RECURSOS DESENVOLVIDOS PLENOCRM

gistfile1.txt

# Recursos Desenvolvidos - PlenoCRM MVP

> Inventario consolidado dos recursos ja implementados no CRM Sindical MVP.
>
> Atualizado em: 07/07/2026
>
> Observacao: a pasta `docs/` esta mantida apenas localmente e ignorada pelo Git, conforme decisao anterior do projeto.

## Sumario

1. Arquitetura e base tecnica
2. Seguranca, autenticacao e sessoes
3. Multi-tenant, RBAC e permissoes
4. Administracao master e tenants
5. Frontend publico, login e PWA
6. Filiados e dependentes
7. Portal do filiado
8. Carteirinha digital, QR, PIN e CAPT
9. Parceiros, convenios e beneficios
10. Financeiro
11. Juridico, chamados e processos
12. Saude e agendamentos
13. Comunicacao, documentos, eventos e certificados
14. Auditoria, LGPD, ranking e dados
15. Storage e arquivos
16. Health check, CORS e operacao
17. Testes, CI e E2E
18. Banco de dados e migrations
19. Pendencias e proximos passos

---

## 1. Arquitetura e base tecnica

### Backend

- Backend em Node.js, Express e TypeScript.
- API REST organizada por modulos em `backend/src/modules`.
- Camadas separadas para rotas, middlewares, servicos e integracoes.
- Uso de PostgreSQL como banco principal.
- Scripts de migracao SQL em `database/migrations`.
- Swagger/OpenAPI disponivel para documentacao tecnica da API.
- Tratamento padronizado de erros em JSON com `message` e `code`.
- Organizacao incremental, mantendo regras de negocio importantes no backend.

### Frontend

- Frontend em React, TypeScript e Vite.
- Estrutura por paginas, componentes e modulos funcionais.
- Layout autenticado com sidebar, rotas protegidas e paineis por perfil.
- Portal do filiado separado da area administrativa.
- Uso de Tailwind/CSS do projeto e componentes reutilizaveis.
- PWA com manifesto, service worker e icones.

### Monorepo e scripts

- Projeto organizado em workspaces `backend` e `frontend`.
- Scripts de build, teste e desenvolvimento via npm workspaces.
- Docker Compose para PostgreSQL local.
- Configuracao de CI no GitHub Actions.

---

## 2. Seguranca, autenticacao e sessoes

- Login com JWT.
- Refresh tokens persistidos para restauracao de sessao.
- Logout individual e logout de todas as sessoes.
- Hash de senhas com `bcrypt`.
- Middleware de autenticacao por token.
- Middleware de RBAC por perfil/permissao.
- Rate limit aplicado a rotas sensiveis de autenticacao.
- Helmet configurado no backend.
- Registro de auditoria para login, logout e acessos negados.

### Endpoints principais

- `POST /auth/login`
- `GET /auth/me`
- `POST /auth/refresh`
- `POST /auth/logout`
- `POST /auth/logout-all`

---

## 3. Multi-tenant, RBAC e permissoes

- Separacao de dados por `tenant_id` nas tabelas de negocio.
- Contexto master separado do contexto de tenant cliente.
- Perfis previstos e utilizados:
  - `MASTER`
  - `PRESIDENCIA`
  - `GESTOR`
  - `FINANCEIRO`
  - `JURIDICO`
  - `SAUDE`
  - `PARCEIRO`
  - `FILIADO`
- Tabelas de `roles`, `permissions`, `role_permissions` e `tenant_modules`.
- Controle de acesso no backend por modulo/rota.
- Controle de acesso no frontend com `ProtectedRoute` e regras de secao.
- Restricao do filiado ao portal restrito, sem acesso aos dados administrativos.

---

## 4. Administracao master e tenants

