GeraPop — CODEBA

Gerador de POP (Procedimento Operacional Padrão) com formulário guiado e exportação .docx/.pdf — backend FastAPI + frontend React (TypeScript/Vite).

Produção: gerapop.vercel.app · Piloto com persistência: preferir make run ou Docker (ver docs/piloto.md).

Pré-requisitos

• Python 3.11 (recomendado — Python 3.12 no WSL pode falhar com ctypes)
• uv ou Make
• Node.js 20+ e npm (para o frontend)

Início rápido

make install-dev
cd frontend && npm install
make run

• Frontend: http://localhost:5173
• API: http://localhost:8000 (docs em /docs)

Nota (rede corporativa): se registry.npmjs.org estiver bloqueado, use npm install --registry https://registry.yarnpkg.com.

Alternativa via Docker

make docker-run

Comandos

Comando	Descrição
make install	Cria .venv e instala dependências
make install-dev	Instala dependências + pytest e ruff
make run-backend	Sobe a API FastAPI (http://localhost:8000)
make run-frontend	Sobe o frontend React (http://localhost:5173)
make run	Sobe backend + frontend em paralelo
make test	Roda testes automatizados (pytest)
make lint	Verifica estilo e imports (ruff + eslint)
make format	Formata o código (ruff)
make docker-run	Sobe via Docker Compose

Testes E2E (Playwright)

Testes de ponta a ponta no frontend/e2e/ cobrem dashboard, formulário → geração → download .docx/.pdf, validação, código duplicado, biblioteca (editar/backup; exclusão desabilitada no MVP), anexar externo → editar e tema claro/escuro.

cd frontend
npm install --registry https://registry.yarnpkg.com   # se o npmjs estiver bloqueado
npx playwright install chromium                        # (o Channel Chrome do sistema também funciona)
npm run test:e2e          # headless (sobe backend 8000 + frontend 5173 automaticamente)
npm run test:e2e:headed   # com navegador visível

Usos do config: usa o Chrome instalado via channel: 'chrome' (sem Chromium baixado), backend com data dir isolado em .e2e-data/ (gitignored) e fullyParallel: false + workers: 1 para sequência determinística.

Estrutura

backend/                       # API FastAPI
├── main.py                    # App + CORS + /api/health
├── schemas.py                 # Modelos Pydantic
├── dependencies.py            # Conversões PopData ↔ schema
└── routers/                   # pops, generate, drafts, backup
frontend/                      # React 19 + TypeScript + Vite
├── src/
│   ├── pages/                 # HomePage, FormPage, PreviewPage
│   ├── components/            # Layout, Dashboard, Form, History, ui
│   ├── hooks/                 # useTheme, usePopForm, useDraft
│   ├── api/client.ts          # Fetch wrappers tipados
│   ├── types/pop.ts           # Interfaces TS (PopData)
│   └── styles/                # Design system CODEBA (light/dark)
gerapop/                       # Lógica de domínio
├── models.py                  # Domínio e validação (matriz fluxo, responsáveis, seções 7/8/9)
├── codigo.py                  # Unicidade de código + rótulo histórico (puro)
├── fluxo.py                   # Leitura do fluxo SEV (puro)
├── storage.py                 # Histórico em disco (pop.json + pop.docx)
├── backup.py                  # CLI de backup (python -m gerapop.backup)
└── services/
    ├── documento.py           # Modelo neutro de blocos (docx/pdf) + título para header
    ├── docx/                  # Geração do .docx (header página 2+, rodapé cópia não controlada)
    └── pdf/                   # Geração do .pdf (Calibri, _NumberedCanvas, página X de Y)
scripts/
└── seed_pops.py               # Alimenta data/pops/ com o padrão CODEBA (idempotente)
obsoleto/
├── gerapop-streamlit/         # UI Streamlit antiga (arquivada)
└── tests-streamlit/           # Testes E2E AppTest (arquivados)
fluxo-sev/                     # Diagrama interativo do fluxo SEV
tests/                         # pytest (78 testes)

Biblioteca de POPs (padrão CODEBA)

Fonte da verdade dos binários: pasta POP - Procedimento Operacional Padrão/ (versionada no git).

Ao listar/abrir POPs, o backend sincroniza esses arquivos para data/pops/ (histórico local, gitignored). Na Vercel, a semente rica vem de gerapop/official_snapshot.json (filesystem efêmero em /tmp).

Abrir na biblioteca abre o preview com visualização embutida do PDF (PDF.js na página) — não força download. Download de .docx/.pdf fica no menu ⋯.

.venv/bin/python scripts/seed_pops.py
.venv/bin/python scripts/regen_library_docx.py   # só DOCX; preserva PDF oficial

Contém hoje: POP-COM-001, POP-OPE-001, POP-OPE-002, POP-OPE-003 (Pesagem).

Anexar externo (.docx / .pdf): o arquivo entra na biblioteca e o app abre o formulário para edição. No Abrir, o preview usa o mesmo visualizador embutido:

• anexou PDF → visualiza o PDF anexado;
• anexou só DOCX → o preview regenera um PDF a partir dos dados do formulário (pode ficar enxuto se o formulário ainda não foi preenchido).

O que a v1 faz

• UI React com identidade CODEBA (home com foto do Porto de Ilhéus, biblioteca como hub, formulário com barra sticky; tema claro/escuro também no mobile)
• Biblioteca oficial sincronizada; Abrir = PDF embutido; anexar externo editável
• Formulário com seções, rascunho persistente, unicidade de código
• Gera .docx e .pdf (Letter, tabelas alinhadas) + pop.json reutilizável
• Backup zip do histórico (data/)
• Deploy Vercel (/api/* via Mangum) — filesystem efêmero; piloto com dados: local/Docker

O que a v1 não faz (proposital)

• Multi-usuário / login
• Persistência durável na Vercel sem volume externo
• Exclusão de POPs (UI sem Excluir; DELETE /api/pops/{id} retorna 403 no MVP)

Sem Make

uv venv --python 3.11 .venv
uv pip install -r requirements.txt -r requirements-dev.txt
uv pip install -e .

# Backend
.venv/bin/python -m uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
# Frontend (outro terminal)
cd frontend && npm install && npm run dev

Documentação

• docs/plano.md — pipeline GeraPOP + Fluxo SEV
• docs/piloto.md — roteiro de validação com a equipe
• docs/deploy.md — opções de hospedagem
• guia-usuario.md — uso do formulário