# Kosm Client Space

Portal de acompanhamento de projetos da Kosm Digital: área do cliente + painel administrativo.
PHP 8.2+, MySQL/MariaDB (PDO), HTML/CSS/JavaScript puro. Sem frameworks, Composer, Node ou build.

## Requisitos

- PHP 8.2 ou superior com as extensões `pdo_mysql`, `mbstring` e `fileinfo`
- MySQL 8+ ou MariaDB 10.4+
- Apache (com `mod_rewrite`) ou Nginx

## Instalação

1. Envie o projeto para o servidor. **O document root do domínio deve apontar para a pasta `public/`.**
   Tudo fora dela (código, `.env`, `storage/`) fica inacessível pela web.
2. Crie o banco e o usuário:
   ```sql
   CREATE DATABASE kosm_client_space CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'kosm'@'localhost' IDENTIFIED BY 'SENHA_FORTE';
   GRANT ALL ON kosm_client_space.* TO 'kosm'@'localhost';
   ```
3. Importe a estrutura: `mysql -u kosm -p kosm_client_space < database/schema.sql`
4. Copie `.env.example` para `.env` e preencha `APP_URL`, `DB_*` (e SMTP, se desejar). Nunca versione o `.env`.
5. Permissões: o usuário do servidor web (ex.: `www-data`) precisa gravar em `storage/`:
   ```bash
   chown -R www-data:www-data storage
   chmod -R 750 storage
   ```
6. Crie o primeiro administrador (pede a senha sem exibi-la):
   ```bash
   php bin/create-admin.php "Seu Nome" voce@kosm.com.br
   ```
   Pode ser executado novamente para criar outros administradores.
7. Acesse `APP_URL/login`.

### Nginx

```nginx
root /var/www/kosm-client-space/public;
location / { try_files $uri /index.php?$query_string; }
location ~ \.php$ { include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root/index.php; fastcgi_pass unix:/run/php/php8.2-fpm.sock; }
client_max_body_size 30m;
```

### Limites de upload

`MAX_UPLOAD_MB` (no `.env`) define o limite por arquivo, mas o PHP também limita. Ajuste no `php.ini`:
`upload_max_filesize = 30M`, `post_max_size = 100M`, `max_file_uploads = 20`.

## SMTP (opcional)

Preencha `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE` (`tls` porta 587, `ssl` porta 465, `none`), `SMTP_USER`, `SMTP_PASS`, `MAIL_FROM` no `.env`.
Com SMTP vazio, todo o sistema funciona; apenas os e-mails (notificações e recuperação de senha) deixam de ser enviados.
Nesse caso o administrador pode redefinir a senha do cliente em **Clientes**. Com `APP_ENV=local`, os e-mails são gravados em `storage/logs/mail.log`.
Em produção use sempre `APP_ENV=production`.

## Identidade visual e logo

Paleta: preto `#191919`, bege `#F1EDE9` e branco. Tipografia: Archivo em todo o sistema (fonte variável, hospedada em `public/assets/fonts/`, licença OFL incluída), com Inter e fontes do sistema como alternativa. Para trocar, altere `--sans` e o `@font-face` no topo do CSS.
A logo deve ser colocada em `public/assets/images/` (veja o `LEIA-ME.txt` da pasta): `logo-light.svg` (versão clara, para fundos pretos), `logo-dark.svg` (versão escura) ou apenas `logo.svg` (tratada como escura e invertida automaticamente sobre o preto). Sem arquivo, aparece o nome "Kosm" em tipografia.
Os tokens de design (cores, raios, espaçamentos) ficam no topo de `public/assets/css/app.css`.

## Arquitetura

```
app/Core         Router, Auth, Csrf, Db (PDO), View, Env
app/Controllers  AuthController, ClientController, AccountController, FileController, Admin/*
app/Models       Project, Request, Message (consultas reutilizadas)
app/Services     Uploader (validação e gravação), Notifier, Activity (histórico), Mailer (SMTP)
app/Helpers      functions.php (escape, datas, rótulos, CSRF, flash)
config/          app, database, mail (lidos do .env)
database/        schema.sql
public/          index.php (front controller), assets/css, assets/js
resources/views  layouts, partials, auth, client, admin
routes/web.php   todas as rotas
storage/         uploads (por projeto), logs — fora da pasta pública
```

