Product Requirements Document - Chronos Rollout Operacional

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

Executive Summary

As features chronos-titulos e chronos-sync-local já produziram, no HML, um conjunto amplo de alterações funcionais, técnicas e operacionais. O sistema deixou de depender apenas de grids originais do SQL Server e passou a operar com carteira consolidada, origem B/T, sincronização local da Travessia, fechamento ajustado, KPIs corrigidos e processos automáticos de sincronização.

O problema, agora, não é falta de implementação. O problema é governança de promoção. Existe risco real de levar para produção apenas parte do pacote homologado, omitindo ajustes auxiliares, scripts, cron, páginas correlatas, endpoints de suporte, regras de ambiente, validações de operação e dependências entre módulos.

Esta feature existe para transformar o conhecimento acumulado no HML em um plano de promoção completo, detalhado e auditável, minimizando risco de rollout parcial, regressão operacional e divergência entre HML e produção.

Problem Statement

O pacote real homologado no HML já inclui componentes de naturezas diferentes:

• regras funcionais visíveis ao cobrador
• regras de classificação consolidadas no backend
• leitura local da Chronos sincronizada por jobs
• ajustes de cards e dashboards gerenciais
• ajustes em histórico do cliente e fluxo jurídico
• reclassificação histórica em tabelas operacionais
• cron, healthcheck e checkpoints de sincronização
• documentação de homologação e readiness

Sem uma feature operacional própria, existe risco de:

1. promover código sem promover cron e rotinas
2. promover dashboards sem promover saneamentos históricos
3. promover grids sem promover ajustes de páginas auxiliares
4. promover jobs sem documentar horários, locks e critérios de monitoramento
5. esquecer dependências críticas porque elas não estão concentradas num único artefato

Business Goal

Garantir que a futura promoção para produção da Chronos/Travessia ocorra com máxima previsibilidade, sem depender de memória tácita e sem perda de ajustes já homologados no HML.

Primary Users

• responsável técnico pela promoção para produção
• analista funcional que valida pós-rollout
• gestor operacional que precisa saber o que foi incluído
• equipe que executará ou acompanhará cron, healthcheck e monitoramento

Success Criteria

Esta feature será considerada bem-sucedida quando:

1. existir um inventário detalhado de todos os ajustes relevantes do HML
2. cada ajuste estiver associado a arquivos, finalidade e impacto
3. houver instrução explícita de como reproduzir cron, flags e jobs em produção
4. houver checklist de pré-go-live, go-live e pós-go-live
5. nenhuma etapa crítica da promoção depender de memória não documentada

In Scope

• documentação exaustiva do pacote homologado
• detalhamento de dependências por área do sistema
• consolidação de cron e operação de sync local
• checklist de validação por página e por fluxo
• estratégia de rollback
• critérios de observação pós-produção

Out of Scope

• executar rollout em produção agora
• alterar diretamente /var/www/html/cobranca sem autorização
• expandir escopo funcional além do que já foi homologado

Functional Requirements

FR1. Inventário integral dos ajustes homologados

O sistema documental BMAC deve listar todos os ajustes relevantes já feitos no HML, incluindo páginas além de dashboard_cobrador.php.

FR2. Mapa detalhado por área funcional

Deve existir separação clara entre:

• dashboard do cobrador
• dashboard digital
• fechamento de gratificação
• histórico do cliente
• triagem jurídica / proxy jurídico
• jobs de sincronização
• auditoria e observabilidade
• BMAC e documentação

FR3. Registro explícito de arquivos impactados

Cada área deve apontar os arquivos, endpoints, scripts ou classes diretamente relevantes para a promoção.

FR4. Registro explícito do que é obrigatório em produção

Para cada item inventariado, deve ficar claro se ele é:

• obrigatório para produção
• condicional
• apenas evidência de homologação

FR5. Registro explícito do que não deve ser promovido sem autorização

Deve ficar explícito que:

