# Documentação dos sistemas em `/var/www/html`

## Objetivo deste documento

Eu deixei este material para facilitar a transição de quem assumir o ambiente depois de mim. A ideia aqui é explicar, de forma prática:

- o que existe dentro de `/var/www/html`
- para que serve cada sistema
- como cada solução está estruturada
- como acessar ou executar
- onde ficam os pontos mais sensíveis de manutenção

O ambiente hoje roda principalmente em `nginx` com `php8.3-fpm`. A aplicação nova de cobranças também roda como serviço `systemd`.

## Visão geral do ambiente

Os principais blocos que estão ativos ou servem como base operacional são:

- `cobrancas_app` + `bling` + `locacao`
- `Contratos`
- `propostas`
- `Rastrear`
- `faturamento`
- `api/BancoBrasil` e `api/banco`
- `api/whatsapp`
- `w-api`
- `botconversa`
- `Lexmark_solution`
- `impressoras`
- `dash`
- `gerar_locais`
- `scripts`
- `bling_v3` e `bling_v3_serv`

Também existem diretórios de apoio:

- `shared`: arquivos compartilhados entre módulos
- `storage`: banco local e arquivos gerados
- `tests`: testes da aplicação nova de cobranças
- `src`: assets pontuais

## Inventário completo das pastas de primeiro nível

Para não ficar dúvida sobre escopo, abaixo está o inventário de todas as pastas que existem diretamente dentro de `/var/www/html` no momento desta documentação.

### `Contratos`

- sistema de cadastro, edição, listagem e impressão de contratos
- persistência em `contratos.json`
- detalhado na seção `2. Contratos`

### `Lexmark_solution`

- solução de impressão via QR Code e upload pelo celular para impressora Lexmark
- trabalha com sessões, token, upload, merge de PDF e download final
- detalhado na seção `11. Solução Lexmark para impressão via celular`

### `Rastrear`

- painel para vincular código de rastreio a notas fiscais filtradas no Bling
- usa `rastreamento.json` e rotina automática por cron
- detalhado na seção `4. Rastreamento de notas / transportadora`

### `api`

- concentração de integrações em PHP
- inclui Banco do Brasil, webhooks de nota fiscal, estoque, chamados, WhatsApp e integração auxiliar com `w-api`
- detalhado nas seções `6. Banco do Brasil`, `7. APIs e webhooks diversos em /api` e `8. API de WhatsApp em PHP`

### `bling`

- legado de cobrança do comércio
- mantém rotas antigas por campanha como `Hoje`, `Amanha`, `Aviso`, `Vencidos` e `PorPeriodo`
- hoje os `cobrar.php` funcionam como ponte para a aplicação Python de cobranças
- também guarda arquivos PDF em `bling/arquivos`
- está coberto na seção `1. Cobranças novas e legado de campanhas`

### `bling_v3`

- estrutura de autenticação do Bling para o contexto de comércio
- guarda scripts de renovação e `token_data.json`
- dependência de vários módulos do ambiente
- detalhado na seção `15. Tokens do Bling`

### `bling_v3_serv`

- estrutura de autenticação do Bling para o contexto de serviço
- espelha a lógica de `bling_v3`, com token separado
- detalhado na seção `15. Tokens do Bling`

### `botconversa`

- integrações operacionais com BotConversa
- inclui busca de cliente, boletos, demonstrativos, PIX, arquivos e automações de atendimento
- detalhado na seção `10. BotConversa`

### `cobrancas_app`

- aplicação nova de cobranças em Python
- concentra worker, dashboard Flask, banco local e rastreio de execução
- detalhado na seção `1. Cobranças novas e legado de campanhas`

### `dash`

- dashboard visual de acompanhamento operacional do ServicePlus
- focado em monitoramento e exibição de indicadores
- detalhado na seção `13. Dashboard TV / ServicePlus`

### `faturamento`

- automação de envio de demonstrativos e boletos
- lê e-mail, extrai PDF, consulta Bling, gera boleto e envia ao cliente
- detalhado na seção `5. Faturamento`