### Módulos

- **Autenticação**: login único; o perfil define o destino. Limite de tentativas (5 por e-mail / 25 por IP em 15 min), sessão regenerada no login, expiração por inatividade (4 h), recuperação por token aleatório (guardado como hash SHA-256, validade de 1 h, uso único).
- **Projetos e cronograma**: etapas livres, reordenáveis, com prazos próprios; modelos reutilizáveis (copiados ao criar o projeto, nunca alteram projetos existentes); pausa com motivo, mensagem e botão de ação exibidos ao cliente; histórico de alterações da previsão com motivo.
- **Materiais**: upload pelo cliente e pela equipe, categorias, observações, arquivos internos (invisíveis ao cliente), progresso de envio.
- **Solicitações**: tipos, responsável, prazo, referências, status, histórico; envio do cliente atualiza o status automaticamente.
- **Aprovações**: versões encadeadas; decisões imutáveis com autor e horário; nova versão só após ajustes/reprovação.
- **Mensagens**: conversa por projeto com anexos; notas internas nunca chegam ao cliente (filtro na consulta SQL e no download).
- **Notificações** no sistema (e por e-mail, se houver SMTP) e **histórico de atividades** com separação interno/visível ao cliente.

## Segurança

- PDO com consultas preparadas (`EMULATE_PREPARES` desligado); saída escapada com `htmlspecialchars`.
- CSRF em todo POST; cabeçalhos CSP (sem scripts/estilos inline), `X-Frame-Options`, `nosniff`.
- O projeto do cliente vem sempre da sessão, nunca de parâmetros da URL (sem IDOR); `/admin` exige perfil admin.
- Um cliente por projeto garantido por `UNIQUE (client_id)` no banco. Projetos arquivados liberam a conta (`client_id` vira `NULL`, o cliente original fica em `former_client_id`).
- Uploads: extensão em lista permitida, MIME real via `finfo` coerente com a extensão, bloqueio de duplas extensões executáveis, SVG com conteúdo ativo rejeitado, nome interno aleatório sem extensão, gravação em `storage/uploads/{projeto}/`, download somente via PHP após checar permissão (arquivo de outro projeto ou interno responde 404).
- Projetos com mensagens, arquivos, solicitações ou aprovações não podem ser excluídos (nem pelo banco: chaves estrangeiras `RESTRICT`); use o arquivamento.

Formatos aceitos: pdf, jpg, jpeg, png, gif, webp, svg, psd, ai, eps, txt, csv, rtf, doc(x), xls(x), ppt(x), odt, ods, odp, zip. Para alterar, edite `Uploader::types()`.

## Verificação realizada

Foram executados 47 cenários automatizados via HTTP contra PHP 8.3 + MariaDB 10.11: login por perfil, bloqueio de `/admin` para cliente, criação de cliente/projeto, vínculo único, etapas, pausa/reativação, previsão com motivo, solicitação + envio, uploads maliciosos recusados, isolamento entre clientes, arquivo interno oculto, fluxo de aprovação com versões, notas internas ocultas, CSRF, limitação de login, recuperação e troca de senha, arquivamento e exclusão protegida.
O envio SMTP real não foi testado (não há servidor SMTP no ambiente de desenvolvimento).

## Modelo de e-mail

Todos os e-mails (recuperação de senha e notificações) usam um modelo HTML com versão em texto puro:

- Visual/HTML: `resources/emails/layout.php` (tabelas e estilos inline, por exigência dos clientes de e-mail)
- Conteúdo por tipo de notificação (rótulo, texto do botão): `app/Services/Notifier.php` (método `email`)
- Recuperação de senha: `app/Controllers/AuthController.php`
- Imagens de cabeçalho e assinatura: `public/assets/images/email/` (veja o `LEIA-ME.txt` da pasta)
- Pré-visualização no navegador, sem enviar nada: `php bin/preview-email.php`

Para um novo e-mail: `Services\Mailer::sendTemplate($para, $assunto, ['eyebrow' => ..., 'heading' => ..., 'name' => ..., 'paragraphs' => [...], 'cta' => ['Texto', $url]])`.
As imagens vão embutidas no e-mail (Content-ID), então aparecem mesmo com a opção "bloquear imagens externas" ativa.

