stepsCompleted:

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8 inputDocuments:
• /var/www/html/cobranca-hml/_evo-output/planning-artifacts/chronos-titulos/prd.md
• /var/www/html/cobranca-hml/_evo-output/planning-artifacts/chronos-titulos/implementation-readiness-report.md
• /var/www/html/cobranca-hml/docs/index.md
• /var/www/html/cobranca-hml/docs/project-overview.md
• /var/www/html/cobranca-hml/docs/source-tree-analysis.md
• /var/www/html/cobranca-hml/docs/architecture.md
• /var/www/html/cobranca-hml/docs/api-contracts.md
• /var/www/html/cobranca-hml/docs/data-models.md
• /var/www/html/cobranca-hml/docs/component-inventory.md
• /var/www/html/cobranca-hml/docs/development-guide.md
• /var/www/html/cobranca-hml/docs/deployment-guide.md
• /var/www/html/cobranca-hml/docs/fluxo-de-cobranca-30-dias.md
• /var/www/html/cobranca-hml/docs/como-abrir-uma-negociacao.md
• /var/www/html/cobranca-hml/docs/relatorios-e-kpis.md
• /var/www/html/cobranca-hml/docs/perfis-e-permissoes.md

• /var/www/html/cobranca-hml/docs/politica-de-seguranca-e-backup.md workflowType: 'architecture' lastStep: 8 status: 'complete' completedAt: '2026-04-09' project_name: 'cobranca' user_name: 'Thiago' date: '2026-04-09'

Architecture Decision Document

This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together.

Project Context Analysis

Requirements Overview

Functional Requirements: A feature chronos-titulos adiciona uma terceira fonte de dados ao dashboard operacional do cobrador sem substituir a logica existente. O PRD consolidou 49 requisitos funcionais, concentrados em nove areas arquiteturalmente relevantes: carteira consolidada, classificacao operacional, fluxo de quebras, fluxo de 30 dias, fluxo de renegociacoes, indicadores, filtros/leitura de dashboard, resiliencia operacional e governanca/auditoria. O efeito arquitetural mais importante e que a feature nao e “mais um endpoint”; ela exige um contrato interno unico de titulo consolidado para alimentar varios endpoints existentes com comportamento consistente.

No MVP, a feature precisa suportar tres comportamentos centrais. Primeiro, incorporar titulos da Chronos no grid de quebras para clientes da carteira do cobrador. Segundo, permitir que titulos Travessia entrem e se movimentem pelo fluxo de 30 dias preservando o MySQL como fonte de verdade da marcacao operacional. Terceiro, incorporar renegociacoes pagas da Chronos sem duplicar valores ou linhas em grids concorrentes. Isso implica regras deterministicas de classificacao, prioridade entre categorias e rastreabilidade suficiente para auditoria funcional.

Non-Functional Requirements: Os 31 NFRs do PRD convergem para seis pressões arquiteturais: performance operacional do dashboard, seguranca de credenciais e dados, confiabilidade com degradacao controlada, robustez de integracao entre fontes heterogeneas, observabilidade/auditoria e rollout seguro em homologacao. Em termos praticos, a arquitetura precisa manter a aplicacao utilizavel mesmo com falha da Chronos, evitar chamadas redundantes, impedir vazamento de segredos, preservar leitura operacional da tela e permitir diagnostico posterior de classificacao e divergencia.

Os NFRs tambem reforcam restricoes nao negociaveis: a integracao deve ser backend-only, os segredos da Chronos nao podem ir para codigo versionado ou frontend, e nenhuma alteracao em scripts SQL Server existentes pode ser feita sem confirmacao explicita. Isso elimina opcoes arquiteturais mais invasivas e direciona o desenho para uma camada complementar dentro do monolito PHP, controlada por configuracao e operando em cima dos endpoints ja existentes.

Scale & Complexity: O projeto e de complexidade alta, nao por volume de telas novas, mas por impacto sobre uma operacao sensivel em producao. A feature cruza tres fontes com semanticas diferentes: SQL Server para carteira operacional atual, MySQL para atribuicao e marcacoes operacionais, e Chronos para titulos suspensos da Travessia. A dificuldade arquitetural esta em orquestrar essas fontes sem regressao para a Bralar e sem espalhar regra de consolidacao por varios endpoints.

• Primary domain: web_app PHP monolitico com APIs JSON internas e integracao financeira externa.
• Complexity level: high
• Estimated architectural components: 7

Technical Constraints & Dependencies

A restricao central do projeto e de negocio e arquitetura ao mesmo tempo: os scripts SQL Server atuais devem permanecer intactos, salvo nova confirmacao explicita. Portanto, a solucao nao pode “corrigir” o ERP. Ela precisa introduzir uma camada complementar de consolidacao no backend PHP, consumindo Chronos e cruzando seus resultados com a mesma carteira e as mesmas marcacoes auxiliares do fluxo atual.

Ha tambem uma dependencia forte do banco MySQL auxiliar. A classificacao de 30 dias nao nasce da Chronos; ela continua a depender de cobranca_30dias_registros. Isso significa que a arquitetura da feature nao pode ser apenas um adapter da API externa. Ela precisa combinar: atribuicoes da carteira no MySQL, titulos SQL Server ja existentes, titulos Chronos complementares, marcacao 30 dias no MySQL e regras funcionais de exclusao de duplicidade entre grids.

Existe tambem uma dependencia estrutural de ownership da carteira. O sistema atual resolve “de quem e o cliente” por cobranca_atribuicao_cliente, e essa regra deve permanecer para a Chronos. Cada titulo Travessia so pode entrar na visao do cobrador se o cpf_cnpj normalizado do devedor estiver associado ao user_id logado em uma atribuicao ATIVO. A API externa nao deve introduzir um segundo conceito de responsavel de carteira.