### `gerar_locais`

- busca locais e gera etiquetas em PDF
- usa Google Places e FPDF
- detalhado na seção `14. Geração de etiquetas de locais`

### `impressoras`

- cadastro/consulta de dispositivos, contadores e logs de impressoras
- inclui tela de configuração e API de consulta
- detalhado na seção `12. Impressoras / ESP32 / contadores`

### `locacao`

- legado de cobrança para contratos e clientes de locação/ServicePlus
- tem campanhas equivalentes a `bling`, além de pasta `ServicePlus`
- hoje os `cobrar.php` principais também chamam a aplicação Python
- está coberto na seção `1. Cobranças novas e legado de campanhas`

### `propostas`

- bloco de propostas comerciais
- tem consulta direta no Bling e também área de locação com dashboard e formulário próprios
- detalhado na seção `3. Propostas`

### `scripts`

- scripts auxiliares de operação e automação
- inclui relatório diário de cobranças, lembretes de eventos e outros utilitários
- detalhado na seção `16. Scripts auxiliares`

### `shared`

- arquivos compartilhados por mais de um sistema
- hoje o principal é a ponte PHP que chama o worker Python de cobranças
- detalhado na seção `17. Estruturas de apoio`

### `src`

- pasta de assets pontuais
- no momento encontrei apenas `logo.png`
- não é um sistema isolado; funciona como apoio visual
- detalhado na seção `17. Estruturas de apoio`

### `storage`

- armazenamento local de artefatos gerados pela aplicação
- hoje é mais importante para `cobrancas_app`, com SQLite e PDFs
- detalhado na seção `17. Estruturas de apoio`

### `tests`

- testes da aplicação nova de cobranças em Python
- serve como base de validação para evolução desse módulo
- detalhado na seção `17. Estruturas de apoio`

### `w-api`

- projeto Node.js para webhook, persistência de mensagens e painel/socket de WhatsApp
- detalhado na seção `9. W-API em Node.js`

## Publicação e serviços

### Serviços do servidor

Os serviços que encontrei habilitados são:

- `nginx.service`
- `php8.3-fpm.service`
- `cobrancas-flask.service`

### Crons ativos

O `crontab` atual tem as seguintes rotinas principais:

- renovação de token Bling em `bling_v3/new_token.php`
- renovação de token Bling em `bling_v3_serv/new_token.php`
- sincronização Banco do Brasil em `/var/www/html/api/BancoBrasil/index.php`
- campanhas de cobrança em Python para comércio e ServicePlus
- atualização de rastreamento via `/var/www/html/Rastrear/api.php`
- envio de relatório diário de cobranças via `/var/www/html/scripts/relatorio_cobrancas.php`

## 1. Cobranças novas e legado de campanhas

### Diretórios envolvidos

- `/var/www/html/cobrancas_app`
- `/var/www/html/bling`
- `/var/www/html/locacao`
- `/var/www/html/shared`
- `/var/www/html/storage/cobrancas`

### O que este bloco faz

Esse é hoje o núcleo mais importante de cobrança automática. Eu mantive as URLs e alguns pontos de entrada em PHP por compatibilidade, mas a execução principal foi migrada para uma aplicação Python.

Ela atende dois cenários:

- cobrança de comércio via Bling
- cobrança de locação/serviço via banco ServicePlus

As campanhas existentes são:

- `hoje`
- `amanha`
- `aviso`
- `vencidos`

### Como está feito

A aplicação nova está em `cobrancas_app` e tem:

- worker CLI em Python
- dashboard Flask
- persistência local em SQLite
- geração/armazenamento de PDFs
- integração com Bling
- integração com ServicePlus
- integração com envio por e-mail e WhatsApp

Os arquivos legados `bling/*/cobrar.php` e `locacao/*/cobrar.php` hoje funcionam só como ponte. Eles chamam o arquivo compartilhado:

- `/var/www/html/shared/cobrancas_python_bridge.php`

Esse bridge executa:

```bash
python3 -m cobrancas_app.cli run --source <origem> --campaign <campanha>
```

### Como acessar

Dashboard novo:

- `https://srv618364.hstgr.cloud/cobrancas/`

Rotas principais do dashboard:

- `/`
- `/runs/<id>`
- `/items/<id>`

### Como executar manualmente

```bash
cd /var/www/html
python3 -m cobrancas_app.cli run --source bling --campaign hoje
python3 -m cobrancas_app.cli run --source bling --campaign amanha
python3 -m cobrancas_app.cli run --source bling --campaign aviso
python3 -m cobrancas_app.cli run --source bling --campaign vencidos

python3 -m cobrancas_app.cli run --source serviceplus --campaign hoje
python3 -m cobrancas_app.cli run --source serviceplus --campaign amanha
python3 -m cobrancas_app.cli run --source serviceplus --campaign aviso
python3 -m cobrancas_app.cli run --source serviceplus --campaign vencidos
```

Para subir o dashboard localmente:

```bash
cd /var/www/html
python3 -m cobrancas_app.cli serve --host 0.0.0.0 --port 5050
```

### Onde ficam os dados

- banco SQLite: `/var/www/html/storage/cobrancas/app.db`
- PDFs gerados/baixados: `/var/www/html/storage/cobrancas/generated`
- backup de cron anterior: `/var/www/html/storage/cobrancas/crontab.backup.before_python`

### Arquivos mais importantes

- `/var/www/html/cobrancas_app/README.md`
- `/var/www/html/cobrancas_app/config.py`
- `/var/www/html/shared/cobrancas_python_bridge.php`

### Observações de manutenção

- o módulo novo já centraliza a cobrança melhor que os scripts antigos
- os diretórios `bling` e `locacao` ainda importam porque os crons e acessos antigos podem depender deles
- `locacao/index.php` hoje redireciona para `painel-cobrancas.php?empresa=servico`

## 2. Contratos

### Diretório

- `/var/www/html/Contratos`

### O que faz

Esse sistema é um cadastro e painel de contratos. Ele salva tudo em arquivo JSON local, sem banco de dados.

Principais ações:

- listar contratos
- criar contrato
- editar
- excluir
- gerar/imprimir documentos

### Como está feito

O arquivo principal é:

- `/var/www/html/Contratos/index.php`

O cadastro usa como base:

- `/var/www/html/Contratos/contratos.json`

O formulário de criação está em:

- `/var/www/html/Contratos/novo.php`

### Como acessar

- `https://srv618364.hstgr.cloud/Contratos/`

### Como usar

- entrar no dashboard
- usar o botão de novo contrato
- preencher os campos da empresa, cobrança e equipamentos
- o sistema grava no `contratos.json`

### Observações de manutenção

- como usa JSON local, conflitos manuais e corrupção de arquivo podem impactar o funcionamento
- se o JSON quebrar, a listagem pode ficar vazia ou falhar
- não existe camada forte de concorrência para edição simultânea

## 3. Propostas

### Diretório

- `/var/www/html/propostas`

### O que faz

Esse módulo é para propostas comerciais. Existe uma parte mais simples em `/propostas/index.php` que consulta propostas do Bling, e uma parte mais operacional em:

- `/var/www/html/propostas/locacao`

Nessa área de locação eu mantive:

- formulário de proposta
- dashboard
- persistência em JSON local
- exclusão

### Como está feito

Arquivos principais:

- `/var/www/html/propostas/locacao/dashboard.php`
- `/var/www/html/propostas/locacao/formulario.php`
- `/var/www/html/propostas/locacao/excluir.php`

Os dados ficam em:

- `propostas.json` dentro da pasta `locacao`

O formulário grava ou atualiza propostas pelo número da proposta.

### Como acessar

Dashboard de locação:

- `https://srv618364.hstgr.cloud/propostas/locacao/dashboard.php`