- Cadastro, listagem, edicao e remocao de tenants.
- Tenant com dados cadastrais e sindicais completos (11 campos):
  - Nome e slug.
  - CNPJ.
  - Tipo de entidade: Sindicato / Federacao / Confederacao / Central Sindical / Associacao.
  - Subtipo (para Sindicato): Servidor Publico Municipal / Servidor Publico Estadual / Privado.
  - Ambito: Municipal / Estadual / Nacional.
  - Categoria Sindical: Educacao / Saude / Construcao Civil / Comercio / Industria / Servicos / Transporte / Rural / Outros.
  - Federacao filiada (UUID → tenants.id, filtrado por tipo=federacao).
  - Confederacao filiada (UUID → tenants.id, filtrado por tipo=confederacao).
  - Central Sindical filiada (UUID → tenants.id, filtrado por tipo=central_sindical).
  - Cliente ativo (boolean).
  - Permitir metricas agregadas para entidade superior (boolean).
- Tabela no MasterPanel com colunas: Nome, Slug, Tipo, CNPJ, Status, Cores e acoes.
- Modal de cadastro/edicao no MasterPanel com todos os campos, incluindo selects hierarquicos filtrados.
- Admin do tenant (PRESIDENCIA/GESTOR) pode editar campos da entidade via `/tenant-admin/settings`.
- Resumo da entidade visivel na tela de administracao do tenant (tipo, ambito, categoria, CNPJ).
- Exclusao de tenant com confirmacao por slug e limpeza em cascata controlada.
- Cadastro e gestao de usuarios administrativos por tenant.
- Controle de modulos habilitados por tenant.
- Suporte a branding por tenant (cores, logo).
- Documentacao detalhada em `docs/CADASTRO-ENTIDADE.md`.

---

## 5. Frontend publico, login e PWA

- Landing page publica antes do login.
- Pagina de contato.
- Botao fixo de WhatsApp no rodape da pagina inicial.
- Botao fixo de WhatsApp tambem na pagina de contato, com comportamento alinhado ao da home.
- Login administrativo.
- Login do filiado.
- Login de parceiro.
- Restauração de sessao no frontend.
- Manifesto PWA, icones e service worker.
- Protecoes contra acesso indevido por perfil.

---

## 6. Filiados e dependentes

- CRUD de filiados com 26 campos, organizados em 4 seções:
  - Dados Pessoais: nome, CPF, RG, data de nascimento, estado civil, nacionalidade, foto.
  - Endereço Residencial: cidade, bairro, logradouro, número, complemento, CEP.
  - Vínculo Profissional: empresa/órgão, CNPJ empresa, cidade trabalho, bairro trabalho, setor, cargo, tipo de vínculo, matrícula funcional.
  - Contato: e-mail, telefone, WhatsApp.
- CRUD de dependentes.
- Vinculo de dependentes ao titular.
- Exportacao CSV de filiados.
- Importacao de filiados por PDF com fluxo de preview e aplicacao.
- Edicao de linhas no preview antes da importacao.
- Identificacao de titulares e dependentes no importador.
- Atualizacao nao destrutiva de dados importados.
- Isolamento por tenant nas operacoes de filiados e dependentes.
- Dependentes com servicos autorizados.
- Dependentes com liberacao individual de carteirinha por `card_enabled`.
- Interface administrativa para dependentes no `DependentsPanel`.
- Formulário com fieldsets agrupados por seção no modal de edição.
- Documentação detalhada em `docs/CADASTRO-FILIADO.md`.

---

## 7. Portal do filiado

- Endpoint agregado `GET /portal/me`.
- Portal restrito com dados apenas do filiado autenticado.
- Dashboard do filiado.
- Visualizacao de dados cadastrais.
- Edicao de perfil.
- Alteracao de senha.
- Consulta de dependentes.
- Consulta de carteirinha.
- Consulta de carteirinhas de dependentes liberados.
- Consulta de cobrancas.
- Abertura e acompanhamento de chamados.
- Consulta de processos juridicos vinculados.
- Agendamento de saude.
- Consulta de documentos.
- Consulta de eventos.
- Consulta de certificados.
- Consulta de convenios e beneficios.
- Historico de notificacoes.
- Funcionalidades de LGPD no portal.

---

## 8. Carteirinha digital, QR, PIN e CAPT