Do lado da Chronos, o comportamento tecnico ja validado impõe dependencias claras: autenticacao OAuth2 Client Credentials, descoberta de credito e uso de id interno para buscar parcelas, classificacao por status e parcelFrequencyName, e tolerancia a respostas vazias/nulas. Como o dashboard atual e server-rendered com AJAX pontual, a integracao deve ficar inteiramente no backend e devolver JSON compatível com os contratos atuais ou com extensoes pequenas e controladas desses contratos.

Cross-Cutting Concerns Identified

• Consolidacao e normalizacao de dados: a feature precisa normalizar cpf_cnpj, identificar corretamente a granularidade de titulo/parcela e manter proposta operacional exibivel sem colapsar multiplos titulos do mesmo cliente.
• Enriquecimento por fonte secundaria: a Chronos deve permanecer como fonte primaria de identificacao e classificacao dos titulos Travessia, enquanto o SQL Server deve atuar como fonte de enriquecimento/fallback para completar contexto operacional ausente na API, como residencial, proposta exibivel completa e referencias legadas usadas por acoes do dashboard.
• Ownership da carteira: a camada consolidada precisa resolver cpf_cnpj -> cobrador_usuario_id a partir de cobranca_atribuicao_cliente antes de incluir linhas Chronos nos grids do cobrador.
• Normalizacao de busca e filtros: a camada consolidada precisa mapear campos equivalentes de pesquisa entre SQL Server, MySQL e Chronos para que a busca atual do dashboard continue funcionando sobre a visao unificada.
• Classificacao deterministica: o mesmo titulo nao pode cair em grids diferentes conforme o endpoint chamado. A ordem de avaliacao e a regra de exclusao precisam ser centralizadas.
• Observabilidade funcional: o backend deve conseguir explicar por que um titulo entrou em quebras, 30 dias ou renegociacoes, e de qual fonte esse titulo veio.
• Controle de regressao: a Bralar precisa continuar funcionando com as consultas atuais. A Travessia entra por composicao, nao por substituicao.
• Compatibilidade de contratos: os endpoints atuais do dashboard sao a fronteira mais sensivel da mudanca. A arquitetura deve minimizar ruptura de payload e concentrar a inteligencia nova atras deles.
• Continuidade dos botões de ação: Histórico do cliente e Triagem Jurídica precisam continuar operando para Bralar e Travessia, o que exige fallback de contexto fora do SQL Server e payload explícito de contrato externo para o jurídico.
• Rollout seguro: a feature sera desenvolvida e validada somente em /var/www/html/cobranca-hml, com necessidade de ativacao reversivel e degradacao controlada em caso de falha da Chronos.

Starter Template Evaluation

Primary Technology Domain

web_app brownfield em PHP server-rendered com endpoints JSON internos, baseado em codigo existente que precisa ser evoluido in-place. Nao se trata de inicializacao de um projeto novo.

Starter Options Considered

Foram verificados starters atuais e mantidos do ecossistema PHP como referencia de mercado, mas apenas para validar se faria sentido adotá-los nesta feature. As opcoes mais obvias hoje sao:

• Laravel Starter Kits atuais, documentados oficialmente pela Laravel para aplicacoes novas, com stack moderna de autenticacao e UI predefinida.
• Symfony CLI / symfony new --webapp e symfony/skeleton, recomendados oficialmente para novas aplicacoes Symfony.

Essas opcoes sao validas para greenfield, mas nao encaixam neste caso por quatro motivos arquiteturais:

1. O sistema atual nao e Laravel nem Symfony; e um monolito PHP brownfield com regras espalhadas entre paginas e endpoints.
2. A feature precisa preservar contratos, sessao, estrutura e consultas atuais, nao substituir a base da aplicacao.
3. O custo arquitetural de “inserir um starter” seria maior que o beneficio, porque criaria dois paradigmas de aplicacao convivendo no mesmo repositorio.
4. O problema real da feature e consolidacao de dados e classificacao operacional, nao bootstrap de projeto.

Selected Starter: Nenhum starter externo

Rationale for Selection: Para chronos-titulos, a decisao correta e nao adotar starter template. A fundacao da feature deve ser o proprio sistema existente em /var/www/html/cobranca-hml, com implementacao incremental e compatível com o monolito atual. Arquiteturalmente, isso evita introduzir um novo framework, evita dualidade de padroes e mantem a feature no lugar onde o negocio ja opera hoje.

Initialization Command:

# Nao aplicavel: a feature sera implementada sobre o codigo brownfield existente
cd /var/www/html/cobranca-hml

Architectural Decisions Provided by Starter:

Language & Runtime: Nao ha novo starter definindo stack. A feature continua em PHP no runtime ja adotado pelo sistema, com sessao PHP, endpoints JSON internos e acesso aos bancos ja configurados.

Styling Solution: Nao ha mudanca de stack visual. A tela continua usando o frontend existente do projeto, com ajustes incrementais nos grids e badges do dashboard.

Build Tooling: Nao ha novo build system introduzido. A implementacao deve respeitar o fluxo atual da aplicacao, sem criar pipeline paralelo de bundling para esta feature.

Testing Framework: Nenhum framework novo e introduzido nesta etapa. A validacao da feature continua centrada em homologacao dirigida e verificacao funcional no ambiente cobranca-hml.

Code Organization: A feature deve se encaixar na organizacao atual do sistema, preferencialmente concentrando a nova inteligencia em uma camada interna de consolidacao reutilizavel pelos endpoints impactados, sem reestruturar o repositorio em torno de um novo framework.

