Visao Geral do Sistema de Cobranca

Objetivo

O repositorio implementa um sistema interno de cobranca com dois perfis principais:

• gerencia: acompanha KPIs, distribui carteira, controla usuarios, metas, gratificacoes, carteira saudavel, juridico e base de conhecimento.
• cobrador: trabalha a carteira, registra historicos, acompanha lembretes, conferencia de recebimentos e operacao diaria.

O sistema centraliza tres tipos de uso:

1. Operacao de cobranca e acompanhamento de clientes.
2. Inteligencia gerencial sobre inadimplencia, recebimentos e produtividade.
3. Registro auxiliar no MySQL para sustentar operacao, trilha historica e modulos internos.

Modelo de funcionamento

O sistema nao e um SPA. A pagina HTML e montada no servidor em PHP e, depois do carregamento, JavaScript consome endpoints JSON em /src/api/* para preencher dashboards, tabelas, modais e automacoes.

Ha uma divisao pratica entre bancos:

• SQL Server: fonte operacional de negocio financeiro e carteira.
• MySQL: autenticacao, configuracoes, historico interno, filas operacionais, documentos, usuarios e modulos auxiliares.

Principais dominios funcionais

1. Dashboards e indicadores

• dashboard_gerencia.php: visao analitica da gerencia.
• dashboard_digital.php e dashboard_digital_black.php: painois executivos com KPIs e visual forte.
• dashboard_cobrador.php: lembretes e operacao do cobrador.
• APIs ligadas: dashboard_data.php, src/api/dashboard_digital/*, src/api/*trend.php, src/api/ranking_cobradores.php.

2. Carteira e distribuicao

• painel_distribuicao.php: distribuicao automatica e manual da carteira entre cobradores.
• src/api/functions_cobranca.php: logica de atribuicao e atendimento.
• src/api/carteira.php, src/api/resumo_distribuicao.php, src/api/distribuir_pendentes.php, src/api/atribuir.php.

3. Historico e contatos

• consulta_historicos.php: busca de clientes e historicos.
• src/contatos/*: ficha geral, historico de contatos, comunicacao, parcelas e IA para revisar observacoes.
• Tabela central identificada: historico_contato.

4. Fluxo 30 dias e renegociacao

• acompanhamento_30dias.php
• acompanhamento_renegociacao.php
• src/api/cobranca30/registrar.php
• src/api/cobranca30/marcar_pago.php
• src/api/indicadores_30dias.php
• src/api/indicadores_renegociacao.php

5. Fechamento, metas e gratificacoes

• metas.php
• param_gratificacoes.php
• fechamento_gratificacoes.php
• src/api/pc_metas_*
• src/api/grat_*

6. Carteira saudavel / clientes inativos

• carteira_saudavel.php
• src/api/clientes_inativos_*
• src/api/clientes_buscar_sqlserver.php
• src/api/carteira_saudavel_indicadores.php

7. Documentos do cliente

• Frontend: assets/js/documentos_cliente.js
• Backend: src/api/documentos/*
• Persistencia auxiliar: tabela documentos_cliente
• Armazenamento fisico: storage/documentos/<cpf>/

8. Juridico

• acompanhamento_juridico.php
• src/api/juridico/check.php
• src/api/juridico/encaminhar.php
• JS compartilhado: js/juridico_status_helper.js

9. Base de conhecimento

• Navegacao em /kb
• Controllers em src/controllers/kb/*
• Models em src/models/kb/*
• Assets em public/assets/kb/*
• Banco proprio dentro do MySQL principal: kb_categories, kb_articles, kb_media

Stack tecnica observada

• Backend: PHP procedural com alguns modulos OO isolados
• Frontend: Bootstrap 5, Bootstrap Icons, JavaScript vanilla, jQuery e DataTables em pontos especificos
• Dependencias PHP via Composer:
  • erusev/parsedown
  • ezyang/htmlpurifier
  • dompdf/dompdf
• Servidor: Apache com PHP-FPM
• Configuracao de runtime em .user.ini

Restricoes arquiteturais relevantes

• Nao existe camada unica de dominio; regras de negocio estao distribuidas entre paginas, endpoints e scripts.
• Parte das tabelas e criada dinamicamente pelo proprio codigo no primeiro uso.
• Existem credenciais e configuracoes sensiveis em arquivos versionados, o que exige cuidado em qualquer refatoracao.
• Integracoes externas e consultas pesadas dependem de SQL escrito manualmente, sem ORM.