teqo-backup/docs/changelog/2026-09-18-c192.md
Francisco Solla 45eef25b1a feat(C192): busca semântica no acervo de falas (Closes #1147)
Modo "Por tema" no acervo de falas: expansão determinística do tema via
DeepSeek (generateObject, timeout, fallback null) alimenta o motor lexical
existente (searchText/keywords OR), mantendo facetas AND, paginação por fala,
o OR de cortes do C174 e o access control intacto. Resultado de tema mostra
selo e "Por que apareceu" com trecho real (frase contínua), sem score;
degradação honesta para termo exato com aviso e vazio honesto com saídas.

- URL: mode=tema (default omitido; canonicaliza sem q), seletor otimista
- ai/expandSpeechSearchTheme + lib/speechThemeTerms (sanitiza saída do modelo)
- view model com themeMatchTerm + espelho speechMatchesSearchTerm
- UI do card de tema (selos, proveniência, ações) e aviso degradado
- sem migration/Consent/exposição pública; gate de leitura inalterado
- testes unit/int/e2e; design hi-fi estendido e certificado pelo designer
2026-09-18 17:48:28 -03:00

2.6 KiB

C192 — Busca semântica no acervo de falas (2026-09-18): o acervo (/campanha/comunicacao/acervo) ganhou busca por tema ao lado da busca literal, sem índice vetorial nem backfill. (1) Modo explícito e visível: novo parâmetro de URL mode=tema (default termo, omitido — deep links da busca exata ficam byte-idênticos; mode=tema sem q canonicaliza fora), registrado em speechListParamNames; o seletor "Buscar por: Termo exato | Por tema" (segmented control, aria-pressed) é otimista e preserva facetas/página. (2) Ponte semântica determinística: expandSpeechSearchTheme (src/utilities/ai/, server-only) pede ao DeepSeek (generateObject, deepseek-flash, timeout 4s, temperatura 0.2) de 3 a 8 termos relacionados; nunca lança — sem chave, timeout, erro ou saída malformada resolve null (degradação), e lista vazia é resposta legítima (sem aviso). normalizeSpeechThemeTerms sanitiza a saída do modelo (%/_/\, termos <3 chars, dedupe, teto de 8/60 chars). (3) Motor lexical no caminho do Payload: buildSpeechListWhereIncludingCutOrigins OR-a q + termos expandidos (searchText like / keywords contains) com dedupe, mantém facetas AND, paginação por fala e o OR de origem de corte do C174 (ancorado só no q literal); payload.find segue com user + overrideAccess:false e canReadSpeechCatalog barra a chamada externa de ator negado (fail-closed). (4) Proveniência honesta: toSpeechListItemViewModel ganha themeMatchTerm e matchKind='theme'; o card de tema mostra selo "Tema" (+ "Termo exato" quando também casa literal) e o bloco "Por que apareceu" com o excerto real da fala e a frase marcada como faixa contínua (findPhraseRanges), sem score nem texto gerado; o CTA só oferece "Assistir no trecho" com casamento literal real. (5) Degradação e vazio: aviso discreto (Alert pending, literais da cena 04) com "Tentar por tema novamente" e resultados lexicais; o vazio honesto tem as saídas reformular/usar termo exato/limpar filtros (cena 03). (6) Design: o designer estendeu o artefato do gate (docs/plans/acervo-busca-semantica-ui-design.html, cenas 01/02) e certificou a implementação renderizada (desktop 1280 / mobile 390). (7) Testes: novos unit de speechThemeTerms e expandSpeechSearchTheme (mock de provider) e extensões de URL/where/espelho/view model/omnibox; int com expansor injetado (tema, fallback, guard de acesso); e2e do modo degradado sem chave (o playwright.config.ts agora zera DEEPSEEK_API_KEY no servidor e2e). Sem migration, sem collection/Consent novo, sem exposição pública. pnpm gate:ci verde (unit 3742, int 827, e2e do acervo 16).