Architecture Decision Document - Chronos Sync Local

Date: 2026-04-11
Project: cobranca-hml
Feature: chronos-sync-local

Context

A feature chronos-titulos homologou a integracao funcional da Travessia na dashboard do cobrador. O proximo problema real nao e mais regra de negocio, e sim abastecimento de dados. O desenho atual consulta a Chronos em tempo real durante requests da dashboard, o que aumenta latencia, amplia risco de timeout e deixa a operacao dependente de uma API externa no momento da leitura.

Esta arquitetura introduz uma base local sincronizada para a Chronos, mantendo ownership no MySQL, enriquecimento no SQL Server e contratos da dashboard compativeis com o modelo atual.

Architectural Decision

Decision

Adotar uma arquitetura de sincronizacao local da Chronos, composta por coleta em lote, persistencia local, reconciliacao incremental e leitura dos endpoints a partir da base sincronizada.

Why

• desacopla a operacao diaria da disponibilidade imediata da API
• reduz tempo de resposta dos grids e indicadores
• torna homologacao mais previsivel
• melhora capacidade de auditoria e reprocessamento

Why not keep realtime-only

Mesmo com otimizacoes de timeout e batching, o desenho realtime-only continua sensivel a:

• oscilacao de rede
• limitacao de throughput da API
• variacao de volume por periodo
• tempo acumulado de ownership, enriquecimento e classificacao no mesmo request

Proposed Components

1. ChronosSyncClient

Responsavel por autenticar e consultar a Chronos em backend-only, com cache tecnico de token e metodos de leitura paginada/lote.

2. ChronosSyncJob

Responsavel por executar carga completa e incremental, controlando:

• janela de processamento
• checkpoints
• idempotencia basica
• tratamento de falha

3. ChronosLocalRepository

Responsavel por persistir e recuperar contratos, parcelas e metadados sincronizados localmente.

4. ChronosSyncAuditRepository

Responsavel por registrar trilha de execucao da sincronizacao:

• tipo de job
• inicio/fim
• status
• quantidades
• mensagem resumida de erro

5. ChronosLocalReadService

Responsavel por expor os dados locais da Travessia para a camada ja existente de consolidacao, mantendo compatibilidade com o contrato TituloConsolidado.

6. TituloConsolidadoService

Ja existente conceitualmente na feature anterior. Continua sendo a camada de classificacao funcional e unificacao Bralar/Travessia, mas agora consumindo Travessia a partir da base local.

Data Strategy

Source of Truth

• SQL Server: continua sendo a base principal da Bralar e fonte de enriquecimento complementar
• MySQL: continua sendo a base de ownership, 30 dias e metadados operacionais internos
• Base local Chronos: passa a ser a fonte operacional da Travessia para leitura da dashboard
• API Chronos: passa a ser a fonte de sincronizacao, nao de leitura realtime da tela

Local Persistence

A arquitetura recomenda persistir pelo menos:

• contrato Chronos
• parcela Chronos
• cpf_cnpj normalizado
• referencias operacionais conhecidas
• timestamps de sincronizacao
• hash ou marcador simples para detectar alteracao relevante

Identity Model

• identidade do titulo Travessia: credit_id + parcel_id
• identidade de ownership: cpf_cnpj
• identidade exibivel: proposta_exibicao

Essas tres identidades nao podem ser confundidas.

Read Path

1. Endpoint da dashboard solicita dados.
2. Camada consolidada consulta SQL Server para Bralar.
3. Camada consolidada consulta base local para Travessia.
4. Ownership e 30 dias continuam sendo resolvidos via MySQL.
5. Enriquecimento adicional pode consultar SQL Server quando necessario.
6. Contrato final TituloConsolidado alimenta os grids atuais.

Sync Path

1. Job solicita token Chronos.
2. Job coleta contratos/parcelas da janela configurada.
3. Dados sao normalizados.
4. Persistencia local faz upsert por identidade tecnica.
5. Auditoria registra resultado do lote.
6. Checkpoint do job e atualizado.

Failure Strategy

• se a sincronizacao falhar, a dashboard continua lendo a ultima base local valida
• falha do job nao derruba request da dashboard
• logs da sincronizacao ficam separados dos logs da leitura operacional
• rollback para modo online deve ser controlado por configuracao, se for necessario

Operational Model

Suggested cadence

• carga completa inicial na homologacao
• duas sincronizacoes incrementais por dia como baseline
• possibilidade de execucao manual assistida para reprocessamento

Suggested controls

• flag para habilitar leitura local da Travessia
• flag para voltar ao modo online se necessario
• endpoint ou script interno para disparar sincronizacao manual em HML

Security

• client_id e client_secret fora do repositorio
• nenhuma chamada direta do frontend para a Chronos
• logs sem token e sem payload sensivel completo
• acessos aos jobs limitados ao backend/ambiente controlado

Observability

Cada execucao deve permitir responder:

• quando sincronizou
• quanto sincronizou
• se falhou
• onde falhou
• quantos registros foram inseridos/atualizados/ignorados

Compatibility with Existing Feature

Esta arquitetura nao substitui a feature chronos-titulos; ela a estabiliza. As regras homologadas de:

• quebras
• 30 dias
• advogado
• renegociacoes
• ownership por carteira
• badge B/T

continuam exatamente as mesmas. O que muda e somente o caminho de abastecimento da Travessia.

Risks and Mitigations

• risco: base local ficar desatualizada
  mitigacao: checkpoints, auditoria e sincronizacao incremental agendada

• risco: duplicidade entre lotes
  mitigacao: identidade tecnica por credit_id + parcel_id e upsert idempotente

• risco: perda de contexto operacional
  mitigacao: manter enriquecimento via SQL Server quando necessario

• risco: divergencia funcional entre online e local
  mitigacao: homologacao comparativa antes da virada definitiva

Recommendation

A recomendacao arquitetural e seguir com a base local sincronizada como proximo passo estruturante da integracao Chronos. Ela ataca o principal gargalo atual sem reabrir as regras de negocio ja estabilizadas e prepara o sistema para escalar a origem Travessia com menos risco operacional.