Consulta de propostas do Bling:

- `https://srv618364.hstgr.cloud/propostas/`

### Como usar

- abrir o dashboard
- cadastrar uma nova proposta ou editar uma existente
- usar o campo de CNPJ para auto preenchimento quando aplicável
- acompanhar a situação por `Rascunho`, `Aprovado` ou `Nao aprovado`

### Observações

- assim como em contratos, a persistência é em JSON
- a parte `/propostas/index.php` usa API antiga do Bling para consulta

## 4. Rastreamento de notas / transportadora

### Diretório

- `/var/www/html/Rastrear`

### O que faz

Esse módulo consulta notas no Bling, filtra por transportadora e permite cadastrar ou atualizar código de rastreio por nota.

Também existe rotina automática via cron:

- `*/15 * * * * /usr/bin/php /var/www/html/Rastrear/api.php`

### Como está feito

Arquivo principal:

- `/var/www/html/Rastrear/index.php`

Arquivo de dados:

- `/var/www/html/Rastrear/rastreamento.json`

Salvamento:

- `/var/www/html/Rastrear/save_rastreamento.php`

### Como acessar

- `https://srv618364.hstgr.cloud/Rastrear/`

### Como usar

- abrir a lista
- localizar a nota
- preencher o código de rastreio
- clicar em salvar

### Observações

- depende de token do Bling disponível em `bling_v3/token_data.json`
- também cruza dados com `/var/www/html/bling/clientes.json`

## 5. Faturamento

### Diretório

- `/var/www/html/faturamento`

### O que faz

Esse bloco lê e-mails de demonstrativos, extrai anexos PDF, busca os dados no Bling, gera o PDF do boleto e envia demonstrativo + boleto por e-mail. Em alguns fluxos também existe integração com WhatsApp.

### Como está feito

Arquivos principais:

- `/var/www/html/faturamento/monitor.php`
- `/var/www/html/faturamento/enviar.php`
- `/var/www/html/faturamento/gerar_demonstrativos.php`

Pasta de saída:

- `/var/www/html/faturamento/demonstrativos`

Dependências:

- Composer / PHPMailer
- IMAP
- `wkhtmltopdf`

### Como executar

Exemplo manual:

```bash
cd /var/www/html/faturamento
php monitor.php
php enviar.php
```

### Como funciona na prática

- conecta na caixa de e-mail do financeiro
- procura e-mails de demonstrativo
- salva os PDFs
- consulta contas a receber do Bling
- busca o e-mail do cliente
- gera o boleto em PDF a partir da URL
- envia os anexos para o cliente

### Observações

- esse módulo depende muito de formato do e-mail, disponibilidade do IMAP e HTML do boleto
- se o layout do e-mail de origem mudar, a extração por regex pode falhar

## 6. Banco do Brasil

### Diretórios

- `/var/www/html/api/BancoBrasil`
- `/var/www/html/api/banco`

### O que faz

Essa integração consulta boletos liquidados/baixados no Banco do Brasil e envia os dados para um webhook interno.

### Como está feito

Arquivo principal do cron:

- `/var/www/html/api/BancoBrasil/index.php`

Webhook receptor:

- `/var/www/html/api/banco/webhook_bb.php`

Log:

- `/var/www/html/api/banco/webhook_bb_log.txt`

### Como executa hoje

Via cron a cada 30 minutos:

```bash
php /var/www/html/api/BancoBrasil/index.php
```

### Observações

- usa biblioteca PHP de Banco do Brasil instalada por Composer
- existem dois conjuntos de convênio/credenciais dentro do script
- importante validar o webhook se houver troca de endpoint ou convênio

## 7. APIs e webhooks diversos em `/api`

### Diretório

- `/var/www/html/api`

### O que existe aqui

#### 7.1 Webhook de nota fiscal / cobrança

Arquivo:

- `/var/www/html/api/index.php`

Função:

