SeConectai_Vendas/Etapas/08-personalizacao-whitelabel.md

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