# Roadmap — Módulo Financeiro e Comunicação Interna

## 1. Visão Geral

Projeto full-stack em PHP (MVC) + MySQL + Tailwind, respeitando timezone America/Sao_Paulo, moeda BRL (centavos) e políticas de RBAC/Auditoria/LGPD. Objetivo: entregar módulo financeiro completo, conta corrente, débitos programados, mural de comunicação e relatórios executivos, com jobs automáticos e documentação/testes abrangentes.

## 2. Fases de Entrega

### Fase 0 — Fundamentos (Infra & Segurança)
- **Setup**: configuração de ambiente, bootstrap MVC, roteador, migrations base, seed inicial (papéis, admin, configurações).
- **RBAC & Middleware**: autenticação, políticas por papel (Admin, Financeiro Admin, Gestor Comercial, Corretor, Funcionário, Auditoria).
- **Auditoria/LGPD**: camada de logging imutável (operações chave), criptografia de dados sensíveis, versionamento lógico.
- **Tailwind Build**: pipeline de build (npm scripts), layout base responsivo.
- **Test Harness**: configuração PHPUnit, fixtures, helpers de integração.

### Fase 1 — Domínio de Comissões
- **Modelo de Comissão**: entidades para contratos, funding, comissões, estados (PREVISTA→ESTORNADA).
- **Configurações Financeiras (Settings)**: módulo central em *Configurações > Financeiro* com gestão de combinações Banco/Produto/Tabela, percentuais de comissão, repasses por papel (Admin/Corretor/Funcionário) e versionamento das regras aplicadas por dia.
- **Regras “Dia-Cheio”**: serviços para taxa diária, aplicação retroativa, reprecificação idempotente.
- **Pendências/Bloqueios**: validação de funding, conciliação, divergências, contestação, documentação.
- **Jobs D+1/D+2**: geração de relatórios e créditos na wallet; logs e relatórios.
- **Ajustes/Clawback**: lançamento diferencial para linhas pagas/relatadas, estornos negativos.
- **Tests**: unitários (cálculo taxa, bloqueios, clawback) e integração (pipeline funding→wallet).

### Fase 2 — Wallet & Débitos Programados
- **Estrutura da Wallet**: contas por Admin/Corretor, saldos (disponível, hold, total).
- **Operações**: crédito/débito/hold/release, extrato, índices por data/status.
- **Saques**: fluxo solicitar→aprovar→pagar, upload comprovante, bloqueios (conta não validada/saldo≤0).
- **Débitos Programados**: agendamento pontual/recorrente, offset automático (prioridade/FIFO), saldo negativo.
- **Jobs**: processamento recorrente, offset ao creditar, cancelamentos/pausas.
- **Tests**: wallet state machine, offsets, saque bloqueado/liberado, saldo negativo.

### Fase 3 — Cadastros Financeiros & Conciliação
- **Contas Bancárias**: CRUD, upload comprovante, validação por papel (Admin/Corretor), estados.
- **Conciliação**: importação OFX/CSV/API, matching (valor/data/ref), triagem de exceções.
- **Pagamentos Solicitados**: fila Financeiro (aprovar/reprovar/pagar em lote).
- **Compliance**: bloqueios de repasses > 100%, verificações de inconsistência.
- **Tests**: matching, validação de conta, fluxo de pagamento.

### Fase 4 — Comunicação Interna (Mural & Scheduler)
- **Modelo de Mensagem**: público alvo (Admin→Corretores, Corretor→Funcionários), prioridades, pins, ACK opcional.
- **Scheduler**: publicação e expiração automáticas, jobs de ativação.
- **UX do Mural**: dashboards por papel, métricas de leitura/ACK, filtros, anexos/comentários (quando aplicável).
- **Restrições**: visibilidade por papel, mensagens críticas bloqueando fluxos.
- **Tests**: autorização, agendamento, métricas, fluxo de ACK.

### Fase 5 — Experiência Financeira & Relatórios
- **Dashboard Financeiro**: KPIs, fluxo de caixa curto, comissões por status.
- **Listagens**: comissões (filtros, timeline), taxa do dia (log de reprecificação), wallet (saldo/extrato/saques), débitos programados.
- **Relatórios Executivos**: Fluxo de Caixa (D+7/D+30/D+90), DRE, Aging, Orçado×Realizado (seed), KPIs (CAC, LTV, Payback, Margem Bruta, % comissões, taxa de estorno, SLA funding).
- **Documentação**: README abrangente (instalação, cron, env), guias de fluxo.
- **Tests**: smoke tests de UI (Cypress ou PHPUnit com BrowserKit), geração de relatórios, exportações.

## 3. Riscos & Mitigações
- **Complexidade das Regras**: definir DDD claro (services para cálculos, jobs isolados); testes em pirâmide.
- **Performance**: índices por status/data, batch jobs, filas; monitoramento de long-running jobs.
- **LGPD/Auditoria**: criptografia, logs WORM, políticas de acesso; revisão de segurança.
- **UX/Tailwind**: biblioteca de componentes reutilizáveis; consistência visual e dark mode existente.

## 4. Entregáveis Adicionais
- Migrações MySQL (estruturas + índices).
- Seeds iniciais (papéis, usuários, configurações).
- Scheduler/cron scripts (jobs D+1/D+2, mural, débitos).
- Scripts de build (Tailwind, assets).
- Postman Collection/Insomnia para APIs financeiras.
- Plano de observabilidade (logs, alertas jobs).

## 5. Próximos Passos
1. Aprovar roadmap e alocar sprints (estimativa inicial: 5 fases / 8-10 sprints).
2. Iniciar Fase 0 com setup infra, RBAC e auditoria.
3. Formalizar critérios de aceitação detalhados por fase e registrar no tracker interno.