Voltar para Central de Manuais
# Sisconnect 2.0 - Arquitetura Financeira (Fase 1)
## Contrato de Compatibilidade (Legado x 2.0)
Este documento fixa o contrato técnico de migração financeira.
- Unidade monetária oficial: **centavos (int)**.
- Cálculo oficial: **backend only**.
- Fórmula única de remanescente:
- `remanescente = max(0, (valor_original + juros_multa) - (valor_pago + desconto))`
- Filtros de período:
- usar range index-friendly (`>= inicio`, `<= fim`) com início `00:00:00` e fim `23:59:59`
- **não** usar `DATE(campo)` em `WHERE`.
## Modelo de Domínio (Fase 1)
### Bounded Context: Contas a Receber
- Agregados:
- `ContaReceber` (`app_contas_receber`)
- `Transacao` (`app_contas_receber_transacoes`)
- Suporte:
- `ContaReceberCte` (`app_contas_receber_ctes`)
- `ContaReceberFollowUp` (`app_contas_receber_followup`)
- `ContaReceberHistorico` (`app_contas_receber_historico`)
- `ContaReceberTransacaoLog` (`app_contas_receber_transacoes_logs`)
- `ContaReceberAlerta` (`app_contas_receber_alerta`)
### Bounded Context: Contas a Pagar
- Agregado:
- `ContaPagar` (`app_contas_pagar`)
- Suporte:
- `ContaPagarHistorico` (`app_contas_pagar_historico`)
- `ContaPagarLancamento` (`app_contas_pagar_lancamentos`)
### Bounded Context: Caixa
- `FluxoCaixa` (`app_fluxo_caixa`)
- `ContaBancaria` (`app_contas`)
## Mapeamento de Casos de Uso para Tabelas
### Receber
1. **Faturar CTe**
- `app_contas_receber`
- `app_contas_receber_transacoes`
- `app_contas_receber_ctes`
- `app_contas_receber_historico`
- fontes: `app_ctes`, `app_coletas`, `app_clientes`
2. **Liquidar transação**
- `app_contas_receber_transacoes` (baixa)
- `app_contas_receber_transacoes_logs` (auditoria da baixa)
- `app_contas_receber_historico` (histórico da fatura)
- `app_fluxo_caixa` (entrada)
- `app_contas` (saldo)
3. **Estornar transação**
- `app_contas_receber_transacoes`
- `app_contas_receber_historico`
- `app_fluxo_caixa` (saída de estorno)
- `app_contas` (saldo)
### Pagar
1. **Criar conta/parcelas**
- `app_contas_pagar`
- referências: `app_fornecedores`, `app_tipo_despesa`, `app_centro_custos`, `app_unidades`
2. **Liquidar conta**
- `app_contas_pagar`
- `app_contas_pagar_lancamentos`
- `app_fluxo_caixa` (saída)
- `app_contas` (saldo)
3. **Estornar conta**
- `app_contas_pagar`
- `app_contas_pagar_lancamentos`
- `app_fluxo_caixa` (entrada de estorno)
- `app_contas` (saldo)
## Matriz de Compatibilidade Legado x 2.0 (Fase 1)
- `valor`, `valor_pago`, `valor_desconto`, `valor_juros_multa`, `valor_remanescente`: **int centavos** no banco e service.
- `descricao` em pagar: preservado como campo oficial.
- status receber:
- transação: `emitido`, `parcial`, `pago`, `cancelado`, `perdido`
- cte vinculado: `paga` (0,1,2,3) mantido
- status pagar:
- `pendente`, `parcial`, `pago`, `estornado` (em lançamento)
## Query Layer e Performance (Fase 1)
- paginação real no banco (`offset/limit`) para receber e pagar.
- sem agregação por JOIN em listagens transacionais.
- agregações com `SUM` em tabela alvo e filtros explícitos.
## Plano de Migração Sem Regressão
1. **Fase 1 (atual)**
- cálculo central único (`FinanceiroCalculoService`)
- Money VO (`app/core/money.py`)
- integração em receber/pagar
- escrita de logs/lançamentos obrigatórios
2. **Fase 2**
- conciliação unificada via `vw_contas_receber_pagar`
- padronização de filtros por conta/período
3. **Fase 3**
- relatório + CSV/PDF usando mesma camada de consulta/cálculo da API
- testes de snapshot e matriz tela/api/csv/pdf
## Atualizacao Fase 2 (iniciada)
- Endpoints adicionados:
- `GET /api/v1/financeiro/fluxo-caixa`
- `GET /api/v1/financeiro/conciliacao`
- Filtros padronizados por range index-friendly:
- `normalizar_periodo(data_ini, data_fim)` => `00:00:00` a `23:59:59`
- Conciliação baseada em `vw_contas_receber_pagar`:
- fallback seguro quando a view nao existir
- cálculo de remanescente sempre recalculado no backend (fonte única)
- Paginação real no banco também aplicada para listagens.
## Atualizacao Fase 3 (implementada)
- Camada unica de relatorio criada:
- `app/services/financeiro_relatorio_service.py`
- Endpoints unificados:
- `GET /api/v1/financeiro/relatorios/receber?formato=json|csv|pdf`
- `GET /api/v1/financeiro/relatorios/pagar?formato=json|csv|pdf`
- A mesma base de dados/consulta alimenta:
- API (json)
- CSV
- PDF
- Tratamento de resultado vazio:
- CSV retorna cabecalho sem erro
- PDF renderiza mensagem de "Nenhum resultado"
- Snapshot base de exportacao:
- testes em `tests/test_financeiro_relatorio_service.py`
## Atualizacao Operacional - Cadastros (2026-04)
### Clientes - integracao de consulta externa
- Novos endpoints de suporte no contexto de clientes:
- `GET /api/v1/clientes/consulta-cnpj/{cnpj}` (BrasilAPI)
- `GET /api/v1/clientes/consulta-ie/{documento}` (Consultar.IO)
- `GET /api/v1/clientes/auxiliares-cadastro`
- Objetivo:
- reduzir erro manual de cadastro;
- autopreencher dados cadastrais e de endereco;
- obter `inscricao_estadual` por consulta externa.
- Regra funcional:
- quando a consulta de IE nao retornar registro valido, o preenchimento padrao e `ISENTO`.
- Seguranca/operacao:
- token de IE consumido por variavel de ambiente (`CONSULTAR_IO_TOKEN`);
- sem dependencia de `.env` local em producao (configurado em `apprunner.yaml`).
### Fornecedores - robustez para base legada
- `PUT /api/v1/fornecedores/{id}` adaptado para tolerar divergencia de schema:
- atualiza apenas colunas existentes em `app_fornecedores` (checagem dinamica);
- sincronizacao de contatos tratada como opcional para nao bloquear update principal.
- Resultado esperado:
- edicao de cadastro antigo sem regressao, mesmo quando houver colunas/tabelas auxiliares divergentes.
### Frontend de clientes - padronizacao de UX
- Formulario reorganizado por abas:
- `Dados Gerais`, `Contatos`, `Endereco`, `Financeiro`, `Observacoes`.
- Endereco com exibicao por nome (cidade/estado/pais), mantendo IDs internos para persistencia.
- Financeiro com listas nominais para grupo/canal/vendedor/aeroporto.
- Disparos de consulta por documento:
- automatico (`change`, `blur`, `Tab`, `Enter`) e botao manual.
### Contrato de nao regressao (cadastros)
- Nenhuma automacao externa grava dados sozinha no banco.
- Persistencia so ocorre em `SALVAR/ATUALIZAR`.
- Em caso de indisponibilidade das APIs externas, o fluxo manual permanece operacional.
## Riscos e Mitigação
- risco: divergência de status legado em tabelas históricas.
- mitigação: logs de transação e histórico de conta em toda baixa/estorno.
- risco: inconsistência entre cálculo enviado pelo frontend e backend.
- mitigação: backend recalcula remanescente sempre; frontend apenas exibe.
- risco: duplicação por JOIN em relatórios.
- mitigação: fase 2/3 com query service dedicado e testes de consistência.