Arquitetura

Classificacao

Projeto web, single-part, brownfield, com arquitetura monolitica em PHP e uso de dois bancos de dados para responsabilidades diferentes.

Visao de alto nivel

flowchart LR
    U[Usuario autenticado] --> P[Pagina PHP]
    P --> H[Header e Footer compartilhados]
    P --> J[JavaScript da pagina]
    J --> A[APIs internas em /src/api]
    A --> MY[(MySQL)]
    A --> MS[(SQL Server Gestor90)]
    A --> FS[(storage/documentos)]
    P --> KB[Modulo KB]
    KB --> MY

Estilo arquitetural

Monolito orientado a paginas

As telas principais estao na raiz do projeto. Cada pagina serve HTML inicial, enquanto a maior parte da interatividade depende de fetches para endpoints em src/api.

Backend hibrido

Ha dois estilos convivendo:

• procedural dominante em paginas e endpoints;
• objetos localizados em modulos mais novos, como o KB.

Persistencia hibrida

• SQL Server concentra dados operacionais da carteira, propostas, parcelas, recebimentos e clientes.
• MySQL guarda autenticacao, usuarios, historicos, tabelas auxiliares, documentos, configuracoes e modulos internos.

Fluxos arquiteturais principais

1. Login e sessao

sequenceDiagram
    participant U as Usuario
    participant L as index.php
    participant C as loginController.php
    participant M as MySQL
    U->>L: abre login
    U->>C: POST email/senha
    C->>M: consulta tabela usuarios
    C->>C: valida senha e perfil
    C->>C: popula sessao PHP
    C->>C: chama marcar_pago.php
    C-->>U: redireciona para dashboard

Observacoes:

• sessao usa rolling timeout implementado em session_boot.php
• autenticacao de API usa auth_api.php

2. Dashboard gerencial

flowchart LR
    DG[dashboard_gerencia.php] --> JS[js/dashboard.js]
    JS --> DD[dashboard_data.php]
    JS --> T1[src/api/abertos_trend.php]
    JS --> T2[src/api/aging_anual.php]
    JS --> T3[src/api/receb_tipoparc_trend.php]
    JS --> T4[src/api/inadimplencia_trend.php]
    JS --> T5[src/api/inadimplencia_residencial.php]
    JS --> T6[src/api/ranking_cobradores.php]
    DD --> SQL[(SQL Server)]

3. Distribuicao de carteira

flowchart TD
    PD[painel_distribuicao.php] --> PJS[js/painel_distribuicao.js]
    PJS --> CART[src/api/carteira.php]
    PJS --> RES[src/api/resumo_distribuicao.php]
    PJS --> DIST[src/api/distribuir_pendentes.php]
    PJS --> ATR[src/api/atribuir.php]
    DIST --> FC[src/api/functions_cobranca.php]
    FC --> SQL[(SQL Server)]
    FC --> MYSQL[(MySQL)]

4. Fluxo de documentos do cliente

flowchart LR
    HC[Tela de historico/ficha] --> DJS[assets/js/documentos_cliente.js]
    DJS --> DL[src/api/documentos/listar.php]
    DJS --> DU[src/api/documentos/upload.php]
    DJS --> DR[src/api/documentos/remover.php]
    DJS --> DZ[src/api/documentos/pacote_zip.php]
    DU --> DT[(documentos_cliente)]
    DU --> FS[(storage/documentos)]

5. Base de conhecimento

O modulo KB e o bloco mais organizado do sistema:

• controllers em src/controllers/kb
• models em src/models/kb
• views em src/views/kb
• assets dedicados em public/assets/kb
• schema formal em database/kb_schema.sql

Componentes e responsabilidades

Camada de apresentacao

• paginas raiz *.php
• partials compartilhados
• componentes de dashboard em src/views/components

Camada de interacao frontend

• scripts em js/
• scripts especializados em assets/js/
• uso de fetch, Bootstrap, DataTables e Chart.js

Camada de aplicacao

• endpoints src/api/*
• controllers KB
• middleware de autenticacao/sessao

Camada de dados

• config/database.php
• config/database_sqlsrv.php
• SQL embutido nos endpoints
• tabelas auxiliares criadas sob demanda

Integracoes externas identificadas

• SQL Server Gestor90
• Z-API para envio de WhatsApp em send_whatsapp.php
• Gemini/OpenRouter para revisao de observacoes e configuracao de IA

Autorizacao

Perfis observados:

• gerencia
• cobrador

Implementacao:

• paginas normalmente validam $_SESSION['user_perfil']
• APIs validam sessao e, em varios casos, perfil explicito

Riscos arquiteturais relevantes

• Credenciais em arquivos versionados.
• Queries SQL extensas sem camada de abstracao comum.
• Acoplamento entre tela, script e endpoint sem contratos formais centralizados.
• Inicializacao de schema em runtime por alguns endpoints.
• Ausencia de testes automatizados para proteger refatoracoes.