first commit

2026-08-14 17:35:24 -03:00
commit 04472fcd2b
118 changed files with 19173 additions and 0 deletions
@@ -0,0 +1,87 @@
+# Etapa 8/8 — Personalização (Whitelabel) e Ajustes Finais
+
+## Contexto do projeto
+
+Etapa final do **SeConectai Vendas**. Todo o backend de negócio já está
+pronto: auth com RLS, painel master (tenants/planos/faturas), integrações
+WhatsApp/e-mail, customers/produtos, vendas/parcelas/dashboards, e o
+motor de alertas automatizado.
+
+Esta etapa cobre a personalização visual por tenant (whitelabel) e uma
+revisão geral de segurança/qualidade antes de considerar o backend pronto
+para receber um frontend.
+
+## Tarefas
+
+1. **Upload e gestão de logo**
+   - `POST /tenant/perfil/logo` (`TenantGuard`, role `tenant_admin`) —
+     recebe upload de imagem (multipart), valida tipo (`png`/`jpg`/`svg`)
+     e tamanho máximo (ex: 2MB), armazena (definir estratégia: volume
+     Docker local para MVP, com estrutura pronta para trocar por S3/
+     object storage depois — abstrair atrás de um `StorageService` com
+     interface clara) e atualiza `tenants.logo_url`.
+   - `DELETE /tenant/perfil/logo` — remove logo, volta ao padrão da
+     plataforma.
+   - `PUT /tenant/perfil/cor` — atualiza `tenants.cor_primaria` (validar
+     formato hex `#RRGGBB`).
+   - `GET /tenant/perfil` — retorna dados de personalização atuais
+     (logo_url, cor_primaria, nome_fantasia) para o frontend montar o
+     tema.
+   - Endpoint público (sem auth, ou com auth leve): `GET
+     /public/tenants/:slugOuId/tema` — para a tela de login do tenant já
+     carregar logo/cor antes do usuário autenticar (avaliar se precisa
+     de um campo `slug` único e amigável em `tenants`; se sim, criar
+     migration incremental para adicionar essa coluna).
+
+2. **Revisão de segurança geral**
+   - Checklist a validar/corrigir no código existente:
+     - Rate limiting está ativo em todos os endpoints de auth e nos
+       endpoints públicos.
+     - CORS configurado explicitamente (não `*`) — origem(ns) do
+       frontend via variável de ambiente.
+     - Helmet (`@nestjs/helmet` ou `helmet` direto) configurado para
+       headers de segurança padrão.
+     - Nenhum segredo (API keys, senhas SMTP, `ENCRYPTION_KEY`,
+       `JWT_SECRET`) hardcoded ou logado em texto puro em nenhum lugar do
+       código.
+     - Todos os inputs de API validados via DTOs com `class-validator`
+       (checar que nenhum endpoint aceita payload sem validação).
+     - Paginação obrigatória (com limite máximo) em todas as listagens,
+       para evitar consultas sem limite.
+
+3. **Documentação da API**
+   - Configurar Swagger/OpenAPI (`@nestjs/swagger`) documentando todos os
+     endpoints das 8 etapas, agrupados por módulo/tag, com exemplos de
+     request/response e indicação clara de quais exigem `MasterGuard` vs
+     `TenantGuard`.
+
+4. **Ambiente de produção**
+   - Revisar `Dockerfile` e `docker-compose.yml` para produção:
+     - Imagem final enxuta (multi-stage, sem devDependencies).
+     - Variáveis sensíveis via secrets/env, nunca commitadas.
+     - Healthchecks configurados em todos os serviços.
+     - Documentar no README o processo de deploy (build, migrations em
+       produção, rodar migration de policies RLS, subir worker
+       separadamente do web).
+
+5. **Testes finais de ponta a ponta**
+   - Escrever um teste E2E que cobre o fluxo completo mínimo: master
+     cria tenant → tenant faz login → cadastra customer e produto → faz
+     uma venda com parcelas → marca uma parcela como paga → confere
+     dashboard financeiro refletindo o pagamento.
+
+## Critérios de aceite
+
+- [ ] Upload/remoção de logo e alteração de cor funcionam e refletem em
+      `GET /tenant/perfil`
+- [ ] Endpoint público de tema retorna logo/cor sem exigir autenticação
+- [ ] CORS, Helmet e rate limiting revisados e ativos
+- [ ] Nenhum segredo aparece em log ou resposta de API (revisão manual)
+- [ ] Swagger disponível (ex: `/docs`) cobrindo todos os módulos, com
+      guards indicados
+- [ ] Build de produção do Docker gera imagem sem dependências de
+      desenvolvimento
+- [ ] Teste E2E do fluxo completo passa do início ao fim
+- [ ] README final consolidado: como rodar em dev, como fazer deploy em
+      produção, como rodar migrations (incluindo policies de RLS) em um
+      ambiente novo