- Carteirinha digital para filiado titular.
- Carteirinha digital para dependentes com permissao ativa.
- Geracao de QR Code da carteirinha.
- Validacao por PIN.
- Geracao de PDF da carteirinha com `pdfkit`.
- QR renderizado no frontend com `qrcode.react`.
- Servico centralizado de carteirinha em `backend/src/modules/carteirinhas/card.service.ts`.
- Suporte a validacao por parceiro autenticado.
- Suporte a validacao publica por QR + CAPT.

### CAPT

- Campo `capt_code` em beneficios/convenios de portal.
- Validacao publica sem login:
  - `POST /partner/validate-capt`
  - `POST /carteirinhas/validar-capt`
- Fluxo de validacao por `qr_code + capt_code`.
- Registro de validacoes em `partner_validations`.
- Registro do parceiro, beneficio, filiado, dependente e resultado da validacao.
- Registro de inadimplencia, valor aberto e motivo de negacao quando aplicavel.
- Relatorio de uso da carteirinha:
  - `GET /carteirinhas/relatorios/uso?period=month|quarter|year`
- Agrupamentos por parceiro, periodo, filiado e dependente.
- Tela de parceiro com modo "QR + CAPT".
- Abas administrativas em beneficios para:
  - parceiros CAPT.
  - uso da carteirinha.

---

## 9. Parceiros, convenios e beneficios

- Perfil `PARCEIRO`.
- Login e area de parceiro.
- Validacao de carteirinha por parceiro.
- Historico de validacoes do parceiro.
- Convenios com categoria, regras, cupons, endereco e localizacao.
- Beneficios separados do modulo de convenios.
- Cadastro de categorias de beneficios.
- Cadastro de beneficios.
- Adesoes a beneficios pelo portal.
- Cancelamento de adesoes.
- Beneficios visiveis no portal do filiado.
- Integracao entre beneficios, CAPT e validacao de carteirinha.

---

## 10. Financeiro

- Cadastro e consulta de cobrancas.
- Registro de pagamentos.
- Atualizacao de status financeiro.
- Resumo financeiro por tenant.
- Relatorios de inadimplencia, receita e fluxo de caixa.
- Exportacoes CSV.
- Preview mock de pagamento para cobrancas.
- Reconciliacao manual.
- Correcao de divergencias financeiras.
- Importacao financeira por PDF.
- Preview e aplicacao de importacao de PDFs Uniodonto como cobrancas.
- APIs revisadas para:
  - PIX.
  - boletos.
  - CNAB.
  - folha/payroll.
  - relatorio por IA em modo mock/adaptador.
- Integracao Asaas estruturada por adaptador e rotas dedicadas.
- Integracao Asaas validada em ambiente sandbox com `PAYMENT_PROVIDER=asaas` e `ASAAS_SANDBOX=true`.
- Credenciais e tokens Asaas centralizados em `.env`, sem configuracao sensivel pela interface do sistema.
- Criacao de cobrancas PIX/Boleto no Asaas a partir do financeiro do PlenoCRM.
- Sincronizacao/criacao de cliente Asaas a partir do filiado antes da cobranca.
- Armazenamento do identificador real da cobranca Asaas (`pay_...`) como referencia externa.
- Visualizacao de instrumento de pagamento real da cobranca:
  - QR Code PIX.
  - codigo copia e cola PIX.
  - dados de boleto quando aplicavel.
- Endpoint de visualizacao de cobranca:
  - `GET /financeiro/charges/:id/payment-instrument`
- Webhook Asaas implementado no backend para atualizacao automatica do status da cobranca.
- Baixa automatica validada em sandbox ao marcar cobranca como paga no painel Asaas.
- Conciliacao de pagamento recebida via Asaas com registro em `finance_payments`.
- Fallback de reconciliacao ao visualizar cobranca ja recebida no Asaas.
- Protecao para referencias locais/legadas que nao sejam ids Asaas reais, evitando erro 502 ao visualizar cobrancas antigas ou canceladas.
- Cobrancas canceladas ocultas por padrao na listagem financeira, com opcao "Mostrar canceladas" para consulta historica.
- Credenciais externas mantidas fora do codigo.
- Paineis frontend:
  - `FinanceChargesPanel`.
  - `FinanceReportsPanel`.

