Construir uma camada operacional sobre a fonte financeira externa, não um substituto

Contexto#

A GoldCash, uma operação familiar de crédito, mantém seus registros financeiros na Fomentis, um sistema externo que é a autoridade da operação sobre os fatos financeiros. A operação precisava de uma visão confiável da carteira e do que exigia trabalho de cobrança. Os dados estavam disponíveis como exports periódicos em planilha.

O que se sabia no momento da decisão (especificação de produto v0.1, 17/08/2026): o sistema operacional é dono dos fatos operacionais; o Receiva importaria e validaria exports e acrescentaria uma interpretação gerencial separada. O contrato de origem nomeado Fomentis/GoldCash foi formalizado depois.

Problema#

Como o Receiva deve se relacionar com o sistema que já guarda a verdade financeira?

Restrições#

• O sistema financeiro continua em uso e continua sendo a autoridade.
• O caminho implementado pelo Receiva para consumir esses dados usava exports periódicos em arquivo.
• As fontes têm naturezas diferentes, incluindo evidência reconstruída à mão.
• Um engenheiro, dentro de uma operação pequena que não podia parar para migrar.
• Os arquivos de origem contêm dados pessoais dos clientes da operação.

Evidências#

As referências técnicas abaixo vêm do repositório privado do Receiva. Estão preservadas como proveniência para auditoria, não como links públicos.

• docs/product/product-spec-v0.1.md §45–50 (propriedade da fonte), §70, §86 (exports periódicos XLSX/CSV), §242–251 (fora de escopo: CRM de cobrança, substituição do sistema de origem, escrita de volta).
• docs/product/mvp-scope-v0.1.md §11–13: o sistema operacional continua sendo a fonte de verdade; o Receiva é uma camada posterior.
• docs/product/financial-safety-gate-v2.1.md §5: a Fomentis continua sendo a fonte financeira autoritativa; o Receiva não sincroniza com ela.
• Migração 20260818230000_financial_safety_gate_v21: trigger no banco que impede alteração e exclusão nas tabelas de origem aceitas.
• src/lib/import/source-contract.ts: contrato de origem FOMENTIS / GOLDCASH.

Escopo de validação: a decisão é confirmada pelas evidências de implementação acima. O uso diário na operação é relato do próprio autor, não um registro medido.

Alternativas consideradas#

A especificação registra as opções rejeitadas como exclusões explícitas, não como uma comparação pontuada. A avaliação abaixo foi escrita agora e está identificada como tal.

1. Substituir o sistema financeiro. Daria controle total do modelo. Excluída: risco de migração para uma operação que precisa continuar rodando, e a autoridade financeira passaria para um sistema novo e não comprovado.
2. Sincronizar e escrever de volta. Manteria os dois sistemas alinhados automaticamente. Excluída: o Receiva poderia alterar a verdade financeira, e exigiria uma integração que o Receiva não tinha.
3. Construir um CRM de cobrança como sistema principal. Cobriria o acompanhamento rapidamente. Excluída: criaria um segundo registro da carteira, concorrente do primeiro.
4. Camada posterior sobre imports imutáveis. Selecionada.

Decisão#

O Receiva é uma camada operacional posterior. Ele importa exports completos, armazena-os como observações imutáveis, reconcilia, publica posições coerentes e mantém seu próprio estado operacional separado. Nunca escreve no sistema financeiro.

Consequências#

Positivas:

• A verdade financeira tem um único dono; o Receiva não pode corrompê-la.
• Todo número pode ser rastreado até arquivo, período e linha.
• A operação adotou o sistema sem substituir nem migrar para fora do sistema financeiro de origem.
• Recursos operacionais (entidades de cobrança, regras de reabertura) foram adicionados sem tocar nos dados de origem.

Negativas:

• A atualização depende da cadência dos exports, e o import é um passo manual.
• Ações feitas no Receiva não voltam para o sistema financeiro.
• Algumas rotinas continuam manuais (fechamento diário).
• A identidade dos registros de origem precisa ser mantida por identidades duráveis, e não por chaves estrangeiras.

Trade-offs#

Aceito: imports manuais, ausência de escrita de volta e armazenamento duplicado das posições de origem, em troca de integridade, sem substituir nem migrar para fora do sistema financeiro de origem. Adiado: integração por API (o motivo específico não foi registrado além do adiamento de escopo). Fora desta decisão: identidade individual de usuário, que segue como uma lacuna aberta separada.

Evidências posteriores à decisão#

• 18/08/2026: trigger contra mutação da origem adicionado.
• 28/08/2026: entidades de cobrança e reabertura automática implementadas sobre o estado separado (commit 3e5a4d6).
• Leituras por posição publicada: OperationalState.currentPublishedPositionId.

Aplicabilidade (interpretação)#

Quando uma empresa depende de um sistema que não vai trocar, a primeira pergunta é se o problema é o sistema ou a falta de uma visão confiável sobre ele. Uma camada de leitura com origem preservada resolve o segundo sem o custo e o risco do primeiro.