Arquitetura

​

Visão geral da arquitetura

​

Contextos delimitados

• Configuração: o que você concilia (contextos, fontes, mapas de campos, regras)
• Discovery: conexões com fontes de dados externas, detecção de schema e orquestração de extração com o motor de extração embutido do Matcher
• Ingestão: entrada dos dados (parsing, validação, normalização)
• Correspondência: o motor (execução de regras, pontuação de confiança)
• Exceção: tratamento de itens não conciliados (workflow, roteamento, resolução)
• Governança: trilhas de auditoria (logs imutáveis para conformidade)
• Relatórios: visibilidade (relatórios, exportações, dashboards)

​

Configuração

• Contextos (o que você concilia)
• Fontes (de onde os dados vêm)
• Mapas de campos (tradução de campos externos)
• Regras (como corresponder)

• ReconciliationContext: o escopo da conciliação
• ReconciliationSource: configuração da fonte
• FieldMap: regras de tradução de campos
• MatchRule: lógica de correspondência

​

Discovery

• Gerenciar conexões com fontes de dados externas
• Detectar e guardar em cache os schemas das fontes
• Rodar extrações no próprio processo e entregar os resultados direto para a Ingestão
• Acompanhar os ciclos de vida de conexão e de extração

• FetcherConnection: conexão com fonte externa gerenciada localmente pelo motor de extração
• ExtractionRequest: acompanha um ciclo de vida de extração rodado pelo motor embutido

​

Ingestão

• Fazer o parse dos arquivos enviados (CSV, JSON, XML)
• Validar os dados recebidos contra os schemas configurados
• Normalizar dados externos em uma representação canônica
• Detectar e tratar registros duplicados
• Emitir eventos de domínio quando a ingestão termina

• IngestionJob: acompanha o ciclo de vida e o status da ingestão
• Transaction: registro canônico e normalizado de transação

• ingestion.completed: indica que os dados estão prontos para a correspondência

​

Correspondência

• Carregar as regras aplicáveis a um contexto de conciliação
• Executar estratégias de correspondência (exata, por tolerância, difusa, por data)
• Calcular pontuações de confiança
• Criar grupos de correspondência e alocar transações
• Identificar transações não conciliadas

• MatchRun: execução de um job de correspondência
• MatchGroup: grupo de transações conciliadas
• MatchItem: alocação de uma transação individual

• match_group.confirmed: um grupo de correspondência foi finalizado
• match_group.unmatched: uma correspondência confirmada antes foi revertida
• transaction.pending_review: um candidato não automático precisa de revisão

​

Gestão de exceções

• Classificar exceções por severidade
• Rotear exceções para times internos ou sistemas externos
• Oferecer suporte a substituições e ajustes manuais
• Acompanhar o status de resolução e os SLAs
• Integrar com ferramentas externas de workflow

• Exception: uma transação não resolvida
• Resolution: resultado do tratamento da exceção
• RoutingRule: lógica de roteamento e escalonamento

• JIRA para acompanhamento de chamados
• ServiceNow para incidentes da Table API
• Webhooks para workflows personalizados

​

Governança

• Registrar em logs de auditoria imutáveis os workflows de mutação auditáveis e instrumentados
• Fornecer histórico de auditoria consultável
• Oferecer suporte a relatórios regulatórios e de conformidade

• AuditLog: registro append-only dos workflows de mutação auditáveis e instrumentados

​

Relatórios

• Gerar relatórios de conciliação
• Expor métricas de dashboard
• Exportar dados de conciliação em vários formatos

• Report: resumo da conciliação
• Dashboard: métricas operacionais agregadas
• ExportJob: execução assíncrona de exportação

​

Fluxo de dados

​

Componentes de infraestrutura

​

Arquitetura de banco de dados

• Resolução de pool por tenant em deploys multi-tenant configurados, para separação de dados
• Consistência forte para o estado de correspondência e de exceção
• Consistência eventual para as visões de relatório

​

Multi-tenancy

• Em deploys multi-tenant com AUTH_PROVIDER=plugin-auth, o Matcher tira a identidade do tenant das claims tenant_id ou tenantId do JWT
• Deploys single-tenant e com autenticação desabilitada usam o tenant padrão configurado
• O Matcher nunca aceita identificadores de tenant vindos dos parâmetros da requisição
• Todo acesso ao banco passa pelo pool de conexões do tenant ativo
• O Matcher restringe automaticamente cada consulta ao tenant ativo

​

Padrões de design

​

Arquitetura hexagonal

context/
├── adapters/
│ ├── http/
│ ├── postgres/
│ └── redis/
├── ports/
├── services/
│ ├── command/
│ ├── query/
│ └── worker/
└── domain/
 ├── entities/
 └── errors/

​

Cqrs-light

• *_commands.go para mutações de estado
• *_queries.go para operações de leitura

​

Padrão outbox

​

Próximos passos