### Validacao sandbox Asaas

Fluxos testados e funcionais em sandbox:

- Login com usuario financeiro de tenant de demonstracao.
- Criacao de cobranca manual pelo sistema usando Asaas.
- Emissao de cobranca PIX no Asaas para filiado com CPF valido.
- Retorno do QR Code PIX real e do codigo copia e cola na tela de detalhes da cobranca.
- Consulta da cobranca criada pelo botao "Visualizar".
- Marcacao da cobranca como paga no painel sandbox do Asaas.
- Recebimento/processamento do webhook e atualizacao da cobranca no PlenoCRM.
- Registro do pagamento conciliado no financeiro.
- Ocultacao das cobrancas canceladas de teste por padrao, sem excluir historico.

Observacoes operacionais:

- Em sandbox, manter `ASAAS_SANDBOX=true`.
- Para homologacao publica, o webhook pode usar:
  - `https://app.plenocrm.com.br/financeiro/asaas/webhook`
  - ou `https://plenocrm.com.br/api/financeiro/asaas/webhook`, conforme dominio publicado para a API.
- Em producao real, trocar para credenciais de producao, revisar `ASAAS_SANDBOX=false`, confirmar o webhook no painel Asaas e fazer uma cobranca real de baixo valor antes de liberar para clientes.

### Validacao producao Asaas

Fluxo validado em ambiente de producao em 01/07/2026:

- Criacao de cobranca PIX real pelo PlenoCRM.
- Sincronizacao/criacao do cliente no Asaas usando credenciais de producao.
- Geracao e exibicao do QR Code PIX real.
- Pagamento PIX aceito pelo Asaas.
- Recebimento do webhook de pagamento pelo backend.
- Atualizacao automatica do status da cobranca no PlenoCRM apos webhook.
- Conciliacao do pagamento com registro financeiro.
- Uso exclusivo das credenciais Asaas definidas em `.env` para emissao, webhook e transferencia.
- Parser de booleanos do `.env` ajustado para tratar `ASAAS_SANDBOX=false` como producao real.

### Ajuste mensal de descontos em folha

- Modulo financeiro de conferencia mensal em `/financeiro/descontos-folha`.
- Criacao/listagem de competencias mensais por tenant.
- Importacao do arquivo Excel da prefeitura, com parser para o layout Uniodonto:
  - aba principal `Plan1`.
  - coluna B como matricula funcional.
  - coluna C como nome do associado/dependente.
  - coluna D como tipo do registro.
  - coluna F como valor do desconto.
- Importacao alternativa por linhas JSON normalizadas para testes e operacao assistida.
- Conciliacao automatica por CPF, matricula funcional e nome normalizado.
- Classificacao de itens da conferencia:
  - desconto normal.
  - valor divergente.
  - associado sem desconto.
  - associado novo no relatorio.
  - associado removido/excluido da folha.
  - associado com retroativo acumulado.
  - associado incluido manualmente.
- Inclusao manual de associado na competencia.
- Ajuste de valor com motivo e observacao.
- Bloqueio mensal de desconto com motivo padronizado e opcao de gerar pendencia.
- Exclusao para proximos lancamentos sem apagar historico cadastral/financeiro.
- Criacao de cobranca retroativa para competencia futura.
- Acumulo de multiplas pendencias retroativas sem duplicidade.
- Painel de pendencias acumuladas por associado.
- Listagem individual de pendencias com reprogramacao e cancelamento.
- Fechamento de competencia com lista consolidada de valores finais.
- Reabertura controlada por perfil autorizado.
- Exportacao JSON da lista consolidada.
- Geracao idempotente de lancamentos em `finance_charges` a partir da conferencia fechada.
- Referencia externa de lancamento no formato `payroll-discount-{batchId}-{itemId}` para evitar duplicidade.
- Historico auditavel de importacao, inclusao, ajuste, bloqueio, retroativo, reprogramacao, cancelamento, exclusao futura, fechamento, reabertura e geracao financeira.
- Isolamento por `tenant_id` em todas as operacoes.
- RBAC do modulo:
  - `GESTOR`: acesso total no tenant.
  - `FINANCEIRO`: operacao, importacao, ajustes, fechamento e geracao de lancamentos.
  - `PRESIDENCIA`: consulta, auditoria, fechamento e reabertura autorizada.

