SeConectai_Vendas/Etapas/03-painel-master-tenants.md

Etapa 3/8 — Painel Master: Tenants, Planos e Faturas

Contexto do projeto

Continuação do SeConectai Vendas. Etapas anteriores entregaram: setup do projeto (Docker/Prisma/schema) e autenticação completa (login master/tenant, JWT, RLS, guards MasterGuard/TenantGuard/RolesGuard).

Esta etapa implementa a parte do painel master relacionada à gestão comercial da própria plataforma: cadastro dos tenants (seus clientes), planos vendidos, e cobrança da mensalidade deles.

Todos os endpoints desta etapa são protegidos por MasterGuard.

Objetivo desta etapa

CRUD completo de planos e tenants, geração e controle de tenant_faturas (mensalidades), e endpoints de consulta para o dashboard do master (quantos tenants ativos, inadimplentes, faturamento previsto etc).

Tarefas

1. Módulo planos (src/modules/planos/)

   • CRUD completo (GET/POST/PUT/DELETE /master/planos).
   • Validação: valor_mensal > 0; limites (limite_customers, limite_usuarios, limite_instancias_whatsapp) opcionais, mas se informados devem ser > 0.
   • Não permitir excluir plano em uso por algum tenant ativo — apenas desativar (ativo = false).

2. Módulo tenants (src/modules/tenants/)

   • POST /master/tenants — cria tenant com status inicial trial, associa a um plano, define trial_expira_em (ex: hoje + 14 dias, configurável), e cria automaticamente o primeiro usuário tenant_admin desse tenant (nome, e-mail e senha provisória informados no payload, ou senha gerada e enviada por e-mail — por ora, retornar a senha provisória na resposta, o envio de e-mail é de etapa futura).
   • GET /master/tenants — listagem com filtros por status, busca por nome/documento, paginação.
   • GET /master/tenants/:id — detalhe do tenant, incluindo plano, últimas faturas, quantidade de usuários/customers/vendas (agregados).
   • PUT /master/tenants/:id — atualizar dados cadastrais, plano, status.
   • PATCH /master/tenants/:id/status — transição explícita de status (ativo, suspenso, cancelado, inadimplente), registrando em audit_logs. Regra: mudar para suspenso ou cancelado deve também bloquear login dos tenant_users daquele tenant (checar status do tenant no login e no TenantGuard).

3. Módulo tenant_faturas (dentro de tenants ou módulo próprio)

   • Geração automática mensal: um job (pode ser um endpoint manual por enquanto, POST /master/faturas/gerar-mes, já preparando estrutura para virar cron na Etapa 7) que cria, para cada tenant ativo, uma linha em tenant_faturas referente ao mês corrente, com vencimento calculado a partir de dia_vencimento_mensalidade, evitando duplicar (respeitar o UNIQUE(tenant_id, referencia)).
   • GET /master/faturas — listagem com filtros por status, tenant, período.
   • PATCH /master/faturas/:id/marcar-pago — marca fatura como paga (pago_em = now()), e se o tenant estava inadimplente, volta para ativo.
   • Regra: se uma fatura passa do vencimento sem pagamento, marcar como atrasado (pode ser endpoint manual por ora, POST /master/faturas/atualizar-atrasadas, que também vira job na Etapa 7) e mudar tenants.status para inadimplente.

4. Dashboard do master

   • GET /master/dashboard retornando: total de tenants por status, MRR (soma de valor_mensal dos planos dos tenants ativos), total recebido no mês corrente, total em aberto (tenant_faturas com status pendente ou atrasado).

5. Auditoria

   • Toda criação/alteração de tenant, plano ou fatura grava uma linha em audit_logs (usuario_tipo='master', acao, entidade, entidade_id, detalhes em JSON com o diff relevante).

Critérios de aceite

• CRUD de planos funcional e validado
• Criar tenant também cria o primeiro tenant_admin funcional (login testado)
• Listagem de tenants com filtro por status e busca funciona
• Mudar status do tenant para suspenso/cancelado bloqueia login dos usuários daquele tenant (testar tentativa de login após suspensão)
• Geração de faturas do mês não duplica fatura já existente para o mesmo tenant/referência
• Marcar fatura como paga reverte tenant inadimplente → ativo
• Marcar fatura como atrasada muda tenant para inadimplente
• Dashboard retorna números corretos (conferir manualmente com dados de teste)
• Todas as ações relevantes aparecem em audit_logs
• Todos os endpoints desta etapa são inacessíveis com token de tenant_user (testar)