pjecalc-agent-architect

Files (5)

• SKILL.md
• find_dead_code.py
• health_check.py
• pjecalc-agent-architect.skill
• split_webapp.py

SKILL.md (first lines)

# PJE-Calc Agent Architect

Skill de arquitetura e refatoração para o repositório `pjecalc-agente`. O objetivo é transformar
o agente atual — funcional mas fragmentado — em uma base de código limpa, testável e escalável.

## Contexto: por que esta skill existe

O pjecalc-agente cresceu organicamente enquanto resolvia problemas difíceis (GUI Java headless,
JSF dinâmico, extração NLP de sentenças). O resultado é um código que funciona em partes, mas
sofre de fragmentação arquitetural: três estratégias de automação concorrentes, código morto
acumulado, acoplamento forte entre orquestração e automação, e dificuldade de escalar.

Esta skill NÃO trata de como preencher o PJE-Calc (use `pjecalc-preenchimento`), nem de como
debugar o Tomcat (use `pjecalc-agent-debugger`), nem de como escrever seletores JSF (use
`playwright-jsf-automator`). Esta skill trata de **como o código do agente deve ser organizado**.

---

## Mapa do repositório atual

```
pjecalc-agente/
├── webapp.py                  (1199 linhas) — FastAPI: rotas, SSE, lógica de negócio
├── config.py                  (113 linhas)  — Configurações globais + auto-detecção CLOUD_MODE
├── database.py                (525 linhas)  — SQLAlchemy: Processo, Calculo, InteracaoHITL
├── main.py                    (?)           — CLI standalone (modo local)
├── iniciarPjeCalc.sh          (207 linhas)  — Startup: Xvfb + xdotool + Bootstrap/Lancador
├── docker-entrypoint.sh       (54 linhas)   — Container: PJE-Calc bg → uvicorn imediato
├── Dockerfile                 (124 linhas)  — Multi-stage: agent-builder + imagem final
├── modules/
│   ├── ingestion.py           (302 linhas)  — PDF/DOCX → texto (pdfplumber + OCR)
│   ├── extraction.py          (2022 linhas) — Texto → JSON via Claude/Gemini API
│   ├── classification.py      (497 linhas)  — Verbas → mapeamento PJE-Calc
│   ├── parametrizacao.py      (328 linhas)  — JSON → instruções módulo a módulo
│   ├── preview.py             (422 linhas)  — Prévia editável (web)
│   ├── playwright_pjecalc.py  (2605 linhas) — ⭐ Automação principal (Playwright + JSF)
│   ├── automation.py          (729 linhas)  — ⚠️ Automação legada (pyautogui/playwright dual)
│   ├── playwright_script_builder.py (891 linhas) — ⚠️ Gera script standalone para download
│   ├── pjc_generator.py       (1083 linhas) — Gerador nativo de .PJC (ZIP+XML)
│   ├── human_loop.py          (465 linhas)  — HITL: pausa para validação humana
│   ├── document_collector.py  (467 linhas)  — Coleta de documentos
│   └── export.py              (301 linhas)  — Exportação de resultados
├── extension/                 — ⚠️ Extensão Chrome (terceira via de automação)
├── templates/                 — Jinja2: previa.html, instrucoes.html, etc.
├── tests/                     — Testes (cobertura limitada)
├── pjecalc-dist/              — PJE-Calc Cidadão empacotado (91MB, sem JRE)
└── dialog-suppressor/         — Java Agent para silenciar JOptionPane
```

### Legenda de status
- ⭐ = código principal, manter e melhorar
- ⚠️ = código problemático, candidato a remoção ou consolidação

---

## Diagnóstico: os 5 problemas estruturais

### 1. Três estratégias de automação concorrentes

O repositório tem três implementações diferentes tentando fazer a mesma coisa — preencher o
PJE-Calc. Cada uma usa seletores diferentes, fluxos diferentes, e até caminhos de navegação
diferentes ("Novo" vs "Cálculo Externo"):

| Implementação | Arquivo | Navegação | Resiliência |
|---|---|---|---|
| Playwright SSE (principal) | `playwright_pjecalc.py` | "Novo" ✓ | Alta (AJAX monitor, retry, crash recovery) |
| Script standalone | `playwright_script_builder.py` | "Cálculo Externo" ✗ | Baixa (seletores fixos, pausas manuais) |
| Extensão Chrome | `extension/content.js` | "Cálculo Externo" ✗ | Baixa (eventos DOM manuais) |

Além disso, `automation.py` é uma abstração legada que tenta unificar pyautogui e playwright,
mas na prática não é usada pelo fluxo principal.

**Ação**: Consolidar tudo em `playwright_pjecalc.py`. Remover `automation.py`,
`playwright_script_builder.py` e `extension/`. Se o usuário precisa de um script local,
gerar a partir do mesmo código-fonte, não de um builder separado.

### 2. webapp.py monolítico (1199 linhas)

O `webapp.py` concentra:
- Rotas HTTP (API + páginas)
- Lógica de processamento (background tasks)
- SSE streaming da automação
- Logging em buffer in-memory
- Gerenciamento de sessões em processamento

**Ação**: Extrair em módulos:
```
webapp.py          → Apenas definição de rotas e middleware
routes/
├── pages.py       → Rotas de páginas HTML (GET)
├── api.py         → API REST (POST/PATCH/DELETE)
├── diagnostics.py → Endpoints de diagnóstico (/api/logs/*, /api/ps, etc.)
└── sse.py         → Server-Sent Events para automação
services/
├── processing.py  → Background tasks (extração + classificação)
└── automation.py  → Orquestração da automação Playwright
```

### 3. Acoplamento Flask ↔ Tomcat no mesmo container

O container Docker empacota tudo junto: Python Agent (FastAPI), PJE-Calc (Tomcat Java), Xvfb,
Playwright Chromium. Isso cria problemas:

- Impossível escalar extração NLP independentemente da automação
- O Tomcat demora 2-5 minutos para subir, bloqueando qualquer automação
- Falha no Tomcat = falha de todo o serviço
- Imagem Docker pesada (~2GB) com Java + Python + Chromium + Xvfb

**Ação (curto prazo)**: Manter o monólito, mas desacoplar internamente. O webapp deve
funcionar 100% sem o Tomcat (extração, prévia, edição). A automação é uma feature
opcional que só roda se Tomcat estiver disponível.

**Ação (médio prazo)**: Separar em dois serviços:
```
┌─────────────────────────┐     ┌──────────────────────────┐
│ Serviço de Orquestração │     │ Worker de Automação      │
│ (Flask + LLM + Prévia)  │────▶│ (Playwright + PJE-Calc)  │
│ Leve, escala horizontal │     │ Pesado, pool fixo        │
│ Sem Java, sem Xvfb      │     │ Java + Xvfb + Chromium   │

From bragabarreto/pjecalc-agente, MIT.

More from bragabarreto/pjecalc-agente