- recebe webhook
- cruza nota fiscal com contas a receber no Bling
- tenta localizar telefone
- envia mensagem via WhatsApp/Evolution/ServicePlus
- grava log em `/var/www/html/api/webhook.log`

Uso típico:

- acionado automaticamente por integração externa

#### 7.2 Estoque comércio e serviço

Arquivos:

- `/var/www/html/api/estoque.php`
- `/var/www/html/api/estoque_serv.php`

Função:

- recebem payload de estoque
- reenviam dados para automação do BotConversa

#### 7.3 Chamados / monitoramento

Arquivo:

- `/var/www/html/api/chamados/monitor.php`

Função:

- monitora caixas de e-mail de técnicos
- identifica chamados
- envia alertas e mensagens pelo BotConversa
- também verifica status de comunicação de equipamentos por número de série

### Observações

- essa pasta concentra integrações bem específicas e de alto acoplamento
- antes de alterar qualquer webhook, eu sempre validaria o payload real recebido em produção

## 8. API de WhatsApp em PHP

### Diretório

- `/var/www/html/api/whatsapp`

### O que faz

Esse é um router em PHP para consulta de contatos, conversas, mensagens, dashboard e busca sobre dados do WhatsApp.

Ele trabalha sobre o banco do ServicePlus.

### Como está feito

Arquivos principais:

- `/var/www/html/api/whatsapp/index.php`
- `/var/www/html/api/whatsapp/config.php`
- `/var/www/html/api/whatsapp/routes/*`

### Como acessar

Base:

- `http://srv618364.hstgr.cloud/api/whatsapp`

Se abrir `GET /api/whatsapp`, ele responde a documentação das rotas.

Exemplos úteis:

- `GET /api/whatsapp/dashboard`
- `GET /api/whatsapp/contatos`
- `GET /api/whatsapp/conversas`
- `GET /api/whatsapp/mensagens/recentes`
- `GET /api/whatsapp/busca?q=texto`

### Observações

- o `API_BASE_URL` está configurado em HTTP, não HTTPS
- essa API é só leitura/consulta no que revisei aqui

## 9. W-API em Node.js

### Diretório

- `/var/www/html/w-api`

### O que faz

Esse projeto em Node recebe webhooks, grava histórico de contatos/conversas/mensagens no banco `w_api`, expõe arquivos estáticos e usa Socket.IO para atualização em tempo real.

### Como está feito

Arquivo principal:

- `/var/www/html/w-api/index.js`

Dependências:

- Express
- MySQL2
- Socket.IO
- raw-body
- axios

### Como acessar

Painel estático:

- `http://<host>:3000/painel`

Webhook:

- `POST /webhook`

### Como executar manualmente

```bash
cd /var/www/html/w-api
npm install
node index.js
```

### Observações

- não encontrei serviço `systemd` específico desse projeto na varredura que fiz
- vale confirmar se ele está sendo gerenciado por PM2, screen ou execução manual em outro contexto

## 10. BotConversa

### Diretório

- `/var/www/html/botconversa`

### O que faz

Essa pasta concentra integrações de automação com BotConversa e alguns utilitários ligados a atendimento, cobrança, PIX, arquivos e atualização de conversa.

### Como está feito

A API principal que eu identifiquei foi:

- `/var/www/html/botconversa/api/index.php`

Esse endpoint:

- recebe `nome`, `telefone`, `cnpj` e `tipoEmpresa`
- consulta contato no Bling
- tenta localizar por CNPJ, telefone e nome
- devolve dados do cliente encontrado

Também existem outros endpoints auxiliares:

- boletos
- demonstrativos
- pedidos
- cadastrar contato
- criar chamado
- enviar PIX
- envio/listagem de arquivos

### Como acessar

Base provável:

- `https://srv618364.hstgr.cloud/botconversa/api/`

### Observações

- esse módulo depende de tokens do Bling em `bling_v3` e `bling_v3_serv`
- há bastante integração operacional com atendimento e automação externa

## 11. Solução Lexmark para impressão via celular

### Diretório

