teqo-backup/docs/plans/sollinha-tool-urls-navegacao-impl.md
Cursor Agent 5f97b6a21c
feat(ai): add buildCampaignLinks tool for Sollinha navigation (B162)
Introduce a closed-catalog URL builder that delegates to existing list/detail
href helpers, with role-based guards for leader lockdown and unrestricted-only
assessor routes. Register the tool in the AI chat and teach the system prompt
when to offer markdown links after resolving entity ids/slugs.

Closes #383
2026-08-06 00:22:11 +00:00

124 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Impl: B162 — Sollinha: tool de URLs para navegar a vistas de interesse
Status: em execução
Atualizado em: 2026-08-06
Issue: #383
Intenção: docs/plans/sollinha-tool-urls-navegacao.md
Appetite restante: ~0,5–1 dia (herdado)
## Leitura da intenção
- **Outcome:** A Sollinha monta paths `/campanha/…` canônicos (detalhe ou lista filtrada) e os oferece como links markdown clicáveis na resposta, para o staff abrir a vista certa em um clique — sem substituir a navegação do app nem inventar filtros inexistentes.
- **O que NÃO negociar:** catálogo fechado (sem path genérico); reuso dos builders de URL existentes; leader lockdown; ids/slugs já resolvidos (nunca chute); links relativos; sem auto-navegação; sem migration/Consent/collection; não inventar `?advisor=` em dobradinhas.
- **O que reavaliar:** A hipótese de “um arquivo em `tools/` + registro” permanece correta, mas a lógica de montagem deve viver num módulo **puro** (`campaignNavigationUrls.ts`) separado da factory `tool()`, para testes unitários sem mock de Payload e para não inflar o handler da tool.
## Abordagem recomendada
```mermaid
flowchart LR
subgraph model [Sollinha]
P[Pergunta do usuário]
D[Tools de dados]
L[buildCampaignLinks]
end
subgraph pure [campaignNavigationUrls.ts]
C[Catálogo + RBAC]
B[build*Href existentes]
end
P --> D
D -->|ids/slugs| L
L --> C
C --> B
B -->|path + label| P
```
**Opções consideradas:** A) módulo puro + tool fina | B) tool com paths hardcoded inline | C) estender `searchEntities` para devolver todos os hrefs
**Recomendação:** **A** — catálogo tipado + delegação aos `build*Href`/`campaignConceptHref` já canônicos; tool só valida input Zod, chama o módulo com `ctx.user.role`, devolve `{ links: [{ path, label }] }`.
**Rejeitadas:** **B** porque driftaria dos contratos B18+ e duplicaria query params; **C** porque não cobre listas filtradas, mistura busca com navegação e não centraliza RBAC de destino.
### Componentes / mudanças
- **`campaignNavigationUrls.ts`** (`src/utilities/ai/campaignNavigationUrls.ts`): núcleo puro. Tipos discriminados por `destination`, mapa de destinos → função builder, guardas de papel (`isStaffCampaignRole`, `isUnrestrictedCampaignRole`, `canAccessSupporterArea`), retorno `{ ok: { path, label } } | { error, alternatives? }`. Sem Payload, sem I/O.
- **`buildCampaignLinks.ts`** (`src/utilities/ai/tools/buildCampaignLinks.ts`): factory `buildCampaignLinks(ctx)` com Zod `discriminatedUnion('destination', …)` espelhando o catálogo v1; aceita `links: [...]` (batch até ~5) para cenários “ficha + lista filtrada”; `execute` chama o módulo puro.
- **`index.ts`**: registrar `buildCampaignLinks: buildCampaignLinks(ctx)`.
- **`systemPrompt.ts`**: seção “Navegação” — quando usar (híbrido C da intenção: proativo em entidade singular + sempre sob pedido explícito); fluxo `searchEntities`/tool de domínio → `buildCampaignLinks`; exemplos do catálogo E (dobradinhas do assessor → ficha + detalhes, não lista filtrada inventada).
- **Migration:** sem migration
- **Access / Consent:** RBAC na tool via papel + invariante “só ids/slugs fornecidos pelo modelo após tools de dados”; páginas continuam fail-closed no servidor
- **UI:** N/A (markdown GFM já renderiza links no `CampaignAIChat`)
### Catálogo v1 (implementação)
| Grupo | `destination` | Builder / path |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| A | `home`, `quadro`, `perfil`, `conceitos`, `giros` | literais + `campaignConceptHref(id)` |
| B detalhe | `municipality`, `leadership`, `dobradinha`, `advisor`, `organization`, `activity`, `demand`, `supporter` | `/campanha/{area}/[slug\|id]` |
| C lista | `municipalityList`, `leadershipList`, `dobradinhaList`, `advisorList`, `organizationList`, `activityList`, `demandList`, `supporterList`, `territoryList` | `build*ListHref` com subset de filtros do catálogo de produto |
| Leader | `leaderContacts` | `LEADER_CONTACTS_HOME` |
Filtros de lista expostos no schema Zod (alto valor operacional, espelhando intenção):
- **municipalityList:** `q`, `slug[]`, `region[]`, `advisor[]`, `coverage`, `priority`, `trend[]`, `class[]`, `level[]`
- **leadershipList:** `q`, `status[]`, `municipality[]`, `organization[]`, `stateDeputy[]`, `access`
- **dobradinhaList:** `q`, `party[]` (sem advisor)
- **advisorList:** `q`, `municipality[]` (gate `unrestricted`)
- **organizationList:** `q`, `kind`
- **activityList:** `tab`, `q`, `kind`, `status`, `municipality`
- **demandList:** `q`, `status`, `kind`, `activity`
- **supporterList:** `q`, `voteIntention`, `source`, `municipality`, `city`
- **territoryList:** `q`, `region[]`, `coverage`, `sort`, `dir`
Destinos **bloqueados para `leader`:** tudo exceto `home`, `perfil`, `leaderContacts`.
Destinos **bloqueados para `advisor`:** `advisor`, `advisorList`, `assessores` paths, `quadro`, `giros`, `conceitos` (staff-only nav).
### Dados → forma
- Forma: links markdown relativos (`[label](/campanha/…)`). O modelo recebe `{ path, label }` e formata na resposta.
- Rejeitadas: URLs absolutas (desnecessárias no mesmo origin); chips/botões “Abrir” (fora do appetite).
## Fases verificáveis
1. **Tracer / schema+server** — `campaignNavigationUrls.ts` com destinos A+B+C mínimos (home, municipality detail, municipalityList com `advisor`/`coverage`/`priority`); `buildCampaignLinks` tool; registro; testes unitários de canonicalização + leader lockdown + recusa de filtro inexistente em dobradinhas.
2. **Cobertura catálogo + prompt** — completar destinos restantes; atualizar `systemPrompt.ts`; testes para cada builder delegado (snapshot de href contra `build*Href` existentes).
3. **Gates** — `pnpm gate:fast`; push via `pnpm push`
## Rabbit holes / Não escopo (engenharia)
- Tool genérica `path: string` — rejeitada na intenção
- Resolver nome→slug dentro da URL tool — usar `searchEntities` / tools de domínio antes
- Cobrir 100% dos query params de sort/página de todas as listas
- Fechar sheet ao clicar link
- Auto `router.push`
- Rotas `…/nova` e município v2
- Alterar `searchEntities` para retornar href em todas as entidades (fora do escopo; pode ser débito barato)
## Riscos e mitigação
| Risco | Mitigação |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| Drift entre tool e contratos B18 | Delegar 100% aos `build*Href` / `parse*Params` existentes; testes que comparam output |
| Modelo inventa slug | Schema exige identificadores explícitos; prompt reforça “resolver antes”; tool não faz fuzzy match |
| Leader recebe link staff | Guard centralizado por `destination` + testes por papel |
| Schema Zod enorme | Discriminated union por destino; só params do catálogo v1 |
## Divergência da hipótese de direção (intenção)
- **Módulo puro separado** (`campaignNavigationUrls.ts`) em vez de colocar toda a lógica dentro de `tools/buildCampaignLinks.ts` — melhora testabilidade sem mudar o outcome.
- **Batch `links[]`** na mesma chamada — não estava explícito na intenção, mas suporta o caso “ficha do assessor + N dobradinhas” (catálogo E) sem N invocações.
## Aceite de engenharia
- [ ] Aceite de produto da intenção ainda coberto
- [ ] Invariantes AGENTS/engineering-standards
- [ ] Testes de domínio previstos (unit em `campaignNavigationUrls`; sem int DB — tool não escreve)
## Decisões de engenharia (self-score)
| Decisão | Recomendação | Rejeitadas |
| ------------------ | ---------------------------------------------- | --------------------------------------- |
| Onde vive a lógica | `campaignNavigationUrls.ts` puro + tool fina | Inline na tool; estender searchEntities |
| Formato de path | Relativo `/campanha/…` | Absoluto com host |
| API da tool | `links[]` batch com `destination` discriminado | Uma URL por chamada; path livre |
| RBAC | Guard por destino no módulo puro | Confiar só no fail-closed das páginas |
| Testes | Unit puro + comparação com builders existentes | E2E do chat neste item |
**Self-score decision-quality: 4/5** — decisões caras documentadas; appetite respeitado; rabbit holes nomeados; reusa shells/helpers; outcome intacto.