# 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)