- `/var/www/html/Lexmark_solution`

### O que faz

Essa solução foi feita para permitir que a impressora Lexmark acione um fluxo de upload pelo celular. A impressora cria uma sessão, gera token/QR Code, o usuário abre no celular, envia os arquivos e depois a impressora baixa um PDF unificado para imprimir.

### Como está feito

Arquivos principais:

- `/var/www/html/Lexmark_solution/api.php`
- `/var/www/html/Lexmark_solution/upload.php`
- `/var/www/html/Lexmark_solution/download.php`
- `/var/www/html/Lexmark_solution/config.php`

Dependências:

- Composer
- `chillerlan/php-qrcode`
- `phpmailer/phpmailer`
- `setasign/fpdi`

### Fluxo resumido

1. a impressora chama `api.php?action=create`
2. o sistema cria uma sessão com token
3. o usuário acessa `upload.php?t=TOKEN`
4. envia PDF/imagens
5. a impressora consulta status
6. a impressora baixa o PDF final unificado
7. no final a sessão pode ser limpa

### Como acessar

URL publicada para celular:

- `https://srv618364.hstgr.cloud/Lexmark_solution`

URL definida para impressora:

- `http://147.79.86.218/Lexmark_solution`

### Onde ficam os arquivos

- uploads e sessões: `/var/www/html/Lexmark_solution/uploads`

### Observações

- a solução foi pensada com HTTP para a impressora porque a Lexmark não suporta HTTPS nesse fluxo
- a limpeza de sessões é importante para não acumular arquivos

## 12. Impressoras / ESP32 / contadores

### Diretório

- `/var/www/html/impressoras`

### O que faz

Esse módulo serve para listar dispositivos ESP32 cadastrados, abrir configuração e consultar dados de contadores/logs de impressoras via API.

### Como está feito

Arquivos principais:

- `/var/www/html/impressoras/config.php`
- `/var/www/html/impressoras/configurar.php`
- `/var/www/html/impressoras/registrar.php`
- `/var/www/html/impressoras/api/api.php`

### Como acessar

Lista principal:

- `https://srv618364.hstgr.cloud/impressoras/config.php`

API:

- `https://srv618364.hstgr.cloud/impressoras/api/api.php?endpoint=contadores`
- `https://srv618364.hstgr.cloud/impressoras/api/api.php?endpoint=logs&numero_serie=...`

### Observações

- a lista de MAC/IP é carregada de um JSON remoto
- a API usa banco `RAR_Monitoramento`

## 13. Dashboard TV / ServicePlus

### Diretório

- `/var/www/html/dash`

### O que faz

É um dashboard visual estilo TV para acompanhamento de chamados e indicadores do ServicePlus.

### Como está feito

Arquivo principal:

- `/var/www/html/dash/index.php`

Também existem:

- `/var/www/html/dash/api.php`
- `/var/www/html/dash/debug_tecnicos.php`
- `/var/www/html/dash/inspecionar_db.php`

### Como acessar

- `https://srv618364.hstgr.cloud/dash/`

### Observações

- é um painel mais visual/operacional do que um sistema transacional

## 14. Geração de etiquetas de locais

### Diretório

- `/var/www/html/gerar_locais`

### O que faz

Esse módulo busca locais, consulta detalhes no Google Places e gera PDF de etiquetas para impressão.

### Como está feito

Arquivos principais:

- `/var/www/html/gerar_locais/buscar_locais.php`
- `/var/www/html/gerar_locais/gerar_pdf.php`
- `/var/www/html/gerar_locais/config.php`

### Como usar

- pesquisar os locais
- selecionar os locais desejados
- enviar o formulário
- o sistema gera e baixa um PDF de etiquetas

### Observações

- depende de chave Google Maps/Places
- usa FPDF

## 15. Tokens do Bling

### Diretórios

- `/var/www/html/bling_v3`
- `/var/www/html/bling_v3_serv`

### O que fazem