Endpoints principais:

- `GET /financeiro/descontos-folha`
- `POST /financeiro/descontos-folha`
- `GET /financeiro/descontos-folha/competencias`
- `GET /financeiro/descontos-folha/pendencias`
- `GET /financeiro/descontos-folha/pendencias/detalhes`
- `PATCH /financeiro/descontos-folha/pendencias/:pendingId/reprogramar`
- `POST /financeiro/descontos-folha/pendencias/:pendingId/cancelar`
- `GET /financeiro/descontos-folha/:batchId`
- `POST /financeiro/descontos-folha/:batchId/import`
- `GET /financeiro/descontos-folha/:batchId/itens`
- `POST /financeiro/descontos-folha/:batchId/itens`
- `PATCH /financeiro/descontos-folha/:batchId/itens/:itemId`
- `POST /financeiro/descontos-folha/:batchId/itens/:itemId/bloquear`
- `POST /financeiro/descontos-folha/:batchId/itens/:itemId/retroativo`
- `POST /financeiro/descontos-folha/:batchId/itens/:itemId/excluir-proximos`
- `POST /financeiro/descontos-folha/:batchId/fechar`
- `POST /financeiro/descontos-folha/:batchId/reabrir`
- `POST /financeiro/descontos-folha/:batchId/gerar-lancamentos`
- `GET /financeiro/descontos-folha/:batchId/historico`
- `GET /financeiro/descontos-folha/:batchId/export`

---

## 11. Juridico, chamados e processos

- Cadastro e acompanhamento de casos juridicos.
- Processos com linha do tempo.
- Tarefas, prazos e anexos juridicos.
- Chamados do portal do filiado.
- Campo obrigatorio de local da ocorrencia em chamados.
- Confirmacao de local da ocorrencia pelo filiado.
- Mapa/agrupamento por zona a partir de `occurrence_location`.
- Historico de notificacoes internas.
- Regra de e-mail implementada:
  - abertura de chamado envia e-mail mock com protocolo.
  - respostas e alteracoes de status ficam no portal e notificacoes internas.
- PDF de chamado no portal:
  - `GET /portal/chamados/:id/pdf`
- Botao no portal para baixar PDF do chamado.

---

## 12. Saude e agendamentos

- Cadastro de profissionais de saude.
- Especialidades.
- Servicos.
- Bloqueios de agenda.
- Agendamentos.
- Confirmacao e cancelamento de agendamentos.
- Historico e calendario.
- Notificacoes relacionadas a agenda.
- Autoatendimento de agendamento no portal do filiado.

---

## 13. Comunicacao, documentos, eventos e certificados

### Comunicacao

- Comunicados por tenant.
- Destinatarios de comunicados.
- Historico de comunicacao.

### Documentos

- Documentos no portal.
- Versoes de documentos.
- Upload e download.
- Metadados de armazenamento.
- URLs assinadas/mock para download privado.

### Eventos

- Cadastro e listagem de eventos com tela admin (`EventsPage.tsx`).
- Eventos gratuitos e pagos (`price_cents`, `is_paid`).
- Data de término do evento (`ends_at`).
- Controle de exigência de pagamento para check-in (`requires_payment_to_checkin`).
- Inscricao em eventos pelo gestor e pelo portal do filiado.
- Check-in com QR Code.
- Validação de pagamento no check-in (verifica `finance_charges.status = 'paid'`).
- Liberação manual de check-in pelo gestor (`checked_in_by = 'gestor'`).
- Certificado digital automático após check-in (com `event_id`).
- PDF de comprovante de inscrição com QR Code.
- PDF de certificado estilizado com QR Code.
- Navegação lateral "Eventos" para GESTOR e PRESIDENCIA.

