# Módulo Financeiro — Contas a Pagar

Este documento descreve a arquitetura, rotas e fluxos principais do módulo Financeiro (Contas a Pagar), incluindo o comprovante de pagamento e conciliação bancária.

## Visão Geral

- Persistência em tabelas `contas_pagar`, `contas_pagar_pagamentos`, `contas_pagar_aprovacoes`.
- RBAC aplicado via `AuthMiddleware` e `Rbac` nas rotas HTML e API.
- Token JWT HS256 com `tenant` para multi-tenant; o tenant é validado em cada requisição.
- Conciliação bancária integrada via stub `BankIntegrationStub` (simula confirmação de liquidação).

## Rotas HTML

- `GET /financeiro/pagar` — Lista de Contas a Pagar.
- `GET /financeiro/contas-pagar/{id}/comprovante` — View de comprovante de pagamento.

Ambas são protegidas por `AuthMiddleware::requireAuthHtml()` e permissões RBAC (ex.: `financeiro.read`).

## Rotas API (Contas a Pagar)

- `GET /api/financeiro/contas-pagar` — Lista contas (query filtros opcionais).
- `POST /api/financeiro/contas-pagar` — Cria conta.
- `PUT /api/financeiro/contas-pagar/{id}` — Atualiza conta.
- `POST /api/financeiro/contas-pagar/{id}/pagar` — Registra pagamento da conta.
- `GET /api/financeiro/contas-pagar/{id}/historico` — Histórico de pagamentos.
- `POST /api/financeiro/contas-pagar/{id}/aprovar` — Aprovação multi-nível (campos: `level`, `status='aprovado'|'rejeitado'`, `notes`).
- `POST /api/financeiro/contas-pagar/{id}/conciliar` — Conciliação bancária (campo: `reference`).

## Automação de Vencidos

Para garantir que contas pendentes sejam marcadas como `vencido` quando a `data_vencimento` passa, foi adicionado um script de rotina:

- Executável: `scripts/financeiro_update_due.php`
- Funções:
  - Atualiza `status = 'vencido'` para contas com `status = 'pendente'` e `data_vencimento < CURDATE()`.
  - Dispara notificações de vencimento próximo via método `notifyDue(days)`.
- Uso (Windows PowerShell):
  - `php scripts/financeiro_update_due.php` — roda no tenant `default` e `days = 5`.
  - `php scripts/financeiro_update_due.php --tenant=acme --days=3` — roda para tenant `acme` e notifica vencimentos em até 3 dias.
  - `php scripts/financeiro_update_due.php --dry-run` — apenas exibe quantas contas seriam atualizadas.

Agende a execução diária via Tarefas Agendadas no Windows (Task Scheduler) ou cron (Linux), preferencialmente no início do dia.

Todas exigem JWT válido em `Authorization: Bearer <token>` e `x-tenant-id` correspondente.

## Comprovante de Pagamento

- View `views/financeiro/contas-pagar/comprovante.php` exibe detalhes da conta, pagamentos e ações.
- Botão de impressão e ação de conciliação disponíveis quando `status` for `pago`.
- Navegação adicionada na lista de Contas a Pagar com ícone de recibo.

## Conciliação Bancária (Stub)

- Serviço: `modules/Financeiro/Services/BankIntegrationStub.php` com `confirmSettlement($reference)`.
- Resposta inclui `bank`, `reference`, `status`, `confirmed_at`; usado para enriquecer logs e resposta.

## Padrões de Controller

- Acesso ao corpo: `is_array($request->body) ? $request->body : []` (evita uso de métodos inexistentes).
- Parâmetros de rota: obtidos via `$request->get('params', [])` preenchidos pelo `Router`.
- Auditoria: `AuditLogger::logUpdate()` e `logRead()` com arrays; evitar `null` em `oldData`.

## Autenticação e Tenant

- O layout `_layout.php` injeta automaticamente `Authorization` e `x-tenant-id` em `apiRequest`.
- 401 dispara tentativa de impersonação automática via `admin_token` (se presente) para o tenant atual.

## Testes de Integração

- `tests/FinanceiroContasPagarFlowTest.php` cobre: criação → aprovações → pagamento → histórico → render da view comprovante → conciliação.
- Usa JWT com bypass de RBAC e valida rotas em português (`/aprovar`, `/historico`, `/conciliar`).

## Próximos Passos

- Substituir o stub bancário por integração real.
- Expandir casos de teste cobrindo erros e permissões.