Essas pastas guardam a renovação e armazenamento dos tokens de acesso do Bling para dois contextos:

- comércio
- serviço

### Arquivos principais

- `new_token.php`
- `token.php`
- `get_token.php`
- `token_data.json`
- `new_token.log`

### Como funciona

O cron renova os tokens periodicamente e grava os dados em `token_data.json`. Outros sistemas leem esse arquivo para autenticar nas APIs do Bling.

### Observações

- vários módulos dependem diretamente desses arquivos
- se a renovação falhar, o impacto se espalha para cobrança, rastreamento, propostas e integrações

## 16. Scripts auxiliares

### Diretório

- `/var/www/html/scripts`

### O que existe aqui

#### 16.1 Relatório diário de cobranças

Arquivo:

- `/var/www/html/scripts/relatorio_cobrancas.php`

Função:

- consulta a tabela `log_envios_cobrancas`
- monta resumo diário por empresa e tipo de cobrança
- envia relatório por WhatsApp

Log:

- `/var/www/html/scripts/relatorio_cobrancas.log`

#### 16.2 Lembretes de eventos

Diretório:

- `/var/www/html/scripts/lembretes_eventos`

Arquivo principal:

- `/var/www/html/scripts/lembretes_eventos/enviar_lembretes.php`

Função:

- procura eventos que vão começar nos próximos minutos
- envia lembrete por e-mail
- envia lembrete por WhatsApp
- marca o lembrete como enviado

#### 16.3 Outros scripts

Também existem arquivos como:

- `printwayy.php`
- `mods.php`
- `mods2.php`
- `mods3.php`
- `mods4.php`
- `relatorio.php`

Esses eu trataria como scripts auxiliares ou históricos. Se alguém for mexer, vale revisar individualmente antes de reusar em produção.

## 17. Estruturas de apoio

### `shared`

Arquivos importantes:

- `/var/www/html/shared/CobrancaLogStore.php`
- `/var/www/html/shared/cobrancas_python_bridge.php`

Uso:

- componentes compartilhados por mais de um fluxo

### `storage`

Uso:

- banco SQLite
- arquivos gerados pela aplicação de cobranças

### `tests`

Uso:

- testes Python da aplicação nova de cobranças

### `src`

Uso:

- assets pontuais, hoje encontrei apenas `logo.png`

## Acessos rápidos

Os acessos que eu considero mais úteis para quem assumir são:

- `https://srv618364.hstgr.cloud/cobrancas/`
- `https://srv618364.hstgr.cloud/Contratos/`
- `https://srv618364.hstgr.cloud/propostas/locacao/dashboard.php`
- `https://srv618364.hstgr.cloud/Rastrear/`
- `https://srv618364.hstgr.cloud/dash/`
- `https://srv618364.hstgr.cloud/impressoras/config.php`
- `https://srv618364.hstgr.cloud/Lexmark_solution`
- `http://srv618364.hstgr.cloud/api/whatsapp`

## Mapa de subpastas relevantes

Além das pastas de primeiro nível, estas são as subpastas mais importantes para operação e manutenção.

### Dentro de `bling`

- `Hoje`, `Amanha`, `Aviso`, `Vencidos`: campanhas legadas por faixa de vencimento
- `Periodo` e `PorPeriodo`: consultas e envios por período
- `arquivos`: PDFs de boleto e nota já gerados ou baixados

### Dentro de `locacao`

- `Hoje`, `Amanha`, `Aviso`, `Vencidos`, `PorPeriodo`: campanhas do fluxo de locação
- `ServicePlus`: material de apoio ao fluxo de serviço/locação
- `arquivos`: documentos gerados
- `src` e `vendor`: código de apoio e dependências PHP

### Dentro de `api`

- `BancoBrasil`: integração com emissão/consulta de boletos BB
- `banco`: webhook receptor dos retornos processados
- `chamados`: monitoramento e automação de chamados
- `w-api`: integração auxiliar com notificações
- `whatsapp`: API HTTP em PHP para consultas de mensagens e conversas