### Certificados

- Emissao de certificados manual e automática (pós check-in).
- Vínculo do certificado com evento (`event_id` em `portal_documents`).
- Codigo de validacao.
- QR Code.
- PDF de certificado.
- Validacao publica por codigo.

---

## 14. Auditoria, LGPD, ranking e dados

- Logs de auditoria expandidos.
- Auditoria de eventos de autenticacao e acesso negado.
- Rotas de ranking.
- Consentimentos LGPD.
- Exportacao de dados LGPD.
- Anonimizacao prevista/estruturada.
- Importacao e exportacao de dados administrativos.

---

## 15. Storage e arquivos

- Camada de storage abstraida.
- Storage mock/local para desenvolvimento e testes.
- Adaptador para DigitalOcean Spaces.
- Suporte a objetos privados.
- Geração de URLs assinadas.
- Uploads com metadados.

---

## 16. Health check, CORS e operacao

- Endpoint `/health`.
- Health check detalhado com estado do backend e dependencias.
- Health pode retornar estado degradado quando dependencias externas/banco falham.
- Middleware de CORS customizado.
- Suporte a multiplas origens configuradas por ambiente.
- Ajuste para evitar `Access-Control-Allow-Origin` duplicado.
- Compatibilidade entre dominios publicos `plenocrm.com.br` e `app.plenocrm.com.br`.
- Ajuste no CI para aguardar disponibilidade TCP do backend quando `/health` pode estar degradado.

---

## 17. Testes, CI e E2E

### Backend

- Testes com `node:test`.
- Cobertura dos principais fluxos REST.
- Fluxos testados incluem:
  - autenticacao.
  - acesso restrito do filiado.
  - financeiro.
  - importacao de PDFs.
  - juridico/chamados/processos.
  - saude.
  - comunicacao/documentos/carteirinhas.
  - eventos/certificados/convenios.
  - fluxo de negocio completo.
  - ajuste mensal de descontos em folha, incluindo importacao, classificacao, bloqueio com motivo, retroativo, pendencias, exclusao futura, fechamento, geracao idempotente de lancamentos, historico, RBAC e isolamento multi-tenant.
- Ultima validacao local conhecida: 59 testes backend passando.

### Frontend

- Testes com Vitest e Testing Library.
- Ajustes para ambiente de teste:
  - `import.meta.env` protegido.
  - acesso a `document`/`navigator` protegido.
  - import de CSS evitado em teste quando necessario.
  - mocks de HTTP ajustados sem erro de inicializacao do Vitest mocker.
- Ultima validacao local conhecida: 20 testes frontend passando.
- Testes especificos do `PayrollDiscountsPanel` cobrem renderizacao da conferencia, inclusao manual de associado e reprogramacao de pendencia retroativa.

### E2E

- Testes E2E com Playwright.
- Helpers de login real.
- Execucao contra frontend e backend locais.
- Sem dependencia de tokens falsos em `localStorage`.
- Fluxos E2E cobrem login, dashboard, CRUD de filiado, financeiro e portal do filiado.
- Ultima validacao local conhecida: 14 testes E2E passando em modo CI local.

### CI GitHub Actions

- Workflow executa backend, frontend e E2E.
- Backend e frontend sao iniciados para E2E.
- CI aguarda backend por `tcp:localhost:3001`.
- CI aguarda frontend por `http://localhost:5173`.
- Playwright usa `frontend/playwright.config.ts`.

---

## 18. Banco de dados e migrations

- Banco principal PostgreSQL.
- Migrations SQL versionadas em `database/migrations`.
- Migracoes cobrem:
  - tenants.
  - usuarios.
  - sessoes.
  - RBAC.
  - filiados.
  - dependentes.
  - financeiro.
  - juridico.
  - saude.
  - portal.
  - documentos.
  - eventos.
  - certificados.
  - convenios.
  - beneficios.
  - comunicacao.
  - carteirinhas.
  - CAPT.
  - metricas de dependentes/carteirinha.
  - ajuste mensal de descontos em folha.
