99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# 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)
|