From 455498c07a3ce17797a653ae22f81c2eb0d989bf Mon Sep 17 00:00:00 2001 From: Francisco Solla Date: Mon, 14 Sep 2026 14:39:58 -0300 Subject: [PATCH] =?UTF-8?q?docs(plan):=20C163=20=E2=80=94=20relat=C3=B3rio?= =?UTF-8?q?=20de=20cidade=20pr=C3=A9-viagem=20(Related=20#1007)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../relatorio-cidade-viagem-a4-draft.html | 469 ++++++++++++++++++ docs/plans/relatorio-cidade-viagem.md | 101 ++++ 2 files changed, 570 insertions(+) create mode 100644 docs/plans/relatorio-cidade-viagem-a4-draft.html create mode 100644 docs/plans/relatorio-cidade-viagem.md diff --git a/docs/plans/relatorio-cidade-viagem-a4-draft.html b/docs/plans/relatorio-cidade-viagem-a4-draft.html new file mode 100644 index 00000000..fcd7ab92 --- /dev/null +++ b/docs/plans/relatorio-cidade-viagem-a4-draft.html @@ -0,0 +1,469 @@ + + + + + + + Rascunho A4 — Relatório de cidade pré-viagem + + +
+

+ Rascunho A4 — Relatório de cidade pré-viagem +

+

+ Persona/job: candidato e CG/assessor chamam um agente + skill com a cidade e recebem um PDF + A4 datado — página 1 = resumo de uma olhada; páginas 2+ = aprofundamento — cruzando base + Teqo com pesquisa web datada. Cenas estáticas, sem interação, valores genéricos. +

+

+ Cinza = estrutura · acento = decisão/guarda + (anunciar × não anunciar, lacuna explícita) · páginas em A4 (794×1123 px). +

+ +
+ + + +
+

+ Cena 1 · PDF página 1 — resumo de uma olhada +

+
+
+
+

+ Relatório de cidade — pré-viagem +

+

Município Exemplo

+

+ Território de Identidade Exemplo · prioridade alta · classe de exemplo (A/B/C) · + nível de envolvimento N2 +

+
+
+

Gerado em 14/09/2026

+

snapshot do momento

+

pág. 1/4

+
+
+ +
+ +
+

+ Conta eleitoral 2022 +

+

+ 0.000 votos +

+
+
+
% do próprio voto
+
0,0%
+
+
+
+
+
+
Rank no estado
+
00º / 435
+
+
+
Meta 2026 (faixa)
+
0.000
+
+
+
Cobertura de pledges
+
0%
+
+
+
+
+
+

+ Fonte: base Teqo — TSE 2022 (leitura relativa ao próprio voto; sem % estadual + absoluto). +

+
+ + +
+

+ Quem é quem +

+
    +
  • + Prefeito(a) + Nome do prefeito · Partido X +
    • +
  • + Vice + Nome do vice · Partido Y +
    • +
  • + Federação / relação + Federação de exemplo · relação a confirmar +
    • +
  • + Lideranças + 12 na base · 3 sem responsável +
    • +
  • + Dobradinhas + Nome 1, Nome 2, Nome 3 +
    • +
+
+ + vereador/dobrada ainda sem leitura (lacuna) +
+

+ Fonte: base Teqo (lideranças) + web datada 12/09/2026 (prefeito/vice/dobradas — + URL por item). +

+
+
+ + +
+

+ O que Solla entregou +

+
+
+

Emendas aportadas

+

R$ 0,0 mi

+

+ Fonte oficial 14/09/2026 (fase por item: empenhada/paga); notas da base quando + houver. Empenho ≠ pagamento. +

+
+
+

Falas no acervo

+

0 trechos

+

+ Busca por município no acervo (C153/C155): 0 resultados. +

+
+
+

Notícias (≤90 dias)

+

0 matérias

+

+ Web 14/09/2026 · imprensa local sem matéria no período. +

+
+
+
+ + +
+
+

+ O que anunciar agora +

+
    +
  • Pauta/entrega com fonte e data — a fonte vai ao lado da frase.
    • +
  • Agradecimento a liderança/prefeito com papel confirmado.
    • +
  • Compromisso novo com escopo que a campanha consegue cumprir.
    • +
+
+
+

+ O que NÃO anunciar +

+
    +
  • — Empenho tratado como pagamento (defeso/ano eleitoral).
    • +
  • — Nada sem fonte ("sem fonte, não publica").
    • +
  • — Dado staff-only (estimativa, nível N0–N4) fora da coordenação.
    • +
  • — Contato pessoal de liderança além do necessário (PII mínima).
    • +
+
+
+ + +
+

+ Riscos — oposição/disputa local +

+
+
+

Oposição local

+

+

Sem leitura suficiente — lacuna

+
+
+

Disputa local

+

+

Conferir com o CG antes da agenda

+
+
+

Rede

+

+

3 lideranças sem responsável

+
+
+
+ +
+ Fontes: base Teqo (leitura 14/09/2026) · pesquisa web e fonte oficial (data + URL em cada item) · + documento datado, completo para o candidato. +
+
+
+ + + + +
+

+ Cena 2 · PDF páginas 2+ — aprofundamento (índice + 2 seções) +

+
+
+
+

+ Relatório de cidade — aprofundamento +

+

Município Exemplo

+
+
+

Gerado em 14/09/2026

+

pág. 2/4

+
+
+ +
+

Índice

+
    +
  1. 1. Conta eleitoral completa 2014/2018/2022
    2. +
  2. 2. Rede e lideranças (responsável e frescor)
    3. +
  3. 3. Conjuntura (tendência, forças, riscos, dobradinhas)
    4. +
  4. 4. Sinais recentes
    5. +
  5. 5. Demandas e visitas
    6. +
  6. 6. Demografia
    7. +
  7. 7. Acervo de falas (data e link)
    8. +
  8. 8. Notícias internas e imprensa local
    9. +
  9. 9. Panorama regional (Território de Identidade)
    10. +
  10. 10. Fontes e limites
    11. +
+
+ +
+

1. Conta eleitoral completa

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AnoVotos% do próprio votoRankVálidos do cargo
20140.0000,0%00º0.000
20180.0000,0%00º0.000
20220.0000,0%00º0.000
+

+ Fonte: base Teqo — artefato TSE 2014/2018/2022. Leitura relativa; sem % estadual + absoluto. +

+
+ +
+

2. Rede e lideranças

+
    +
  • + Liderança 1 — organização de exemplo + responsável: Assessor Exemplo · atualizada há 2 semanas +
    • +
  • + Liderança 2 — organização de exemplo + responsável: — · atualizada há 6 semanas +
    • +
  • + Liderança 3 — sem dados suficientes + lacuna: pledge não declarado · ver "fontes e limites" +
    • +
+

+ Fonte: base Teqo (pledges, frescor). Nomes omitidos no rascunho; no PDF, só o + necessário (PII mínima). +

+
+ +
+ Seções 3–10 seguem na mesma página/continuação · fontes item a item. +
+
+
+ + + + +
+

+ Cena 3 · PDF — dado ausente vira lacuna explícita +

+
+
+
+

+ Relatório de cidade — aprofundamento +

+

Município Exemplo

+
+
+

Gerado em 14/09/2026

+

pág. 4/4

+
+
+ +
+

8. Notícias internas e imprensa local

+
+

+ Não encontrado na base nem na pesquisa. +

+

+ Buscas web em 14/09/2026: "Município Exemplo" + prefeito, obras, saúde — nenhuma + matéria com data ≤90 dias. Nenhum post interno relacionado ao município. +

+

+ Lacuna explícita — não preencher por inferência. +

+
+
+ +
+

Emendas aportadas

+
+

+ Campo "Emendas aportadas" (staff) sem registro para o município. +

+

+ Fontes oficiais consultadas em 14/09/2026 (Portal da Transparência, Câmara): + nenhum resultado associado com segurança. +

+

+ Sem fonte, não publica — e nada de anunciar empenho como pagamento. +

+
+
+ +
+

10. Fontes e limites

+
    +
  • Base Teqo: leitura read-only em 14/09/2026 — o PDF é datado e o dado envelhece.
    • +
  • Web: cada item carrega data + URL; o que não veio com fonte virou lacuna.
    • +
  • Limite: não existe voto por bairro/seção — o relatório não inventa granularidade.
    • +
  • Efeito eleitoral de emenda é condicional ao crédito local — o PDF não promete voto.
    • +
+
+ +
+ Exemplo de seção vazia: a ausência é resultado, não falha de layout. +
+
+
+ + + + +
+

+ Cena 4 · leitura de bolso (390px) — o mesmo resumo, uma coluna +

+
+
+

+ Relatório de cidade +

+

Município Exemplo

+

Gerado em 14/09/2026

+
+ +
+

+ Conta eleitoral 2022 +

+

0.000 votos · 0,0% do próprio voto

+
+
+
+

rank 00º/435 · meta 0.000 · cobertura 0%

+
+ +
+

+ Quem é quem +

+

Prefeito: Nome do prefeito (Partido X) — relação a confirmar.

+

12 lideranças na base · 3 sem responsável.

+
+ +
+

+ O que Solla entregou +

+

Emendas: R$ 0,0 mi (sem fonte oficial). Falas: 0 trechos.

+

Notícias: 0 matérias na janela ≤90 dias.

+
+ +
+

+ Anunciar +

+

Só o que tem fonte e escopo cumprível na cidade.

+
+ +
+

+ Não anunciar +

+

Empenho como pagamento · dado staff-only · PII além do necessário.

+
+ +
+

+ Riscos +

+

Oposição: sem leitura · Disputa local: conferir com o CG.

+
+ +

+ Fontes: base Teqo (leitura 14/09/2026) · web datada com URL. +

+
+
+
+
+ + diff --git a/docs/plans/relatorio-cidade-viagem.md b/docs/plans/relatorio-cidade-viagem.md new file mode 100644 index 00000000..febd9c2d --- /dev/null +++ b/docs/plans/relatorio-cidade-viagem.md @@ -0,0 +1,101 @@ +# 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).