# Relatório de cidade pré-viagem (agente + skill → PDF A4) Status: rascunho Atualizado em: 2026-09-14 Issue: #1007 Priority: P1 Impeccable: B — superfície nova (documento A4), sem tela de app Rascunho UI: docs/plans/relatorio-cidade-viagem-a4-draft.html Appetite: ~2–3 dias eng; um outcome verificável — chamar com uma cidade e sair o PDF Responsável: — ## Intenção A eleição é em ~3 semanas e o candidato viaja quase todos os dias. Ao chegar numa cidade, ele precisa saber sem garimpo: quem manda ali (prefeito aliado ou oposição? de que federação?), quem são as lideranças, o que o mandato já entregou (emendas, falas no acervo, menções na imprensa), o que está quente na região e — decisivo em ano eleitoral — o que pode e o que não pode ser anunciado. O pedido é explícito desde a sessão de campo de 2026-07-23 (O6; caso Nazaré das Farinhas). O E16 entregou a tela/print interno; falta o **documento de viagem**: um PDF por cidade, gerado sob demanda por um **agente + skill**, cruzando a base interna do Teqo (lida direto da produção) com pesquisa web e **fontes oficiais datadas e com fonte**. ## Persona e fluxo - **Persona / contexto:** o **candidato** (Almerindo Vasconcelos) no deslocamento/véspera da visita — lê no celular, uma passada de olho; e o **CG/assessor** (Nivaldo Cerqueira) que prepara a agenda e confere as fontes. - **Job principal:** chegar na cidade sabendo "quem é quem, o que entreguei, o que está quente, o que posso/não posso anunciar" — sem depender de memória, WhatsApp ou garimpo manual. - **Fluxo desejado:** pede o relatório com o nome da cidade → o agente exporta a base, pesquisa a web com data/URL e gera o PDF → o candidato lê o resumo de 1 página antes de desembarcar, decide o tom do palanque e o que acionar; o aprofundamento fica com o assessor. - **Anti-goals de produto:** virar relatório de 40 páginas; inventar dado sem fonte; virar segundo cadastro/fonte de verdade; tentar cobrir toda a internet; prometer anúncio que o defeso não permite. ### Esboço de fluxo (B/C/D) ```text [pede: "relatório de Teixeira de Freitas"] → [export read-only da base + pesquisa web datada] → [template A4] → [PDF datado: página 1 = resumo; 2+ = aprofundamento] → [candidato lê no deslocamento e decide tom/anúncio] → [assessor usa o aprofundamento na agenda] ``` ### Rascunho UI (B/C/D) - Rascunho UI (gate): `docs/plans/relatorio-cidade-viagem-a4-draft.html` (página 1, início do aprofundamento, lacuna explícita e leitura de bolso ~390px) ## Objetivo e aceite - Chamar o agente/skill com um município e sair um **PDF A4 datado** (+ companion `.md` com números e proveniência) com **resumo de 1 página** + seções de aprofundamento, lendo a **base de produção diretamente (read-only)** no estado atual do dado (**snapshot do momento**). - A página 1 responde sozinha o job: conta eleitoral 2022, quem é quem, o que foi entregue, o que anunciar × o que NÃO anunciar, riscos. - Toda afirmação não trivial tem **fonte visível** (base Teqo com data de leitura; web/fonte oficial com data + URL); o que não foi encontrado aparece como **lacuna explícita** — nunca preenchido por inferência. - Guardrails de produto: "sem fonte, não publica"; não anunciar empenho como pagamento (defeso/ano eleitoral); sem despejo de PII desnecessária (contatos completos não entram); PDF datado e **completo para o candidato** (estimativas e nível N0–N4 incluídos, sem marca de restrição). ## Dados (intenção) - **Vou apresentar dados?** Sim, superfície neste item — o PDF é documento de dados. - **Decisões desbloqueadas:** - Candidato: o que falar/evitar no palanque e o que é seguro anunciar na cidade. - CG/assessor: se aciona/agradece prefeito e lideranças na agenda — e com que pedido. - Assessor: qual lacuna atacar primeiro (rede sem responsável, disputa local, cobertura de meta). - **Restrições de produto (forma adiada ao impl):** leitura **relativa** (% do próprio voto, LQ, rank — nunca % estadual absoluto); separar visualmente "base Teqo" de "pesquisa web/fonte oficial (com data + URL)"; lacuna explícita em vez de invenção; **conteúdo completo para o candidato** (estimativas e nível N0–N4 entram, sem marca de restrição); emendas lidas da fonte oficial **em tempo de geração, sem persistir na base**. ## Dados da decisão (literais) - **Estrutura do relatório (contrato de conteúdo).** - **Página 1 = "Resumo de uma olhada"**, blocos nesta ordem: (1) identificação/prioridade/classe; (2) conta eleitoral 2022 — votos, % do próprio voto, rank, meta/cobertura; (3) quem é quem — prefeito/vice/partido/federação/relação, principais lideranças, dobradinhas; (4) o que Solla entregou — emendas (`budgetNotes`) + falas + notícias; (5) o que anunciar × o que NÃO anunciar; (6) riscos — oposição/disputa local. - **Páginas 2+ = aprofundamento**, seções: conta eleitoral completa 2014/2018/2022; rede/lideranças com responsável e frescor; conjuntura (`politicalTrend`, forças/riscos, dobradinhas); sinais recentes (`municipalityUpdate`); demandas e visitas (`campaignDemand`/`activity`); demografia; acervo de falas (`Speech.mentionedMunicipalities`/`SpeechSegment`, com data e link); notícias internas e imprensa local; panorama regional da TI; **fontes e limites**. - **Checklist mínimo de pesquisa web** (cada item com data + URL): prefeito/vice (nome, partido, federação, situação, relação com o campo); vereadores/dobradas; disputa local; quem mais investe na praça (bancada/adversários); notícias da cidade/região (janela ≤90 dias); emendas (fontes oficiais quando possível); imprensa/rádio local. - **Guardrails literais:** "sem fonte, não publica"; nada de "anunciar empenho como pagamento" (defeso/ano eleitoral); PII desnecessária fora (contatos completos não entram); PDF datado e completo para o candidato. - **Fonte interna v1:** base E16 (TSE, pledges, lideranças, sinais, demografia) + `Speech.mentionedMunicipalities`/`SpeechSegment` + `municipality.budgetNotes` ("Emendas aportadas", notas manuais) — leitura **direta à produção, read-only**, sem criar/alterar nada na base. - **Emendas:** número/estado vêm da **fonte oficial em tempo de geração** (Câmara/Portal da Transparência — fonte exata verificada na implementação), com URL + data da consulta + fase (empenhada/paga); **sem collection, migration ou persistência** no app. - **Entrega:** PDF + companion `.md` (números e proveniência, revisável em diff) commitados em `docs/research/` — precedente C157. - **Precedente de render:** Chromium do Playwright `page.pdf` A4 (`printBackground`) — sem lib server-side (decisão de E16/C157). ## Direção no codebase (hipótese) - **Áreas prováveis:** script de leitura **direta da produção read-only** (transação `read_only`, opt-in explícito; receita do proxy socat `127.0.0.1:5433` do runbook — túnel/execução remota é decisão de implementação; **sem `db:pull`/snapshot**); skill + agente/command (`.agents/skills//SKILL.md`, `.opencode/agent/.md`); fetch da fonte oficial de emendas em runtime (sem persistência); template HTML do relatório; renderizador PDF reusando a mecânica do C157; saída `docs/research/relatorios-cidade/-.pdf` + `.md`. - **Precedente a olhar:** `scripts/build-solla-ceuci-salvador-report.mjs` (`page.pdf`), `src/utilities/municipality/municipalityDossierData.ts`, `src/utilities/ai/tools/` (queries por `mentionedMunicipalities`); runbook `docs/ops/teqo-1313-deploy.md` (acesso read-only à prod). - **Risco de acoplamento:** compor o E16, não duplicar; leitura read-only sem tocar guards locais (nunca apontar dev/test para a prod); nenhum schema/migration novo (emendas só em memória do relatório). ## Dependências - Nenhuma dura — E16 ✓, acervo de falas C153/C155 ✓, precedente de PDF C157/C161 ✓. - Suave: a **persistência** de emendas (G11 estrutural) segue fora; esta entrega lê a fonte oficial apenas em runtime. ## Fora de escopo - Persistir emendas na base (collection/migration — G11 estrutural); UI nova em `/campanha`; publicação no site; histórico comparativo entre relatórios; mapas/gráficos ricos por cidade (fatias futuras); fato por bairro/zona. ## Rabbit holes de produto - **Relatório de 40 páginas.** Se alguém "só completar": cada seção quer crescer. **Corte:** teto de itens por seção e página 1 fechada em 1 página. - **"IA inventa" sem fonte.** Se alguém "só completar": texto plausível sem lastro. **Corte:** "sem fonte, não publica" + separação base/web + lacuna explícita. - **Segundo cadastro/fonte de verdade.** Se alguém "só completar": base paralela para prefeito/vereador. **Corte:** compõe E16; emendas seguem G11 manual. - **Cobrir toda a internet.** Se alguém "só completar": research infinito e cara de dossiê de consultoria. **Corte:** checklist fixo, janela ≤90 dias, lacuna explícita. - **Prometer o que não saiu.** Se alguém "só completar": anúncio de empenho como entrega. **Corte:** bloco "anunciar × não anunciar" com defeso; empenho nunca tratado como pagamento. ## Questões em aberto (produto) - ~~**Acesso à base real?**~~ **Resolvida (2026-09-14):** leitura **direta à produção, read-only** (opção C) — sem snapshot/`db:pull`; mecânica de conexão (proxy/túnel/execução remota) é da implementação. **Rejeitadas:** export no homeserver e `db:pull` local. - ~~**Destino do PDF?**~~ **Resolvida (2026-09-14):** PDF + companion `.md` **commitados em `docs/research/`** (opção B), precedente C157. - ~~**Ferramenta de PDF?**~~ **Resolvida (2026-09-14):** Chromium do Playwright `page.pdf` (opção A); MCP/ferramenta externa e lib nova rejeitados. - ~~**Campos staff-only (estimativas/nível N0–N4) no PDF?**~~ **Resolvida (2026-09-14):** **incluir tudo, sem marca** (opção A) — o relatório é do candidato e ele vê/sabe de tudo. - ~~**Emendas estruturadas?**~~ **Resolvida (2026-09-14):** **fonte oficial em tempo de geração, sem persistir**; a estrutura persistida segue G11 (fora). - **Fonte oficial de emendas (Câmara × Portal da Transparência)?** **Recomendação:** verificar na implementação (skill `source-driven-development`); critério: valor por município/ano + fase + URL estável. _(assumido — validar na implementação)_ ## Referências - GitHub Issue #1007. - Rascunho UI (gate): `docs/plans/relatorio-cidade-viagem-a4-draft.html`. - `docs/CUSTOMER.md` (O6 — dossiê pré-agenda) e personas: `docs/research/persona-emendas-parlamentar.md`, `docs/research/persona-emendas-coordenador-campanha.md`, `docs/research/persona-cientista-politico-campanha-ba.md`. - Entrega vizinha: `docs/plans/dossie-municipio.md` (E16); precedente de PDF: `docs/plans/relatorio-sobreposicao-solla-ceuci-salvador{,-impl}.md` + `scripts/build-solla-ceuci-salvador-report.mjs`. - Fontes internas: `src/utilities/municipality/municipalityDossierData.ts`, `src/collections/Speech.ts`, `src/collections/Municipality.ts` (`budgetNotes`), `docs/plans/inteligencia-campanha.md` (G11).