Development Experience: O ganho de consistencia virá das decisoes arquiteturais deste documento, nao de um boilerplate externo. O primeiro trabalho de implementacao devera ser criar a camada de integracao/consolidacao Chronos dentro da aplicacao atual.

Note: Nao existe historia de “inicializar projeto a partir de starter”. A primeira historia de implementacao deve partir da arquitetura da camada consolidada dentro do brownfield existente.

Core Architectural Decisions

Decision Priority Analysis

Critical Decisions (Block Implementation):

• Manter a arquitetura brownfield atual e introduzir uma camada interna de consolidacao, sem reescrever o sistema em framework novo.
• Preservar SQL Server como fonte atual da Bralar e adicionar Chronos apenas como fonte complementar da Travessia.
• Centralizar classificacao de titulos Chronos em uma camada unica reutilizavel, em vez de replicar regra por endpoint.
• Tratar MySQL como fonte de verdade para atribuicao de carteira e marcacao 30 dias.
• Adotar rollout controlado por configuracao e degradacao segura quando a Chronos falhar.

Important Decisions (Shape Architecture):

• Adicionar metadata de rastreabilidade no MySQL para titulos Travessia quando necessario para evitar ambiguidade futura.
• Manter contratos dos endpoints atuais com extensoes minimas e compatíveis.
• Usar integracao HTTP nativa em PHP no MVP, sem adicionar cliente HTTP novo ao monolito.
• Concentrar logs e diagnostico funcional em uma trilha de consolidacao identificavel.

Deferred Decisions (Post-MVP):

• Cache persistente mais sofisticado para respostas Chronos.
• Eventual UX formal dedicada para grids e badges.
• Evolucao da camada consolidada para outros paineis alem do escopo inicial.

Data Architecture

Decision: manter o modelo atual com SQL Server + MySQL e introduzir uma terceira camada logica de leitura consolidada, sem criar novo banco e sem mexer nos scripts SQL Server existentes.

Rationale: O SQL Server continua sendo a fonte operacional da Bralar e nao deve ser alterado. O MySQL continua sendo a fonte de atribuicao de carteira, historico e marcacoes operacionais. A Chronos entra como fonte externa complementar da Travessia. A arquitetura correta e uma composicao server-side dessas fontes, nao migracao de ownership de dados.

Chosen Model:

• SQL Server: leitura da carteira Bralar atual exatamente como hoje.
• MySQL: atribuicoes, cobranca_30dias_registros, historicos e futuras colunas auxiliares de rastreabilidade.
• Chronos: leitura de creditos e parcelas da Travessia via API.
• Camada nova: TituloConsolidado, contrato interno unico para alimentar endpoints.

Normalization Strategy:

• cpf_cnpj normalizado como chave de pertencimento e cruzamento.
• titulo_uid interno obrigatorio por linha consolidada.
  • Bralar: pode derivar de origem + proposta + cpf_cnpj + categoria
  • Travessia: deve derivar de origem + credit_id + parcel_id
• proposta_exibicao mantida para leitura operacional.
• marca_empresa sempre explicita: Bralar ou Travessia.
• origem_sistema sempre explicita: sqlsrv ou chronos.
• Campos de busca consolidados devem ser normalizados em contrato interno unico, no minimo para nome_cliente, cpf_cnpj, proposta_exibicao e referencias operacionais equivalentes de residencial/unidade quando houver.
• Para Travessia, cpf_cnpj pode ser usado para localizar dados complementares no SQL Server, mas nunca deve substituir credit_id + parcel_id como identidade do titulo. O SQL Server enriquece o contexto; a Chronos continua sendo a fonte de verdade do titulo complementar.

MySQL Schema Strategy: Para o MVP, a tabela cobranca_30dias_registros continua sendo a base funcional do fluxo 30 dias, mas a arquitetura recomenda extensao aditiva no MySQL para suportar rastreabilidade da Travessia sem quebrar compatibilidade. Os campos candidatos sao:

• origem_sistema
• marca_empresa
• titulo_uid
• chronos_credit_id
• chronos_parcel_id

Isso evita ambiguidade futura entre proposta operacional, cpf do cliente e identificador real da parcela Chronos.

Caching Strategy: Nao adotar cache persistente sofisticado no MVP. A decisao inicial e:

• sem novo Redis ou fila
• sem cache de payload de negocio entre usuarios
• apenas cache tecnico curto de token OAuth2, porque isso reduz chamadas desnecessarias sem comprometer consistencia funcional

Authentication & Security

Decision: manter autenticacao da aplicacao via sessao PHP e isolar a autenticacao Chronos no backend por OAuth2 Client Credentials com cache curto de token.

Verified Runtime Context:

• Ambiente local atual: PHP 8.4.17 no servidor de homologacao
• guzzlehttp/guzzle em Packagist continua na linha 7.x e declara suporte >=7.2.5,<8.5

Security Decision: Apesar de o ambiente atual suportar Guzzle 7, a melhor escolha para o MVP e nao introduzir nova dependencia HTTP. O projeto hoje tem composer.json minimo e nenhuma abstracao HTTP preexistente. Para reduzir risco de supply chain, impacto em deploy e variabilidade no brownfield, a integracao Chronos deve usar PHP nativo com cURL/extensao HTTP ja presente no ambiente.

Token Handling:

• token Chronos obtido apenas no backend
• client_id e client_secret fora do repositorio
• cache tecnico de token com expires_at em arquivo local nao publico ou camada equivalente de configuracao do servidor
• nenhum token exposto ao navegador ou a logs

Authorization Pattern:

• manter sessao PHP atual para autorizacao dos endpoints
• reusar user_id/user_perfil existentes
• aplicar filtros por carteira do cobrador antes de consultar/mesclar dados da Chronos
• usar cobranca_atribuicao_cliente com status = 'ATIVO' como fonte unica de ownership de carteira para Bralar e Travessia

API & Communication Patterns

Decision: manter o padrao atual de endpoints JSON internos e introduzir uma camada interna de servicos/adapters, sem criar microservico, GraphQL ou API externa nova.

Internal Pattern Chosen:

• endpoint recebe usuario + filtros + busca atual
• camada consolidada resolve quais fontes precisam ser consultadas para aquele grid
• filtros e busca sao aplicados de forma equivalente sobre SQL Server, MySQL e Chronos conforme a semantica de cada campo
• resultado final e retornado como lista consolidada unica, sem exigir ao frontend pesquisas separadas por fonte
• Endpoints continuam em /src/api/*
• Cada endpoint impactado delega parte da montagem a uma camada nova
• A camada nova deve ser dividida em responsabilidades:
  • ChronosTokenProvider
  • ChronosClient
  • ChronosMapper
  • SqlsrvTituloEnrichmentService
  • TituloConsolidadoService
  • TituloClassificationService

Error Handling Standard:

• servicos internos lancam excecoes especificas ou retornos controlados
• endpoints traduzem isso para o contrato JSON atual
• falha da Chronos nunca deve derrubar toda a resposta se a parte Bralar puder continuar sendo entregue

Payload Compatibility: A arquitetura deve favorecer extensao minima dos contratos atuais. Campos novos recomendados nos grids:

• origem_sistema
• marca_empresa
• titulo_uid
• proposta_exibicao

Campos atuais como Cliente, cpf_cnpj, Residencial, Valor, DataPagamento, DataVencimento e afins devem continuar existindo.

Frontend Architecture

Decision: nao introduzir nova arquitetura frontend. O dashboard continua server-rendered com AJAX pontual, recebendo apenas extensoes pequenas de payload.

Frontend Impact Rules:

• nao criar SPA
• nao mover regra de classificacao para JavaScript
• nao consumir Chronos diretamente do navegador
• limitar mudancas visuais a badges/colunas/rotulos necessarios

View Model Decision: O frontend deve receber uma representacao uniforme para linhas Bralar e Travessia. Isso permite que grids existentes renderizem dados de ambas as origens sem ifs excessivos por origem na camada visual.

Infrastructure & Deployment

Decision: manter deploy no ambiente atual Apache/PHP-FPM e usar configuracao do proprio servidor para ativacao da feature e segredos da Chronos.

Deployment Strategy:

• implementacao somente em /var/www/html/cobranca-hml
• configuracao da Chronos separada por ambiente
• flag de ativacao recomendada:
  • CHRONOS_ENABLED
  • opcionalmente flags granulares por fluxo:
  • CHRONOS_ENABLE_QUEBRAS
  • CHRONOS_ENABLE_30D
  • CHRONOS_ENABLE_RENEG

Logging & Monitoring:

• logs com prefixos dedicados: chronos, titulos_consolidados, classificacao_titulos
• registrar erro HTTP, timeout, creditos consultados, quantidade de parcelas e decisao de classificacao
• nunca registrar segredo ou token completo

Endpoint Impact Decisions

/src/api/quebras_listar.php

• continua gerando a base Bralar atual via SQL Server
• passa a anexar linhas Chronos OVERDUE para CPFs da carteira do cobrador
• nao altera a query SQL Server atual

/src/api/pc_titulos_pagos.php

• continua trazendo renegociacoes Bralar pelo SQL Server atual
• passa a somar renegociacoes Chronos pagas com parcelFrequencyName = Renegociação
• continua excluindo o que ja estiver em 30 dias
• continua excluindo o que for classificado em advogado pelo enriquecimento SQL Server

/src/api/pc_titulos_pagos_adv.php

• continua trazendo recebimentos advogado Bralar pelo SQL Server atual
• passa a incluir titulos pagos da Travessia cujo contexto enriquecido no SQL Server indique NumeroContratoBanco LIKE '%adv%'
• deve excluir o que ja estiver classificado em 30 dias
• deve permanecer mutuamente exclusivo em relacao a renegociacoes

/src/api/pc_titulos_pagos_30d.php

• continua tomando cobranca_30dias_registros como base
• para linhas Travessia, deve montar a linha usando a rastreabilidade da Chronos e completar contexto exibivel a partir do SQL Server por cpf_cnpj e referencias operacionais derivadas quando a API nao trouxer todos os campos necessarios
• esse endpoint vira o principal consumidor da rastreabilidade adicionada ao MySQL

/src/api/indicadores_30dias.php

• continua tendo o MySQL como base de contagem
• passa a considerar registros Travessia marcados em cobranca_30dias_registros
• nao precisa consultar Chronos diretamente se o MySQL ja estiver devidamente marcado/enriquecido

Decision Impact Analysis

Implementation Sequence:

1. Criar a camada interna Chronos (token, client, mapper).
2. Criar o contrato interno TituloConsolidado.
3. Criar a classificacao centralizada (quebra, 30 dias, renegociacao).
4. Adaptar o fluxo de marcacao 30 dias para registrar rastreabilidade da Travessia no MySQL.
5. Integrar quebras_listar.php.
6. Integrar pc_titulos_pagos.php.
7. Integrar pc_titulos_pagos_30d.php.
8. Integrar pc_titulos_pagos_adv.php.
9. Integrar pc_recebimento_por_tipo.php e indicadores derivados.
10. Ajustar frontend do dashboard para Travessia/Bralar.
11. Homologar com contratos reais e logs de classificacao.

Cross-Component Dependencies:

• A camada de consolidacao depende da carteira do cobrador no MySQL.
• O filtro de ownership deve ser resolvido antes da inclusao de titulos Chronos, usando cobranca_atribuicao_cliente como mapa de carteira ativa por CPF normalizado.
• O grid 30 dias depende da marcacao persistida no MySQL, nao apenas da Chronos.
• Indicadores dependem da qualidade dessa marcacao.
• Os grids quebras, advogado e renegociacoes dependem da classificacao centralizada para nao divergirem entre si.
• A rastreabilidade no MySQL reduz risco de perda de contexto entre endpoints e operacoes futuras.
• Os botões do grid quebras dependem de contexto operacional adicional:
  • Historico do cliente: src/contatos/historico_clientes.php hoje é SQL Server-first para nome, status, KPIs e parcelas, com MySQL para ownership e histórico.
  • Triagem Jurídica: js/dashboard_quebras.js, src/api/triagem/registrar_historico.php e integração jurídica externa exigem cpf, contract.external_id, cliente e residencial consistentes para Bralar e Travessia.
• Para Travessia, a arquitetura deve deixar explícito um campo normalizado contract_external_id, em vez de depender de parsing implícito da proposta exibida.
• A estrategia de enriquecimento recomendada e em duas etapas:
  • primeiro, tentar resolver contexto por referencias mais especificas vindas da Chronos, como contractNumber, numberDescription, datas e valor;
  • segundo, usar cpf_cnpj no SQL Server como fallback controlado para recuperar contexto exibivel do cliente quando a API nao trouxer o campo desejado.
• O uso de CPF puro como fallback nao deve reidentificar o titulo; ele serve para completar contexto operacional do cliente. A identidade funcional do titulo Travessia continua sendo a combinacao Chronos (credit_id, parcel_id, key quando houver).
• Para titulos pagos da Travessia, a precedencia de classificacao recomendada fica explicita:
  • primeiro 30 dias, por marcacao no MySQL;
  • depois advogado, por enriquecimento no SQL Server com NumeroContratoBanco LIKE '%adv%';
  • por fim renegociacoes, para titulos pagos remanescentes com parcelFrequencyName = Renegociação.
• Essa precedencia deve ser centralizada no TituloClassificationService, nunca reproduzida de forma independente por endpoint.

Implementation Patterns & Consistency Rules

Pattern Categories Defined

Critical Conflict Points Identified: 8 areas onde agentes diferentes poderiam tomar decisoes incompatíveis: naming de campos e classes, localizacao da camada nova, formato de payload, modelo de erro, normalizacao de dados, logging, persistencia auxiliar no MySQL e regras de classificacao/precedencia.

Naming Patterns

Database Naming Conventions:

• Para novas colunas/tabelas MySQL, usar snake_case.
• Chaves de rastreabilidade devem seguir nomes descritivos e sem abreviacoes ambíguas.
• Exemplos:
  • origem_sistema
  • marca_empresa
  • titulo_uid
  • chronos_credit_id
  • chronos_parcel_id
• Nao criar naming misto como chronosCreditId ou tituloUid no banco.

API Naming Conventions:

• Endpoints existentes permanecem com naming atual; nao renomear rotas para a feature.
• Campos novos de JSON devem respeitar o estilo já dominante do payload do endpoint.
• Como os endpoints atuais misturam PascalCase e snake_case, a regra para a feature e:
  • preservar os campos existentes como ja saem hoje
  • adicionar metadata nova em snake_case para reduzir ambiguidade
• Exemplos:
  • manter Cliente, Residencial, Valor, DataPagamento
  • adicionar origem_sistema, marca_empresa, titulo_uid, proposta_exibicao

Code Naming Conventions:

• Classes novas em PascalCase.
• Metodos em camelCase.
• Variaveis locais em camelCase.
• Helpers de normalizacao podem seguir o estilo do arquivo onde estao, mas classes novas devem ser consistentes.
• Exemplos:
  • ChronosTokenProvider
  • ChronosClient
  • ChronosMapper
  • TituloConsolidadoService
  • TituloClassificationService

Structure Patterns

Project Organization:

• Nao espalhar a logica Chronos diretamente em cada endpoint.
• Colocar a camada nova sob src/lib/ ou estrutura equivalente leve dentro do monolito.
• Organizacao recomendada:
  • src/lib/chronos/ChronosTokenProvider.php
  • src/lib/chronos/ChronosClient.php
  • src/lib/chronos/ChronosMapper.php
  • src/lib/cobranca/TituloConsolidadoService.php
  • src/lib/cobranca/TituloClassificationService.php
• Endpoints em src/api/* devem virar consumidores dessa camada, nao novos centros de regra.

File Structure Patterns:

• Um arquivo por classe nova.
• Nenhuma classe nova em arquivos de pagina raiz.
• Nenhum acoplamento da Chronos em JavaScript do dashboard.
• Se houver configuracao especifica da integracao, preferir arquivo proprio de apoio em config/ ou leitura de ambiente em um ponto central.

Format Patterns

API Response Formats:

• Manter o wrapper atual de cada endpoint.
• Quando o endpoint hoje retorna {data: [...]}, continuar com {data: [...]}.
• Quando o endpoint hoje retorna {error: false, data: [...]}, continuar com esse formato.
• Campos novos devem ser aditivos, nunca substituindo campos já usados pelo frontend.

Data Exchange Formats:

• cpf_cnpj sempre trafega normalizado para somente dígitos internamente.
• Datas em payload seguem o formato já esperado pelo endpoint consumidor:
  • YYYY-MM-DD quando operacional
  • YYYY-MM-DD HH:MM:SS ou valor atual, se o endpoint já trabalha assim
• Valores monetarios trafegam como numero decimal, nao string formatada.
• Booleanos internos devem ser booleanos reais ou inteiros compatíveis com o endpoint atual, sem misturar 'true', 'false', 'SIM', 'NAO'.

Communication Patterns

Event System Patterns:

• Nao introduzir barramento de eventos no MVP.
• A comunicacao entre componentes novos deve ser por chamada direta de servico/adapter.
• O “contrato de comunicacao” entre camadas passa a ser o TituloConsolidado.

State Management Patterns:

• O estado da classificacao deve ser recalculado no backend a partir das fontes, nao memorizado no frontend.
• Persistencia de estado funcional so no MySQL quando a operacao exigir, como no caso de 30 dias.
• Nenhum endpoint deve manter sua propria variante da regra de classificacao se a camada central puder responder.

Process Patterns

Error Handling Patterns:

• Cliente Chronos deve encapsular HTTP status, body resumido e contexto minimo da chamada.
• Servicos internos retornam dados ou lancam excecoes de dominio/integracao claras.
• Endpoints traduzem isso para o contrato JSON atual e fazem degradacao controlada quando a falha for apenas da Chronos.
• Separar:
  • erro tecnico para log
  • resposta tolerante para o usuario

Loading State Patterns:

• Nenhuma mudanca arquitetural de loading no frontend.
• Se um endpoint consolidado levar mais tempo por causa da Chronos, a mitigacao principal deve ser backend e nao spinner novo por tela.
• A feature nao deve introduzir encadeamentos extras no navegador para carregar Bralar e Travessia em etapas separadas.

Enforcement Guidelines

All AI Agents MUST:

• preservar as queries SQL Server existentes e integrar Chronos por composicao
• reutilizar a camada TituloConsolidado e a classificacao centralizada, sem reimplementar regra por endpoint
• tratar cobranca_30dias_registros como fonte de verdade para 30 dias
• adicionar metadata nova em formato aditivo, sem quebrar payload atual
• manter Travessia/Bralar explicito em todos os pontos de exibição suportados pelo MVP
• registrar logs com contexto funcional suficiente, mas sem segredos

Pattern Enforcement:

• Revisar todo arquivo novo para garantir que esta em src/lib/ ou local equivalente da camada nova, e nao com regra solta em src/api.
• Revisar todo payload alterado para garantir compatibilidade do frontend atual.
• Revisar toda persistencia nova no MySQL para garantir naming em snake_case.
• Revisar toda classificacao nova para garantir uso da mesma ordem de precedencia definida na arquitetura.

Pattern Examples

Good Examples:

• quebras_listar.php chama TituloConsolidadoService::listarQuebras(...) e apenas adapta a resposta ao contrato JSON atual.
• pc_titulos_pagos.php usa TituloClassificationService para excluir itens que ja pertencem a 30 dias.
• pc_titulos_pagos_30d.php usa titulo_uid/ids Chronos persistidos no MySQL para enriquecer corretamente linhas Travessia.
• campos novos do payload: origem_sistema, marca_empresa, titulo_uid.

Anti-Patterns:

• colocar chamadas HTTP para Chronos diretamente dentro de cada endpoint sem camada compartilhada.
• classificar renegociacao em um endpoint por parcelFrequencyName e em outro por regra textual diferente.
• persistir somente proposta da Travessia no MySQL sem nenhum identificador real da parcela.
• retornar marcaEmpresa em um endpoint e marca_empresa em outro para o mesmo conceito novo.
• criar log com token OAuth2 completo ou payload bruto da Chronos sem filtro.

Project Structure & Boundaries

Complete Project Directory Structure

/var/www/html/cobranca-hml/
├── config/
│   ├── database.php
│   ├── database_sqlsrv.php
│   ├── juridico.php
│   ├── kb_routes.php
│   └── chronos.php                    # novo ponto central de configuracao da integracao
├── src/
│   ├── api/
│   │   ├── cobranca30/
│   │   │   └── registrar.php          # adaptar para rastreabilidade Travessia
│   │   ├── pc_titulos_pagos.php       # consumir camada consolidada
│   │   ├── pc_titulos_pagos_30d.php   # consumir camada consolidada
│   │   ├── indicadores_30dias.php     # consumir dados MySQL com rastreabilidade Travessia
│   │   └── quebras_listar.php         # consumir camada consolidada
│   ├── lib/
│   │   ├── chronos/
│   │   │   ├── ChronosTokenProvider.php
│   │   │   ├── ChronosClient.php
│   │   │   ├── ChronosMapper.php
│   │   │   └── ChronosContracts.php   # DTOs/arrays padronizados, opcional
│   │   ├── cobranca/
│   │   │   ├── TituloConsolidadoService.php
│   │   │   ├── TituloClassificationService.php
│   │   │   ├── TituloUidFactory.php
│   │   │   ├── TituloNormalization.php
│   │   │   └── TituloAuditContext.php
│   │   ├── Image.php
│   │   ├── Markdown.php
│   │   └── Sanitize.php
│   └── middleware/
│       └── auth_api.php
├── storage/
│   └── logs/                          # reaproveitar para logs técnicos da integração, se já existir política local
└── _evo-output/
    └── planning-artifacts/
        └── chronos-titulos/
            ├── prd.md
            ├── implementation-readiness-report.md
            └── architecture.md

Architectural Boundaries

API Boundaries:

• /src/api/* permanece como fronteira HTTP interna do sistema.
• Endpoints nao conhecem detalhes de OAuth2, endpoints Chronos ou mapping de payload bruto.
• Endpoints apenas:
  • validam sessao/perfil
  • leem parametros
  • chamam a camada consolidada
  • adaptam resposta ao contrato JSON atual

Component Boundaries:

• src/lib/chronos/* e responsavel apenas por autenticacao e leitura da API Chronos.
• src/lib/cobranca/* e responsavel por normalizacao, classificacao, consolidacao e rastreabilidade.
• src/api/* e responsavel apenas pela borda HTTP e compatibilidade com o dashboard.
• frontend continua separado e consome apenas JSON final.

Service Boundaries:

• ChronosTokenProvider: obtenção e cache do token.
• ChronosClient: chamadas HTTP, retries mínimos, parse básico e tratamento de falha.
• ChronosMapper: transforma payload bruto Chronos em estrutura intermediaria coerente.
• TituloNormalization: normaliza cpf_cnpj, proposta e chaves.
• TituloUidFactory: gera titulo_uid consistente por origem.
• TituloClassificationService: decide quebra, 30 dias, renegociacao e exclusões.
• TituloConsolidadoService: orquestra SQL Server + MySQL + Chronos para cada caso de uso.

Data Boundaries:

• SQL Server: somente leitura, sem mudança de query existente.
• MySQL: leitura e escrita operacional, incluindo extensao de rastreabilidade da Travessia.
• Chronos: leitura externa, sem persistir payload bruto como fonte de negocio.

Requirements to Structure Mapping

Feature/FR Mapping:

• Carteira Consolidada e Classificação Operacional

  • src/lib/cobranca/TituloConsolidadoService.php
  • src/lib/cobranca/TituloClassificationService.php
  • src/lib/cobranca/TituloNormalization.php
  • src/lib/cobranca/TituloUidFactory.php

• Fluxo de Quebras

  • src/api/quebras_listar.php
  • src/lib/cobranca/TituloConsolidadoService.php
  • src/lib/chronos/ChronosClient.php

• Fluxo de 30 Dias

  • src/api/cobranca30/registrar.php
  • src/api/pc_titulos_pagos_30d.php
  • src/api/indicadores_30dias.php
  • src/lib/cobranca/TituloConsolidadoService.php

• Fluxo de Renegociações

  • src/api/pc_titulos_pagos.php
  • src/lib/cobranca/TituloClassificationService.php
  • src/lib/chronos/ChronosMapper.php

• Governança, Auditoria e Resiliência

  • src/lib/cobranca/TituloAuditContext.php
  • config/chronos.php
  • logs da aplicação

Cross-Cutting Concerns:

• autenticacao e filtros de sessao: src/middleware/ + validacoes atuais de endpoint
• configuracao de ambiente: config/chronos.php
• normalizacao de dados: src/lib/cobranca/TituloNormalization.php
• logs tecnicos: camada de servico + error_log com prefixos padronizados

Integration Points

Internal Communication:

• endpoint -> TituloConsolidadoService
• TituloConsolidadoService -> SQL Server atual + MySQL atual + ChronosClient
• TituloConsolidadoService -> TituloClassificationService
• TituloConsolidadoService -> retorno uniforme para endpoint

External Integrations:

• Chronos OAuth2 token endpoint
• Chronos credits/parcels endpoints
• SQL Server Gestor90
• MySQL auxiliar interno

Data Flow:

1. endpoint recebe usuario + filtros
2. recupera carteira do cobrador no MySQL
3. consulta dados Bralar atuais conforme endpoint
4. consulta dados Chronos apenas para CPFs relevantes
5. normaliza linhas de ambas as fontes
6. classifica e exclui duplicidades
7. devolve payload compatível ao frontend

File Organization Patterns

Configuration Files:

• toda configuracao da Chronos deve ficar centralizada em config/chronos.php
• esse arquivo le variaveis de ambiente/servidor e nunca armazena segredo versionado
• database.php e database_sqlsrv.php nao devem ser poluídos com regra de negocio da feature

Source Organization:

• adapters externos em src/lib/chronos/
• consolidacao de dominio operacional em src/lib/cobranca/
• borda HTTP continua em src/api/
• nenhuma regra nova de negocio em JS ou pagina raiz

Test Organization:

• o projeto nao possui suite automatizada consolidada hoje
• para esta feature, a organizacao minima de verificacao deve ser:
  • checklist de homologacao em docs/artefatos EVO
  • cenarios de contrato conhecidos
  • logs de auditoria e comparacao manual
• se testes automatizados forem introduzidos depois, devem espelhar a fronteira de servicos em src/lib/

Asset Organization:

• sem novos assets obrigatórios no MVP
• ajustes de visual no dashboard devem ocorrer nos arquivos já existentes da tela/JS correspondente

Development Workflow Integration

Development Server Structure:

• desenvolvimento exclusivamente em /var/www/html/cobranca-hml
• sem branch paralela de runtime dentro do mesmo DocumentRoot
• feature flags controlam ativacao parcial da Chronos

Build Process Structure:

• nao ha build novo para esta feature
• deploy continua seguindo o processo atual do monolito
• dependencias novas devem ser evitadas no MVP

Deployment Structure:

• configuracao separada por ambiente
• homologacao usa dominio proprio e bancos MySQL isolados
• publicacao futura em producao deve replicar apenas os arquivos e configuracoes aprovados, sem misturar com experimentos de HML

Architecture Validation Results

Coherence Validation ✅

Decision Compatibility: As decisoes principais nao entram em conflito entre si. A opcao por manter o monolito PHP atual, nao usar starter externo, nao alterar queries SQL Server e introduzir uma camada interna de consolidacao e compativel com o brownfield existente. A decisao de usar Chronos apenas no backend tambem e coerente com a seguranca definida no PRD e com o modo atual de funcionamento do dashboard.

Pattern Consistency: Os padroes definidos reforcam as decisoes arquiteturais. Naming, formato de payload, localizacao das classes novas e estrategia de logging estao alinhados com a ideia de manter os endpoints como borda HTTP e mover a inteligencia da feature para src/lib/chronos/ e src/lib/cobranca/. Isso reduz a chance de implementacoes divergentes entre agentes ou arquivos diferentes.

Structure Alignment: A estrutura proposta suporta o desenho tecnico sem exigir refatoracao ampla do repositorio. Os novos componentes vivem em areas coerentes com a organizacao ja existente, e os endpoints impactados estao claramente mapeados. A separacao entre adaptador externo, consolidacao de dominio e borda HTTP ficou suficientemente clara para implementacao incremental.

Requirements Coverage Validation ✅

Epic/Feature Coverage: Mesmo sem epicos criados ainda, a arquitetura cobre a feature chronos-titulos como um todo. Os fluxos de quebras, 30 dias, renegociacoes, indicadores e rastreabilidade foram explicitamente contemplados nas decisoes e na estrutura.

Functional Requirements Coverage: Os FRs do PRD estao arquiteturalmente suportados. A camada TituloConsolidado cobre consolidacao, origem e view model uniforme. TituloClassificationService cobre classificacao deterministica, precedencia e nao duplicidade. Os endpoints mapeados cobrem os fluxos obrigatorios do MVP. O papel do MySQL como fonte de verdade de 30 dias tambem foi mantido.

Non-Functional Requirements Coverage: Os NFRs mais importantes estao respondidos na arquitetura:

• performance: minimizacao de chamadas e ausencia de pipeline novo
• seguranca: backend-only, segredos fora do repo, sem token no frontend
• confiabilidade: degradacao controlada em falhas da Chronos
• observabilidade: logs e contexto funcional de classificacao
• rollout: feature flags e homologacao separada

Implementation Readiness Validation ✅

Decision Completeness: As decisoes criticas para comecar a implementacao estao fechadas. Isso inclui stack, boundaries, contracts internos, estrategia de integracao, politica de erro, rollout e impacto por endpoint. Nao restou nenhuma decisao estrutural grande em aberto para o MVP.

Structure Completeness: A estrutura fisica do projeto para a feature esta suficientemente definida: configuracao, classes novas, endpoints consumidores, limites de responsabilidade e fluxo de dados. Isso e suficiente para guiar os proximos artefatos e a implementacao.

Pattern Completeness: Os principais pontos onde agentes poderiam divergir foram cobertos: naming, localizacao de codigo, campos de payload, persistencia de rastreabilidade, tratamento de erro, classificacao e logging. Isso reduz bastante o risco de conflitos de implementacao.

Gap Analysis Results

Critical Gaps:

• Nao existe ainda o documento de epicos/historias rastreando os FRs para unidades de implementacao.

Important Gaps:

• Nao existe ainda um artefato leve de UX para congelar detalhes de badges, colunas e exibicao incremental no dashboard.
• A extensao exata do schema MySQL para rastreabilidade da Travessia ainda precisara ser especificada no breakdown tecnico de implementacao.

Nice-to-Have Gaps:

• Futuro refinamento de observabilidade com métricas mais estruturadas.
• Documentacao de casos de homologacao por contrato real.

Validation Issues Addressed

O principal risco detectado antes da arquitetura era cair em implementacao espalhada por endpoints. Isso foi resolvido nesta arquitetura ao definir uma camada compartilhada de consolidacao e classificacao. Outro risco era perder rastreabilidade dos titulos Travessia no fluxo 30 dias; isso foi tratado ao prever metadata persistente no MySQL e um titulo_uid unico por linha consolidada.

Architecture Completeness Checklist

✅ Requirements Analysis

• [x] Project context thoroughly analyzed
• [x] Scale and complexity assessed
• [x] Technical constraints identified
• [x] Cross-cutting concerns mapped

✅ Architectural Decisions

• [x] Critical decisions documented with versions/context
• [x] Technology stack fully specified
• [x] Integration patterns defined
• [x] Performance and resiliency considerations addressed

✅ Implementation Patterns

• [x] Naming conventions established
• [x] Structure patterns defined
• [x] Communication patterns specified
• [x] Process patterns documented

✅ Project Structure

• [x] Complete directory structure defined
• [x] Component boundaries established
• [x] Integration points mapped
• [x] Requirements to structure mapping complete

Architecture Readiness Assessment

Overall Status: READY FOR EPICS AND IMPLEMENTATION BREAKDOWN

Confidence Level: high

Key Strengths:

• protege o brownfield e evita regressao na Bralar
• centraliza a regra nova em camada unica reutilizavel
• respeita a restricao critica de nao tocar SQL Server
• deixa clara a responsabilidade de cada endpoint afetado
• ja prepara rastreabilidade e rollout seguro

Areas for Future Enhancement:

• UX leve para congelar detalhes de apresentacao
• epicos/historias com rastreabilidade FR a FR
• testes automatizados ou harness tecnico para regressao futura

Implementation Handoff

AI Agent Guidelines:

• seguir a camada src/lib/chronos/ e src/lib/cobranca/ como centro da feature
• nao colocar regra Chronos solta em endpoints ou JavaScript
• preservar contratos atuais dos endpoints e adicionar apenas campos novos compatíveis
• tratar cobranca_30dias_registros como fonte de verdade operacional de 30 dias
• nao alterar scripts SQL Server existentes sem nova confirmacao do usuario

First Implementation Priority: Criar a camada interna de integracao Chronos e o contrato TituloConsolidado, incluindo token provider, client HTTP, mapper, normalizacao, titulo_uid e classificacao centralizada.