- Migracao mais recente registrada localmente:
  - `045_payroll_discount_review.sql`

---


---

## Integração Asaas BaaS — Status: ✅ Completo

A integração com o Asaas BaaS (Banking as a Service) está **totalmente implementada** conforme o documento `docs/INTEGRACAO-FINANCEIRA-BAAS.md`. Todos os checklists do documento foram concluídos.

### Arquitetura

```
PlenoCRM (Master API Key)
  └── POST /v3/accounts (cria subconta por sindicato)
        └── Subconta Sindicato (apiKey + walletId próprios)
              ├── POST /v3/payments (PIX / Boleto)
              ├── POST /v3/customers (sync filiado)
              ├── POST /v3/transfers (transferência automática)
              └── Webhook → PlenoCRM (PAYMENT_RECEIVED, PAYMENT_CONFIRMED, etc.)
```

### Arquivos principais

| Arquivo | Responsabilidade |
|---------|-----------------|
| `backend/src/modules/finance/payment.adapters.ts` | Adapter Asaas: `createCharge`, `getPixQrCode`, `getBoletoInfo`, `syncCustomer`, `createSubaccount`, `createTransfer`, `getBalance`, `validateWebhookSignature` |
| `backend/src/shared/crypto.ts` | AES-256-GCM: `encrypt()`, `decrypt()`, `isEncrypted()`, `safeDecryptApiKey()` |
| `backend/src/modules/financeiro/financeiro.routes.ts` | Webhook handler (`POST /financeiro/asaas/webhook`), split de comissão + transferência automática no evento `PAYMENT_CONFIRMED` |
| `backend/src/modules/tenants/tenants.routes.ts` | Criação automática de subconta Asaas ao criar tenant (`criar_subconta_asaas: true`) |
| `backend/src/modules/tenant-admin/tenant-admin.routes.ts` | Máscara da API key (`abcd...wxyz`), criptografia ao salvar nova chave |
| `backend/src/modules/commissions/commissions.routes.ts` | CRUD de regras de comissão, listagem de splits, resumo financeiro, reprocessamento de transferências |
| `database/migrations/043_asaas_financial_tables.sql` | Tabelas: `financial_accounts`, `payment_splits`, `transfers`, `webhook_logs`, `commission_rules` |
| `docs/INTEGRACAO-FINANCEIRA-BAAS.md` | Documento de arquitetura completo com checklist atualizado |

### Criptografia AES-256-GCM

Toda `apiKey` de subconta é armazenada criptografada no banco (`tenant_modules.settings.asaas_api_key`).

```typescript
import { encrypt, decrypt, safeDecryptApiKey, isEncrypted } from '../../shared/crypto.js';

// Ao SALVAR (nunca armazenar em texto puro):
settings.asaas_api_key = encrypt(novaApiKey);

// Ao LER (descriptografa automaticamente, compatível com chaves legadas):
const apiKey = safeDecryptApiKey(settings.asaas_api_key);
```

**Regras de segurança:**
- API key **nunca** é exibida na interface — apenas mascarada como `abcd...wxyz`
- API key **nunca** aparece em logs (`payment_logs`, `audit_log`)
- `getPaymentAdapterForTenant()` descriptografa automaticamente antes de usar
- `maskAsaasApiKey()` descriptografa apenas para exibir os 4 primeiros e 4 últimos caracteres

### Módulo de Comissão (`/commissions`)

Endpoints disponíveis apenas para perfil `MASTER`:

