15 KiB
B162 — Sollinha: tool de URLs para navegar a vistas de interesse
Status: ready Atualizado em: 2026-08-05 Issue: #383 Priority: P1 Model: composer-2.5 Model-local: deepseek-v4-flash-high Impeccable: A — N/A (links markdown no chat já existente; sem rearranjo de UI) Canvas UI: N/A — sem UI Appetite: ~0,5–1 dia eng; uma tool + catálogo de destinos + orientação no system prompt; sem migration / Consent / collection Responsável: —
Intenção
A Sollinha (chat IA em /campanha, v1 entregue 2026-08-04) já responde com dados reais via tools de leitura, mas não consegue levar o usuário até a tela onde esses dados vivem. Quem pergunta “e Ilhéus?” ou “quais dobradinhas o assessor X cuida?” recebe texto — e depois tem de achar o município / filtro / ficha na mão.
Queremos que a Sollinha monte links canônicos (lista filtrada ou detalhe) e os ofereça na resposta, para o staff abrir a vista certa em um clique. Isso não substitui a navegação pelo app; completa a resposta com o próximo passo operacional.
Sucessor de ai-chat-sollinha.md (entregue; plano imutável).
Persona e fluxo
- Persona / contexto: Coordenador / candidato / assessor no Field Desk, com o chat aberto ao lado (sheet) ou full-screen (drawer), sob pressão de tempo.
- Job principal: depois (ou junto) da resposta factual, ir à tela certa sem rebuscar na sidebar/omnibox.
- Fluxo desejado:
- Pergunta em linguagem natural (“abre Ilhéus”, “dobradinhas do João”, “municípios prioritários sem assessor”).
- Sollinha usa tools de dados se precisar resolver entidade / confirmar existência.
- Sollinha chama a tool de URL com destino + parâmetros canônicos.
- Resposta inclui link(s) clicáveis (markdown) — e, quando útil, mais de um caminho (ex.: ficha do assessor e lista de municípios da carteira).
- Anti-goals de produto:
- Substituir a navegação do app pela IA (o anti-goal original da v1 permanece).
- Inventar filtros/URLs que o app ainda não honra (ex.: lista de dobradinhas filtrada por assessor — ver catálogo).
- Auto-navegar / fechar o chat e forçar
router.pushsem o usuário clicar (surpreende). - Links para
/admin, site público, wizards de escrita ou rotas fora do escopo do papel (leader lockdown).
Objetivo e aceite
- Existe uma tool dedicada (nome de implementação livre) que só constrói paths
/campanha/…canônicos a partir de um catálogo de destinos + parâmetros conhecidos. - O system prompt ensina quando usar a tool (oferecer link quando a pergunta é sobre uma entidade/vista concreta; após responder com dados de uma entidade singular; quando o usuário pede explicitamente “abre / me manda o link / leva pra…”).
- Links na resposta são clicáveis no chat atual (markdown GFM já renderiza).
- Destinos cobertos no v1 = catálogo abaixo (vistas que já existem e filtros que a URL já aplica). Destinos sem filtro no app não são inventados — a tool recusa / devolve alternativa documentada.
- Staff com escopo restrito: a tool não precisa “esconder” paths (páginas já fail-closed), mas só deve apontar entidades já resolvidas por tools/dados no escopo do usuário (não inventar slug/id).
- Leader lockdown: sem links para municípios / dobradinhas / etc. (mesmo padrão da v1 — se o papel não vê a área, a tool não oferece).
- Sem migration, sem Consent, sem collection, sem persistência de histórico.
Dados (intenção)
- Vou apresentar dados? Não — esta tool não agrega métricas; só devolve path(s) + label humana.
- Decisões desbloqueadas: staff decide para onde ir a seguir após a resposta da IA (abrir ficha, revisar lista filtrada, profundar no glossário).
- Forma: adiada — links markdown bastam neste appetite; chips/botões “Abrir” ficam fora (ver questões).
Catálogo de destinos (produto — o que a tool precisa saber)
Inventário do que a Sollinha deve poder montar no v1. Cada linha = vista real no app hoje. Filtros = só os que a URL já entende.
A. Homes / referência
| Destino | Path | Quando oferecer |
|---|---|---|
| Início (mapa / dashboard) | /campanha |
“volta pro início”, visão geral |
| Conceitos / glossário | /campanha/conceitos (+ âncora #… se o conceito for conhecido) |
explicar captura, LQ, nível, etc. |
| Perfil | /campanha/perfil |
raro; só se pedir |
| Quadro | /campanha/quadro |
se o usuário citar o quadro |
B. Detalhes de entidade (1 registro)
| Entidade | Path | Identificador que a tool precisa |
|---|---|---|
| Município | /campanha/municipios/[slug] |
slug canônico (não nome solto sem resolver) |
| Liderança | /campanha/liderancas/[id] |
id |
| Dobradinha | /campanha/dobradinhas/[slug] |
slug |
| Assessor | /campanha/assessores/[id] |
id |
| Organização | /campanha/organizacoes/[slug] |
slug |
| Atividade | /campanha/atividades/[slug] |
slug |
| Demanda | /campanha/demandas/[slug] |
slug |
| Apoiador | /campanha/apoiadores/[id] |
id |
C. Listas com recorte (filtros que já existem na URL)
| Lista | Path base | Recortes úteis para a IA (já suportados) |
|---|---|---|
| Municípios | /campanha/municipios |
busca q; município(s) por slug; território de identidade; assessor; com/sem assessor; prioridade alta; tendência; classe territorial; nível N0–N4 / sem nível; compare (mapa) |
| Lideranças | /campanha/liderancas |
q; status; município(s); organização(ões); dobradinha(s); com/sem acesso ao app |
| Dobradinhas | /campanha/dobradinhas |
q; partido(s) — sem filtro por assessor hoje |
| Assessores | /campanha/assessores |
q; município(s) da carteira |
| Organizações | /campanha/organizacoes |
q; tipo |
| Atividades | /campanha/atividades |
preset/tab (próximos/todos/…); tipo; status; município; q |
| Demandas | /campanha/demandas |
q; status; tipo; atividade |
| Apoiadores | /campanha/apoiadores |
q; intenção de voto; fonte; município/cidade |
| Territórios | /campanha/territorios |
(contrato de sort/filtro já da lista) |
D. Fluxos auxiliares (incluir só se couber no appetite sem puxar wizard)
| Destino | Path | Nota |
|---|---|---|
| Compositor de giro | /campanha/atividades/giros |
staff; sem parâmetros inventados além do que o compositor já lê |
Nova entidade (…/nova) |
vários | fora do v1 — escreve/cria; anti-goal write |
E. Lacunas conscientes (NÃO inventar neste item)
| Pedido humano típico | Situação no app hoje | O que a Sollinha deve fazer neste item |
|---|---|---|
| “Dobradinhas do assessor X” (lista filtrada) | Relação assessor↔dobradinha existe (B156), filtro na lista de dobradinhas não | Oferecer ficha do assessor e/ou listar dobradinhas via tool de dados + links de detalhe de cada dobradinha; não fabricar ?advisor= em /campanha/dobradinhas |
| “Municípios do assessor X” | Sim — ?advisor= na lista de municípios |
Preferir lista filtrada + opcionalmente ficha do assessor |
Detalhe município v2 (/campanha/municipio/…/v2) |
Paralelo / cutover (B152) | Preferir canônico /campanha/municipios/[slug] até cutover de produto |
F. Como a IA deve escolher (orientação de produto no prompt)
- Entidade singular clara → detalhe + (opcional) lista filtrada se o job for comparativo.
- Conjunto / “quais / lista de” → lista com filtros canônicos; se o filtro não existir, dados no chat + links de detalhe.
- Nome ambíguo →
searchEntities(ou tool de domínio) antes de montar URL; nunca inventar slug/id. - Pergunta só analítica (“quantos votos…”) → dados primeiro; link de detalhe do município como “ver no app” quando ajuda.
- Pedido explícito de navegação (“abre…”, “me manda o link”) → URL é o outcome principal.
Direção no codebase (hipótese)
- Áreas prováveis:
src/utilities/ai/tools/(+ registro emindex.ts);src/utilities/ai/systemPrompt.ts; reuso dos builders/contratos já existentes (campaignListUrl,municipalityListUrl,*ListUrl,campaignPaths, âncoras de conceitos) — sem segundo gerador de query paralelo. - Precedente:
ai-chat-sollinha.md; contratos de lista pós-omnibox (B127+). - Risco de acoplamento: drift se a tool hardcodar params que a lista já canônica; leader lockdown; não apontar v2 como canônico antes do cutover.
Dependências
- Soft: Sollinha v1 já em produção (entregue).
- Soft: B156 (assessores por dobradinha) já em prod — explica o job “dobradinhas do assessor”, mas não desbloqueia filtro de lista.
- Nenhuma dependência dura de Issue aberta.
Fora de escopo
- Novos filtros de lista (ex.:
advisorem dobradinhas) — Issue sucessor se produto quiser. - Auto-navegação / deep-link que fecha o sheet sozinho.
- Write tools / wizards /
…/nova. - Histórico persistente, web search, STT.
- Site público /
/admin. - UI rica de “card de link” / botão Abrir (markdown basta).
- Trocar detalhe canônico para município v2.
Rabbit holes de produto
- “Uma tool genérica que aceita qualquer path.” Vira alucinação de URL e bypass de catálogo. Corte: catálogo fechado de destinos + params allowlisted.
- “Resolver nome→URL sem tools de dados.” Duplica busca e erra slug. Corte: URL tool exige ids/slugs já conhecidos ou resolve só via helpers/catalog já usados pelas outras tools — nunca chute.
- “Cobrir 100% dos query params de todas as listas.” Explode o schema da tool. Corte: params de alto valor operacional listados no catálogo; o resto fica para expansão.
- Inventar filtro assessor→dobradinhas. Outro item. Corte: alternativas do catálogo E.
Questões em aberto (produto)
- Links relativos (
/campanha/…) ou absolutos (domínio de produção)? Opções: A) relativo | B) absoluto com host da sessão | C) ambos. Recomendação: A — o chat roda no mesmo origin; markdown relativo abre na mesma aba/PWA. (assumido — validar) - Oferecer link proativamente ou só quando pedido? Opções: A) sempre que houver entidade singular na resposta | B) só sob pedido explícito | C) híbrido (proativo em entidade singular + sempre sob pedido). Recomendação: C. (assumido — validar)
- Quando o job for “dobradinhas do assessor” e não houver filtro de lista? Opções: A) só ficha do assessor | B) ficha + N links de detalhe das dobradinhas (via tool de dados) | C) inventar filtro agora. Recomendação: B; C fora de escopo. (assumido — validar)
- Clique no link deve fechar o chat? Opções: A) comportamento default do browser/sheet (sem lógica extra) | B) fechar sheet ao clicar link interno. Recomendação: A neste appetite. (assumido — validar)
- UI além de markdown (chip “Abrir Ilhéus”)? Opções: A) não neste item | B) sim. Recomendação: A (Impeccable A). (assumido — validar)
Referências
- GitHub Issue #383
- Canvas UI (gate): N/A
ai-chat-sollinha.md— v1 entreguesrc/utilities/ai/tools/,src/utilities/ai/systemPrompt.ts,src/components/campaign/shell/ai/CampaignAIChat.tsx- Contratos de URL:
src/utilities/campaignListUrl.ts,municipality/municipalityListUrl.ts,stateDeputyListUrl.ts,leadership/leadershipListUrl.ts,advisor/advisorListUrl.ts, … src/lib/campaignPaths.ts,src/lib/campaignIntelligenceConcepts.ts(âncoras)- AGENTS.md — rotas
/campanha, leader lockdown, RBAC