### Dentro de `Lexmark_solution`

- `uploads`: diretório principal de sessões e arquivos enviados
- `sessions`: sessões temporárias da solução
- `vendor`: dependências PHP instaladas por Composer

### Dentro de `botconversa`

- `api`: endpoints operacionais usados pelas automações
- `api/arquivos`: arquivos enviados ou disponibilizados
- `api/qrcodes` e `api/qrlib`: geração e apoio a QR Codes
- `api/vendor`: dependências PHP

### Dentro de `impressoras`

- `api`: endpoints para leitura de contadores, logs e cadastro/consulta

### Dentro de `faturamento`

- `demonstrativos`: PDFs processados ou gerados
- `vendor`: dependências PHP

### Dentro de `scripts`

- `lembretes_eventos`: rotina específica de aviso de eventos
- `lembretes_eventos/src` e `lembretes_eventos/vendor`: apoio da automação

### Dentro de `w-api`

- `routes`: rotas Node.js para processamento
- `painel`: frontend estático do painel
- `frontend`: experimentos ou interfaces auxiliares
- `node_modules`: dependências instaladas do projeto Node

### Dentro de `cobrancas_app`

- `templates`: templates HTML do dashboard
- `__pycache__`: cache de bytecode Python

### Dentro de `storage`

- `cobrancas`: armazenamento persistente da aplicação de cobranças
- `cobrancas/generated`: PDFs e arquivos produzidos pelas execuções

### Pastas que são dependências ou saída gerada

Estas pastas existem, mas eu trataria como infraestrutura de execução, não como sistemas para alterar regra de negócio:

- `vendor`
- `node_modules`
- `__pycache__`
- `uploads`
- `sessions`
- `arquivos`
- `generated`

## Onde normalmente eu mexia quando precisava dar manutenção

### Se o problema era cobrança

- `cobrancas_app`
- `bling`
- `locacao`
- `shared`
- `storage/cobrancas`
- `crontab`

### Se o problema era token/API Bling

- `bling_v3`
- `bling_v3_serv`
- logs `new_token.log`

### Se o problema era WhatsApp

- `api/whatsapp`
- `w-api`
- `botconversa`
- `api/index.php`

### Se o problema era faturamento

- `faturamento`
- IMAP
- `wkhtmltopdf`

### Se o problema era impressão

- `Lexmark_solution`
- `impressoras`

## Pontos de atenção

Esses são os principais riscos ou dívidas técnicas que eu deixo mapeados:

- existem várias credenciais embutidas em arquivos PHP e Python
- vários sistemas dependem de JSON local em vez de banco
- há integrações baseadas em regex e scraping de HTML, então qualquer mudança externa pode quebrar
- os tokens do Bling são ponto central de dependência
- parte do ambiente é legado e parte já foi migrada, então convivem duas abordagens
- nem tudo está encapsulado em serviço `systemd`; algumas coisas ainda dependem de cron ou execução direta

## Recomendações para quem assumir

Se eu fosse continuar a evolução desse ambiente, eu priorizaria:

- mover credenciais para `.env` ou secret manager
- centralizar logs
- documentar payloads reais de webhook
- reduzir dependência de JSON local
- consolidar os fluxos de WhatsApp, porque hoje existem várias frentes paralelas
- manter a aplicação nova de cobranças como padrão e ir aposentando o legado aos poucos

## Arquivo final

Se alguém precisar entender o ambiente rapidamente, eu começaria por estes arquivos:

- `/var/www/html/DOCUMENTACAO_SISTEMAS.md`
- `/var/www/html/cobrancas_app/README.md`
- `/var/www/html/cobrancas_app/config.py`
- `/var/www/html/shared/cobrancas_python_bridge.php`
- `/var/www/html/api/whatsapp/index.php`
- `/var/www/html/Lexmark_solution/api.php`
- `/var/www/html/faturamento/enviar.php`
- `/var/www/html/api/BancoBrasil/index.php`