# CLAUDE.md — mapa de integração do projeto

Leia antes de editar: as três partes (JS, PHP, Python) conversam por
contratos que não aparecem no código de uma parte só. Mudou um lado,
confira o outro.

## Pontos de integração

| De | Para | Como | Contrato |
|---|---|---|---|
| Frontend | API PHP | `fetch` em `/api/...` (`frontend/js/api.js`) | JSON; cookie de sessão + header `X-CSRF-Token` em POST/PUT/DELETE. Dinheiro chega em **reais** (`valor`, calculado de `valor_centavos`) e vai em reais (texto "1.234,56" ou "1234.56") |
| Produção (servidor web) | API PHP | `frontend/api.php` faz `require` de `php-api/public/index.php` | A ponte PRECISA ficar dentro de `frontend/` (pasta pública) |
| API PHP | Worker Python | **fila**: `Worker::run/background` grava em `pedidos_worker (comando, args JSON)`; `servico.py` executa `worker.py <comando> <args>` SEM shell | Comando precisa estar em `PERMITIDOS` dos DOIS lados (`php-api/src/Worker.php` e `python-worker/servico.py`); resposta = ÚLTIMA linha do stdout, JSON `{"ok": bool, ...}`; `Worker::run` acompanha por uma conexão PDO SEPARADA (`Database::nova()`) — leitura aberta na conexão principal prende a "foto" do WAL |
| systemd | Worker | `organizador-worker.service` → `worker.py servico` (usuário `organizador`, `TZ=America/Sao_Paulo`) | Agenda dentro do serviço (`servico.verificar_agenda`, chaves `agenda_*` em `configuracoes`); heartbeat `worker_vivo_em` a cada 5 s (`Worker::vivo()` exige < 30 s) |
| Cron | Worker | `/etc/cron.d/organizador`: `flock -n ... worker.py vigiar` a cada 10 min | Só alerta se o serviço parar |
| PHP + Python | Banco | Mesmo `database/app.db` (SQLite WAL, busy_timeout 30 s) | Schema único em `database/schema.sql` (idempotente) + `migracoes.json` (`PRAGMA user_version`); dinheiro SEMPRE `*_centavos INTEGER` |
| PHP → Python | Senhas de e-mail | `Crypto::encrypt` (só chave PÚBLICA) → `cripto.decifrar` (chave privada, 600, só `organizador`) | `"v2:" + base64(len2 + RSA-OAEP-SHA1(chave AES) + nonce12 + cifrado + tag16)`; `"v1:"` legado (APP_SECRET) só leitura |
| PHP | Segredo do 2FA | `Crypto::cifrarLocal/decifrarLocal` | `"p1:"` AES-256-GCM com `PHP_SEGREDO` (app.env) |
| PHP + Python | Configuração | `config/app.env` (PHP e worker; nada secreto), `config/worker.env` (só worker: tokens, `BACKUP_SENHA`, `CHAVE_PRIVADA`) e tabela `configuracoes` (tela) | O PHP não lê worker.env: sabe o que está configurado por `configuracoes.worker_diagnostico` (gravado pelo serviço) |
| Worker | Drive do contador | `rclone copy --immutable storage/documentos/notas-fiscais <remoto>` | Nunca `sync` |
| Worker | Backup | `backup.py`: snapshot SQLite + documentos + config → tar.gz → AES-256-GCM em blocos (scrypt de `BACKUP_SENHA`) → `storage/backups/*.bkp` → `rclone copy --immutable` | Formato `ORGBKP1\n + sal16 + custo1 + [len4 + nonce12 + cifrado]`; AAD = índice + flag de último bloco |
| PHP + Python | Regras de captura | `RegrasController::bate()` e `regras.py::bate()` | As duas comparações precisam ser idênticas; descartar vence capturar |
| PHP | Revisão | `Arquivos::sairDaRevisao()` move `documentos/revisao/...` → `documentos/...` | O worker grava pendentes em `documentos/revisao/` |
| Worker → PHP | Fornecedores | `documentos.dados_fornecedor` → `fornecedores.sincronizar()` | Campo editado na tela vira `"manual"` em `origens`; o worker nunca mais muda. Categoria/centro do fornecedor são herdados pelo documento |
| Worker | PIX do boleto | `extrator.analisar_pdf` → `pix.do_pdf` (copia e cola do texto + QR via `zbarimg`, CRC16 conferido) → `documentos.pix` (JSON) | Usado pela fraude (sinal 7) e mostrado na tela |
| Worker | Boleto falso | `coletor` → `fraude.analisar(con, id, alertar=True)` | `documentos.suspeito/motivos_suspeita`; resolver = `suspeita_resolvida_por` (PHP `resolverSuspeita`). Suspeito: conciliação não baixa, PHP não deixa marcar pago, não conta como "chegou" na recorrente |
| PHP + Worker | Lançamento manual | `DocumentosController::lancar` (origem `manual`, `aprovacao='aguardando'`) → `aprovarPagamento` por OUTRO usuário | Notificador e conciliação só usam `aprovacao='aprovado'` |
| Worker | Recorrentes | `recorrentes.processar(con)` (antes dos avisos, em `notificar`) | Uma linha por mês em `recorrentes_ocorrencias`; `nao_chegou` avisa 1 vez; `manual` gera documento origem `recorrente` |
| Worker | Nota PJ | `extrator.retencoes_nfse` → `documentos.retencoes`; `validacao.validar` → `documentos.validacao` | Compara com `fornecedores.contrato_valor_centavos` / `retencoes_esperadas` (JSON de %) |
| Worker + PHP | Conta que pagou | `documentos.pago_conta_id` → `contas_bancarias` → `empresas`: conciliação grava a conta do OFX; baixa manual recebe `pago_conta_id` no PUT | Contas cadastradas à mão casam com o OFX por banco+conta normalizados (`conciliador._achar_conta`) |
| Worker | Histórico da caixa | `coletor.varrer_historico` (estado em `contas_email.historico_*`: pendente → em_andamento → concluido / desligado) depois do fluxo normal, com tempo `historico_minutos` | `SEARCH UID cursor+1:* BEFORE historico_antes`; ctx `historico=True` = sem aviso; arquivo com mtime = data do e-mail (contabilidade usa `--max-age 120d` salvo `contabilidade_enviar_historico=1`). PHP `POST /api/contas/{id}/historico` só muda o estado |
| PHP + Worker | Rastreador | `RastreadorController` calcula a situação (SQL, nada gravado) a partir de `status`, `transacao_id`, `pago_origem`, `pago_conta_id` e `importacoes_ofx.periodo_*` | `pago_origem` = extrato \| comprovante \| manual (PHP grava `manual`; worker troca, nunca rebaixa extrato). `pago_por_documento/nome` = pagador lido do comprovante (`extrator.pagador_do_comprovante`) |
| PHP + Worker | OFX sem titular / .zip / pasta | `ConciliacaoController::importar` (`empresa_id` opcional, `.zip`) → `conciliador.importar(caminho, None)`; `importar_pasta()` para `storage/ofx/entrada` | Conta casada por banco+conta normalizados em TODOS os titulares; conta desconhecida volta em `contas_desconhecidas` e não é importada. Titular PF = `empresas.tipo='pf'` com CPF (11 dígitos) na coluna `cnpj` |
| Worker + PHP | Duplicidades | `duplicidade.verificar(con)` no fim de `conciliador.conciliar`, em `cmd_coletar` (sem conciliação) e `cmd_notificar`; comando `duplicidades` | Tabela `duplicidades` (chave única por par; status aberta \| resolvida \| nao_e_duplicidade \| sumiu; `docs_busca` ",id,id,"). Só avisa (`enviar_alerta(sempre=True)`, `avisar_duplicidades`), nunca altera boleto/extrato. 2º comprovante: `coletor._segundo_pagamento` → documento `comprovante` status `duplicado` + `duplicata_de`. PHP `DuplicidadesController` (financeiro) |
| Worker + PHP | Nota do boleto | `notas_busca.verificar(con)` (comando `buscar-notas`, agenda de hora em hora): `comprovantes.vincular_nota` (mesmo e-mail, duplicata `documentos.duplicatas` venc+valor, emitente+valor) → `sefaz.sincronizar` (NFeDistribuicaoDFe por NSU, estado `empresas.dfe_*`, 656/sem novidade = espera 1 h) → resumo compatível → `sefaz.manifestar_ciencia` (evento 210210 assinado RSA-SHA1, só notas que batem com boleto, máx. 15/rodada) → `baixar_por_chave`; `nfse_nacional.sincronizar` (ADN `GET /contribuintes/DFe/{NSU}?cnpjConsulta=&lote=true`, só tomador). Certificado A1 em `config/certificados/<doc>.pfx` + `CERT_SENHA_<doc>` (worker.env; PHP nunca lê; `certificado.situacao()` vai no `worker_diagnostico`) | `documentos.nota_situacao` = NULL \| buscando \| encontrada \| nao_encontrada \| sem_nfe \| nota_cancelada; decisão manual (`nota_decidida_por`, PHP `POST /documentos/{id}/nota`) não é desfeita; `dfe_documentos` guarda resumos/completas; DANFE por `danfe.py` → `gerar_danfe.py` (processo isolado) em `arquivo_extra` ('' = falhou, não tenta de novo); `fornecedores.emite_nota` = 'nao' → sem_nfe automático |
| Worker | Alertas | `notificador.enviar_alerta` = WhatsApp **e** e-mail (SMTP, senha `smtp_senha_cifrada` v2), independentes; `tudo-ok` diário | Um canal fora não impede o outro |
| Worker | WhatsApp | `notificador.PROVEDORES`; `enviar_alerta(texto, sempre=False)` para alertas operacionais | `notificacoes (documento_id, tipo_aviso)` UNIQUE evita repetição; CallMeBot não recebe linha digitável no modo "auto" |