| Método | Rota | Descrição |
|--------|------|-----------|
| `GET` | `/commissions` | Listar todas as regras de comissão |
| `GET` | `/commissions/global` | Regra global (tenant_id = null) |
| `GET` | `/commissions/tenant/:tenantId` | Regra específica de um sindicato |
| `POST` | `/commissions` | Criar/atualizar regra (upsert por tenant_id) |
| `PUT` | `/commissions/:id` | Editar regra existente |
| `DELETE` | `/commissions/:id` | Remover regra (exceto global) |
| `GET` | `/commissions/splits` | Listar splits de comissão (filtros: tenant_id, status, período) |
| `GET` | `/commissions/splits/summary` | Resumo: total bruto, comissão, líquido, quantidade, % médio |
| `GET` | `/commissions/transfers` | Listar transferências (filtros: tenant_id, status) |
| `GET` | `/commissions/transfers/pending` | Transferências com falha aguardando retry |
| `POST` | `/commissions/transfers/:id/retry` | Reprocessar manualmente uma transferência com falha |

**Comportamento padrão:** regra global de 3% fixo é criada automaticamente pela migration 043.

### Fluxo de transferência automática

Quando o Asaas envia o webhook `PAYMENT_CONFIRMED`:

1. Calcula comissão (busca regra do tenant ou global)
2. Registra split em `payment_splits` (gross, commission, net)
3. Cria registro em `transfers` com `status = 'pending'`
4. Chama `POST /v3/transfers` no Asaas
5. Se sucesso: `status = 'processing'`
6. Se falha: `status = 'failed'` + agenda retry com exponential backoff (2, 4, 8, 16, 32, 60 min)

### Variáveis de ambiente necessárias

```env
# Gateway de pagamento (produção: 'asaas', dev: 'mock')
PAYMENT_PROVIDER=asaas

# Asaas — Subconta (usada se não houver tenant_modules configurado)
ASAAS_API_KEY=$ASAAS_SANDBOX_API_KEY
ASAAS_SANDBOX=true
ASAAS_ENVIRONMENT=sandbox

# Asaas — Conta Master (para criar subcontas Marketplace)
ASAAS_MASTER_API_KEY=

# Asaas — Webhook
ASAAS_WEBHOOK_TOKEN=token-configurado-no-painel-asaas
ASAAS_WEBHOOK_ENABLED=false

# Criptografia da API Key (se não definida, usa JWT_SECRET como fallback)
ASAAS_ENCRYPTION_KEY=
```

### Para testar localmente

```bash
# 1. Subir banco
docker compose up -d

# 2. Rodar migrations (inclui a 043 com tabelas financeiras)
cd backend && npm run migrate

# 3. Rodar backend com provider mock (não depende do Asaas real)
PAYMENT_PROVIDER=mock npm run dev

# 4. Rodar testes
cd backend && npx tsx --test src/shared/crypto.test.ts
cd backend && npx tsx --test src/modules/finance/payment.adapters.test.ts
cd backend && npx tsx --test src/app.test.ts
```

### Para usar em produção (sandbox Asaas)

```bash
# Criar tenant com subconta automática:
curl -X POST http://localhost:3333/tenants \
  -H "Authorization: Bearer <master_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sindicato Exemplo",
    "slug": "sindicato-exemplo",
    "cnpj": "12345678000199",
    "email": "financeiro@sindicato.com",
    "criar_subconta_asaas": true
  }'

# O sistema automaticamente:
# 1. Cria subconta no Asaas via POST /v3/accounts
# 2. Criptografa e salva a apiKey no tenant_modules
# 3. Salva walletId e webhook token
# 4. Configura webhook no Asaas
```


## 19. Pendencias e proximos passos

- Manter integracoes externas em padrao adapter/mock-first antes de ativar producao.
- Antes de producao real Asaas: trocar credenciais sandbox por producao, definir `ASAAS_SANDBOX=false`, confirmar URL publica do webhook e executar cobranca real controlada de baixo valor.
- Criar pagina publica dedicada para validacao CAPT, caso o produto exija validacao fora da area autenticada.
- Ampliar testes frontend especificos para abas CAPT e relatorios de uso da carteirinha.
- Adicionar exportacao do relatorio de uso da carteirinha, se necessario.
- Continuar refinando UX visual sem alterar regras de negocio ja protegidas no backend.
- Manter documentacao local atualizada, lembrando que `docs/` nao e versionado no Git neste momento.