• o ambiente de produção não pode ser alterado sem autorização do usuário
• nenhum cron ou flag de produção deve ser ativado antecipadamente

FR6. Runbook de promoção

Deve existir um runbook com:

• pré-requisitos
• ordem de execução
• dependências
• validações
• rollback

FR7. Estratégia de cron documentada

Deve existir documentação explícita do desenho operacional homologado no HML:

• full diário às 06:00
• incremental de 07:00 a 19:00, somente dias úteis
• healthcheck diário às 03:30

FR8. Comportamento de domingo explicitado

Deve constar formalmente que:

• domingo roda full
• domingo roda healthcheck
• domingo não roda incremental horário

FR9. Registro do estado real da base local

Deve constar o estado validado da base local, incluindo:

• quantidade de créditos
• quantidade de parcelas
• ausência de órfãs
• ausência de parcelas sem CPF

FR10. Registro dos ajustes em dashboard_digital

Deve constar detalhamento de:

• Total a Vencer
• Total Vencidos
• Inadimplência
• Carteira Total
• Top Cobrador
• origem de Total Recebido

FR11. Registro dos ajustes em fechamento_gratificacoes

Deve constar o ajuste da prévia mensal para considerar Travessia e usar a mesma base consolidada homologada.

FR12. Registro do fluxo 30 dias

Deve constar:

• registro de 30 dias para Bralar e Travessia
• reclassificação histórica para origem_sistema = chronos
• comportamento da marcação de pago

FR13. Registro do histórico do cliente

Deve constar:

• badge B/T
• ocultação do badge SUSPENSO para Chronos
• fallback para contexto Travessia enriquecido

FR14. Registro do fluxo jurídico

Deve constar:

• necessidade do proxy backend para evitar CORS
• continuidade de uso de contract_external_id

FR15. Registro dos ajustes de timeout e sessão

Deve constar onde foram aplicadas liberações antecipadas de sessão e por quê.

FR16. Matriz de impacto HML -> produção

Deve existir matriz detalhada por:

• caminho do arquivo
• papel do ajuste
• criticidade
• necessidade de promoção

FR17. Checklist de validação pós-produção

Deve existir checklist de conferência prática após promoção:

• grids
• cards
• jobs
• healthcheck
• logs

FR18. Estratégia de rollback

Deve existir rollback documentado por:

• flags
• cron
• isolamento de leitura local
• não destruição de histórico

FR19. Separação entre evidência e ação

Os documentos devem diferenciar:

• o que foi comprovado no HML
• o que precisará ser executado no momento do rollout

FR20. Atualização do painel BMAC

A nova feature deve aparecer explicitamente no painel, com slug e identidade próprios.

Non-Functional Requirements

NFR1. Zero dependência de memória implícita

O pacote documental deve ser suficiente para outra pessoa técnica executar a promoção sem depender da conversa original.

NFR2. Detalhamento máximo

Os artefatos devem preferir excesso de precisão a generalidades.

NFR3. Rastreabilidade por arquivo

Sempre que possível, cada ajuste deve apontar caminhos de arquivos concretos.

NFR4. Separação de ambiente

Os documentos devem reforçar a regra fixa:

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

NFR5. Segurança operacional

A documentação deve presumir rollout controlado por flags e cron, nunca ativação irrestrita.

Constraints

• não alterar produção nesta fase
• não presumir que produção tem o mesmo cron já aplicado
• não presumir que todos os arquivos do HML já estão presentes ou alinhados em produção
• não presumir que dados históricos de produção já estão saneados como no HML

Acceptance Criteria

1. existe uma feature BMAC separada para rollout operacional
2. ela contém PRD, arquitetura, épicos, readiness, runbook e matriz de impacto
3. o painel BMAC consegue listá-la
4. os artefatos deixam claro o pacote mínimo para promoção segura
5. os artefatos deixam claro que a promoção continua bloqueada até autorização explícita