## Regras que não podem quebrar

- **Toda mudança pedida pelo usuário atualiza a documentação**: README.md, este CLAUDE.md e o Claude Doc do sistema (https://claude.ai/artifact/JMgqGozNffATRMSwcGnmWF — etapas, testes e o que mudou). Mudança sem doc atualizado não está pronta.
- Toda rota, exceto `POST /api/auth/login` e `POST /api/auth/2fa`, passa por `Auth::requireLogin()`, `requireCsrf()` (POST/PUT/DELETE) e `Auth::exigir(papelMinimo)` em `Router::dispatch`. Rota nova = papel novo em `papelMinimo()`.
- 2FA obrigatório para financeiro/admin (`Auth::exige2faPara`); só `EXIGIR_2FA_FINANCEIRO=0` no app.env desliga (ambiente de teste). Aprovação própria só com `permitir_aprovacao_propria=1`.
- Documento fiscal (nota aprovada, boleto pago, enviado ao contador) não é excluído antes de 5 anos (`DocumentosController::excluir`); `manutencao.py` nunca toca em `documentos`.
- Excel: texto que começa com = + - @ sai com `quotePrefix` (`Xlsx.php`).
- Papéis: leitura < operador < financeiro < admin. Marcar pago/aprovar/conciliar/resolver suspeita = financeiro; usuários/config/contas de e-mail/backup = admin.
- Ações sensíveis chamam `Auditoria::registrar()` (nunca com senha, token ou linha digitável).
- Todo texto vindo da API entra no HTML via `escapeHtml()`.
- Arquivo do banco só é servido via `Arquivos::absoluto()` e SEMPRE como download (`Content-Disposition: attachment` + `nosniff`).
- XML de anexo: `defusedxml` (fallback recusa DOCTYPE/ENTITY). PDF: lido em processo separado (`ler_pdf.py`, 512 MB / 30 s). ZIP: leitura em blocos com limite, nomes com `..`/absolutos recusados.
- IMAP sempre só leitura (`select(readonly=True)` + `BODY.PEEK[]`).
- Datas/horas: nunca `datetime('now','localtime')` no SQL do código — passe `agora_txt()` (Python) / `date('Y-m-d H:i:s')` (PHP), ambos no fuso `APP_TIMEZONE`.
- Scripts do servidor (`preparar-servidor.sh`, `atualizar.sh`) rodam como root e trocam de usuário com `runuser -u organizador --` (Debian mínimo não tem `sudo`); a versão do PHP é a da distribuição (detectada; `PHP_VERSAO` força). Alvo: Debian 13/12 e Ubuntu 24.04. `instalar-tudo.sh` (servidor novo) = HD de dados em `/var/www` (sfdisk, sem parted; só formata disco vazio com "SIM") + unzip em `/var/www/organizador` + `preparar-servidor.sh`; recusa se `database/app.db` já existe. Passo a passo com prints: https://claude.ai/artifact/PAu1uSAxTKiaeVfMXCuRF2
- `deploy.sh` não envia nem apaga `database/`, `storage/`, `config/app.env`, `config/worker.env`, `config/*.pem`, `config/certificados/` (certificados A1: pasta 700, arquivos 600, só o worker).
- Documento com `revisao != 'aprovado'` não gera aviso, não entra na conciliação e não vai para o drive.
- Conciliação: um débito ↔ um boleto; auto só com 70+ pontos, 15 de folga e boleto não suspeito.

## Testes

```bash
python3 -m unittest discover -s python-worker/tests -v   # worker (sem rede): 60 testes
./scripts/dev-up.sh && ./scripts/smoke-test.sh            # API ponta a ponta (sobe também o serviço do worker): 160 checagens
```
