Architecture Decision Document - Chronos Rollout Operacional

Date: 2026-04-12
Project: cobranca-hml
Feature: chronos-rollout-operacional

Context

O HML já concentra um ecossistema funcional e técnico consolidado em torno da Chronos/Travessia. Esse ecossistema não é composto por um único ponto de alteração; ele é distribuído entre:

• páginas PHP de dashboard
• endpoints de API internos
• serviços de consolidação
• scripts de sincronização
• rotinas cron
• tabelas locais de sync
• trilhas de auditoria
• documentação BMAC

Arquiteturalmente, o risco atual não é "falta de código". O risco atual é "promoção incompleta".

Architectural Decision

Decision

Adotar uma arquitetura documental de rollout, explícita e orientada por inventário, na qual a promoção HML -> produção seja tratada como uma entrega técnica própria, separada da feature funcional.

Why

• o pacote já homologado é transversal
• existem dependências entre áreas que não são óbvias olhando apenas um grid
• cron e sync local fazem parte do comportamento do sistema
• dashboards gerenciais já dependem de ajustes feitos fora do fluxo do cobrador
• há regras de ambiente e operação que precisam viajar junto com o código

Why not rely only on existing feature docs

As features existentes explicam bem o "porquê" e o "como" da funcionalidade. Elas não foram desenhadas para servir, sozinhas, como plano exaustivo de promoção. Parte dos hardenings, hotfixes, cron, retrofits e saneamentos ocorreu durante a homologação. Sem consolidar isso numa trilha operacional, o risco de omissão continua.

Rollout Topology

Environment Boundaries

• HML:
  • /var/www/html/cobranca-hml
• Produção:
  • /var/www/html/cobranca

Regra fixa:

• toda alteração continua sendo feita no HML até autorização explícita
• nenhuma documentação desta feature autoriza mudança antecipada em produção

Runtime Components

1. Monólito PHP
2. SQL Server da Bralar
3. MySQL local do sistema
4. API Chronos
5. API jurídica consumida via proxy backend
6. cron do servidor

Operational Domains

1. Dashboard do Cobrador

Domínio principal da feature funcional:

• dashboard_cobrador.php
• dashboard_quebras.js
• grids pagos
• endpoints de quebra, 30 dias, advogado, renegociação
• badges de origem
• filtros e busca

2. Sincronização Local Chronos

Domínio técnico-operacional:

• scripts/chronos_sync_full.php
• scripts/chronos_sync_incremental.php
• scripts/chronos_sync_incremental_runner.sh
• scripts/chronos_sync_healthcheck.php
• src/lib/chronos/*
• chronos_sync_credits
• chronos_sync_parcels
• chronos_sync_runs
• chronos_sync_state

3. Dashboard Digital

Domínio gerencial impactado pela consolidação:

• dashboard_digital.php
• src/api/dashboard_digital/kpi_total_avencer.php
• src/api/dashboard_digital/kpi_total_vencidos.php
• src/api/dashboard_digital/kpi_inadimplencia_geral.php
• src/api/dashboard_digital/kpi_top_cobrador.php
• src/api/grat_fechamento_preview.php

4. Fechamento de Gratificação

Domínio financeiro sensível:

• fechamento_gratificacoes.php
• src/api/grat_fechamento_preview.php
• src/api/grat_fechamento_fechar.php
• src/api/grat_fechamento_status.php
• src/api/grat_fechamento_excluir.php

5. Histórico do Cliente

Domínio auxiliar, porém funcionalmente crítico:

• src/contatos/historico_clientes.php
• badges de origem
• fallback Travessia
• supressão de SUSPENSO para Chronos

6. Jurídico

Domínio de integração lateral:

• src/api/juridico/status_batch.php
• js/juridico_status_helper.js
• proxy backend para evitar CORS

Inventory of Affected Technical Areas

A. Páginas e telas

• dashboard_cobrador.php
• dashboard_digital.php
• dashboard_digital_black.php
• fechamento_gratificacoes.php
• src/contatos/historico_clientes.php
• bmac_acompanhamento.php
• index.php

B. Endpoints e APIs internas

• src/api/quebras_listar.php
• src/api/cobranca30/registrar.php
• src/api/cobranca30/marcar_pago.php
• src/api/dashboard_digital/kpi_total_avencer.php
• src/api/dashboard_digital/kpi_total_vencidos.php
• src/api/dashboard_digital/kpi_inadimplencia_geral.php
• src/api/dashboard_digital/kpi_top_cobrador.php
• src/api/grat_fechamento_preview.php
• src/api/juridico/status_batch.php
• src/api/chronos_sync_status.php

C. Serviços de domínio

• src/lib/cobranca/QuebrasConsolidadoService.php
• src/lib/cobranca/RecebimentosConsolidadosService.php
• src/lib/cobranca/SqlsrvTituloEnrichmentService.php
• src/lib/cobranca/TituloConsolidadoFactory.php
• src/lib/cobranca/ClassificationTraceLogger.php
• src/lib/chronos/ChronosLocalReadService.php
• src/lib/chronos/ChronosLocalRepository.php
• src/lib/chronos/ChronosPortfolioResolver.php
• src/lib/chronos/ChronosIncrementalSyncService.php
• src/lib/chronos/ChronosSyncAuditRepository.php
• src/lib/chronos/ChronosSyncStateRepository.php
• src/lib/chronos/ChronosSyncStatusService.php

D. Scripts operacionais

• scripts/chronos_sync_full.php
• scripts/chronos_sync_incremental.php
• scripts/chronos_sync_incremental_runner.sh
• scripts/chronos_sync_healthcheck.php
• scripts/chronos_sync_backfill_proposals.php
• scripts/chronos_sync_backfill_advogado.php
• scripts/chronos_reclassify_30d_to_chronos.php

E. Configuração e suporte

• _evo/bmm/config.yaml
• config/database.php
• config/chronos.php
• src/views/partials/header.php

Promotion Model

Promotion Principle

Produção não deve receber apenas arquivos alterados. Deve receber um pacote coerente composto por:

1. código funcional
2. código de suporte
3. scripts
4. configuração
5. cron
6. validação pós-ativação

Promotion Layers

Layer 1. Código base

Arquivos PHP, JS e classes necessárias para o comportamento funcional.

Layer 2. Dados e saneamentos

Scripts e passos necessários para:

• enriquecer base local
• reclassificar 30 dias
• garantir materialização de proposta e em_advogado

Layer 3. Operação

Cron, healthcheck, lockfile, logs e checkpoints.

Layer 4. Validação

Conferência manual e funcional após ativação.

Cron Architecture

HML validated schedule

• full: 06:00, todos os dias
• incremental: 07:00-19:00, somente 1-5
• healthcheck: 03:30, todos os dias, --stale-minutes=1440

Required production stance

No momento do rollout, produção deve ser configurada deliberadamente. Nada deve ser presumido. Devem ser confirmados explicitamente:

• presença dos scripts
• path correto dos logs
• path correto do lock
• versão correta das credenciais
• agendamento exato

Rollout Constraints

Constraint 1. No implicit parity

Não presumir que produção já possui:

• mesmas tabelas
• mesmo cron
• mesmo arquivo de config
• mesma política de logs
• mesmo schema local Chronos

Constraint 2. No premature activation

Não ativar:

• flags da Chronos
• cron da sync local
• healthcheck

sem autorização do usuário.

Constraint 3. No mixed-environment execution

Não executar scripts de HML em produção por acidente. Os caminhos de execução devem ser revisados linha a linha.

Observability Requirements

Required signals

• última execução full
• última execução incremental
• checkpoint incremental
• quantidade de créditos e parcelas
• parcelas sem CPF
• parcelas órfãs
• status do healthcheck
• logs de grids/classificação

Required files and endpoints

• logs/chronos_sync_incremental.log
• logs/chronos_sync_healthcheck.log
• endpoint src/api/chronos_sync_status.php
• tabela chronos_sync_runs
• tabela chronos_sync_state

Rollback Architecture

Safe rollback levers

1. desligar flags da Chronos
2. pausar cron da sync
3. manter base local intacta para auditoria
4. voltar leitura para comportamento anterior apenas se realmente necessário

Unsafe rollback patterns

• apagar tabelas sincronizadas sem backup
• alterar cron sem registrar
• remover scripts sem preservar runbook
• reverter parcialmente apenas parte dos KPIs

Decision Summary

Para esta entrega, a arquitetura correta não é apenas "subir código". A arquitetura correta é tratar a promoção como um sistema operacional em miniatura, com:

• pacote explícito de componentes
• ordem de promoção
• checklist de validação
• observabilidade
• rollback