-
-
-
@@ -560,24 +558,24 @@
-
-
-
-
Por que apareceu
-- Trecho exemplificativo: “… - atendimento público e acesso universal à saúde …” +
+ “… atendimento público e + acesso universal à saúde + …”
-
-
@@ -631,24 +628,24 @@
-
-
-
Por que apareceu
-- Trecho exemplificativo: “… presença - da atenção básica nos bairros e comunidades …” +
+ “… presença da + atenção básica + nos bairros e comunidades …”
-
-
@@ -702,28 +698,28 @@
-
-
-
Por que apareceu
-- Trecho exemplificativo: “… - fortalecimento da rede pública de atendimento …” +
+ “… fortalecimento da + rede pública de atendimento + …”
-
-
-
-
-
-
-
Por que apareceu
-- Trecho exemplificativo: “… - + “… + defesa do SUS …” @@ -916,21 +908,24 @@
-
-
-
-
-
+
-
Por que apareceu
-- Trecho exemplificativo: “… atendimento público - e acesso universal à saúde …” +
+ “… atendimento público e + acesso universal à saúde + …”
- TemaTermo exato
+
+
-
+ TemaTermo exato
+
+ Fala · Data da fala · Duração
Fala · Data da fala · Duração
-
-
-
-
-
+
Por que apareceu
-- Trecho exemplificativo: “… - + “… + defesa do SUS …” @@ -1309,12 +1305,12 @@
-
- Trecho exemplificativo com o termo - + “… reafirmamos a + defesa do SUS - destacado no contexto literal. + como compromisso público …”
Tema da fala
Selo: “Tema”; quando também há
- casamento literal, o card acrescenta “Termo exato”, sem score numérico.
+ casamento literal, o card acrescenta “Termo exato”, sem score numérico. Os selos ocupam
+ uma linha própria, imediatamente antes da metainformação da fala; nunca ficam ao lado de
+ um título.
Proveniência: bloco “Por que
- apareceu” + trecho curto explicitamente exemplificativo neste artefato.
+ apareceu” + um único excerto real da fala, com o termo que de fato casou destacado. No
+ modo por tema, esse bloco substitui o excerto comum: as duas áreas nunca convivem nem
+ repetem o mesmo texto. “Trecho exemplificativo” não é copy do produto.
+
+
+ Precedência visual: evidência na
+ própria fala pelo tema vence o estado “Fala de origem”, mesmo quando não houve casamento
+ literal. Sem evidência de tema e sem casamento literal, permanece integralmente o branch
+ C174 (“Fala de origem” + nota + correspondência no corte). O card comum fica para o
+ resultado literal fora desses dois casos.
Miniaturas e conteúdo: caixas e
diff --git a/playwright.config.ts b/playwright.config.ts
index ac663fbf..6983f212 100644
--- a/playwright.config.ts
+++ b/playwright.config.ts
@@ -242,6 +242,12 @@ export default defineConfig({
// Keep e2e artifacts outside `.next`: a concurrent development server
// owns that entire directory and may clear nested production bundles.
NEXT_DIST_DIR: process.env.NEXT_DIST_DIR ?? '.next-e2e',
+ /*
+ * C192 — blank the DeepSeek key so the acervo's theme expansion always
+ * degrades to the literal search (never the network) and the degraded
+ * state stays deterministic, same principle as the Google test key.
+ */
+ DEEPSEEK_API_KEY: '',
PAYLOAD_SECRET: process.env.PAYLOAD_SECRET ?? 'test-only-secret-not-used-in-production',
// Prod mode serves a production build where `getCampaignInviteBaseURL`
// fails closed unless NEXT_PUBLIC_SITE_URL is an HTTPS public DNS name
diff --git a/src/app/(campaign)/campanha/(app)/comunicacao/acervo/page.tsx b/src/app/(campaign)/campanha/(app)/comunicacao/acervo/page.tsx
index 400251f8..1ff3ff26 100644
--- a/src/app/(campaign)/campanha/(app)/comunicacao/acervo/page.tsx
+++ b/src/app/(campaign)/campanha/(app)/comunicacao/acervo/page.tsx
@@ -12,7 +12,10 @@ import {
} from '@/components/campaign/shared/CampaignListPending'
import { CampaignPageShell } from '@/components/campaign/shell/CampaignPageShell'
import { SpeechAcervoFilters } from '@/components/campaign/speech/SpeechAcervoFilters'
+import { SpeechRefineSearchButton } from '@/components/campaign/speech/SpeechRefineSearchButton'
import { SpeechResultList } from '@/components/campaign/speech/SpeechResultList'
+import { SpeechThemeFallbackNotice } from '@/components/campaign/speech/SpeechThemeFallbackNotice'
+import { SpeechThemeRetryButton } from '@/components/campaign/speech/SpeechThemeRetryButton'
import { Button } from '@/components/ui/button'
import { campaignPageMetadataFromCatalog } from '@/lib/campaignPageChrome'
import { CAMPAIGN_COMMUNICATION_ACERVO, CAMPAIGN_COMMUNICATION_CORTES } from '@/lib/campaignPaths'
@@ -36,6 +39,8 @@ export default async function SpeechAcervoPage({ searchParams }: SpeechAcervoPag
if (data.redirectHref) redirect(data.redirectHref)
const hasFilters = buildSpeechFiltersKey(data.state) !== ''
+ const themeMode = data.state.mode === 'tema'
+ const themeActive = themeMode && data.themeApplied && !data.themeUnavailable
return (
@@ -53,28 +58,74 @@ export default async function SpeechAcervoPage({ searchParams }: SpeechAcervoPag
key={buildSpeechFiltersKey(data.state)}
state={data.state}
filterOptions={data.filterOptions}
+ themeUnavailable={data.themeUnavailable}
/>
+ {data.themeUnavailable ?
+ {themeMode ? (
+
-
+ {themeActive ? (
+
)}
diff --git a/src/components/campaign/shared/CampaignListEmptyState.tsx b/src/components/campaign/shared/CampaignListEmptyState.tsx
index 794ed783..532f7079 100644
--- a/src/components/campaign/shared/CampaignListEmptyState.tsx
+++ b/src/components/campaign/shared/CampaignListEmptyState.tsx
@@ -9,32 +9,40 @@ import {
EmptyMedia,
EmptyTitle,
} from '@/components/ui/Empty'
+import { cn } from '@/lib/utils'
/**
* The standard campaign list empty state (icon, title, description, optional
* CTA). Rendered inside `CampaignListResults` so it dims with the shared
- * transition like the rows it replaces.
+ * transition like the rows it replaces. `className` / `mediaClassName` /
+ * `contentClassName` let a caller tune the shell without forking it (C192).
*/
export const CampaignListEmptyState = ({
icon: Icon,
title,
description,
children,
+ className,
+ mediaClassName,
+ contentClassName,
}: {
icon: LucideIcon
title: string
description: ReactNode
/** Call-to-action button(s). */
children?: ReactNode
+ className?: string
+ mediaClassName?: string
+ contentClassName?: string
}) => (
-
+
-
+
{title}
{description}
- {children ? {children} : null}
+ {children ? {children} : null}
)
diff --git a/src/components/campaign/speech/SpeechAcervoFilters.tsx b/src/components/campaign/speech/SpeechAcervoFilters.tsx
index a9d56dfd..a46808f7 100644
--- a/src/components/campaign/speech/SpeechAcervoFilters.tsx
+++ b/src/components/campaign/speech/SpeechAcervoFilters.tsx
@@ -1,5 +1,6 @@
'use client'
+import { SparklesIcon, TriangleAlertIcon } from 'lucide-react'
import { useMemo, useOptimistic, useState } from 'react'
import {
@@ -12,6 +13,7 @@ import {
} from '@/components/campaign/shared/CampaignListOmnibox'
import { useCampaignListFilterNavigation } from '@/components/campaign/shared/useCampaignListFilterNavigation'
import { SPEECH_SCOPES, SPEECH_TOPICS } from '@/lib/speechFacets'
+import { cn } from '@/lib/utils'
import {
buildSpeechListHref,
SPEECH_DURATION_BUCKETS,
@@ -20,14 +22,17 @@ import {
speechTopicLabels,
type SpeechFilterOptions,
type SpeechListState,
+ type SpeechSearchMode,
} from '@/utilities/speech/speechListUrl'
import {
applySpeechOmniboxSuggestion,
+ applySpeechSearchMode,
buildSpeechOmniboxChips,
buildSpeechOmniboxSuggestionSeeds,
clearSpeechOmnibox,
filterSpeechOmniboxSuggestions,
removeSpeechOmniboxChip,
+ SPEECH_OMNIBOX_ID,
type SpeechOmniboxAction,
} from '@/utilities/speech/speechOmnibox'
@@ -58,12 +63,27 @@ const selectedTriggerLabel = (
return `${base}: ${values.length}`
}
+/** C192 — segmented search-mode button (mobile full width, desktop inline). */
+const modeButtonClass = (active: boolean, tone: 'termo' | 'tema'): string =>
+ cn(
+ 'min-h-11 rounded-md px-3 text-sm md:min-h-9',
+ active
+ ? cn(
+ 'bg-white font-semibold shadow-sm ring-1 ring-border',
+ tone === 'tema' ? 'text-primary' : 'text-foreground',
+ )
+ : 'font-medium text-muted-foreground',
+ )
+
export const SpeechAcervoFilters = ({
state,
filterOptions,
+ themeUnavailable = false,
}: {
state: SpeechListState
filterOptions: SpeechFilterOptions
+ /** C192 — the theme expansion is down; the selector reflects the fallback. */
+ themeUnavailable?: boolean
}) => {
const { navigate, isPending } = useCampaignListFilterNavigation({
state,
@@ -72,6 +92,9 @@ export const SpeechAcervoFilters = ({
const [query, setQuery] = useState('')
const [viewState, setOptimisticState] = useOptimistic(state)
+ const activeMode: SpeechSearchMode =
+ viewState.mode === 'tema' && !themeUnavailable ? 'tema' : 'termo'
+
const municipalityLabelsById = useMemo(() => {
const map = new Map()
for (const option of filterOptions.municipalities) {
@@ -110,6 +133,12 @@ export const SpeechAcervoFilters = ({
navigate(action.state)
}
+ const runMode = (mode: SpeechSearchMode) => {
+ const next = applySpeechSearchMode({ state: viewState, mode }).state
+ setOptimisticState(next)
+ navigate(next)
+ }
+
const facetRows = (
prefix: string,
options: readonly { value: string; label: string }[],
@@ -206,7 +235,7 @@ export const SpeechAcervoFilters = ({
}}
>
+
+ ) : null}
+
{data.rows.length > 0 ? (
+
+ {data.themeUnavailable ? + {data.themeUnavailable + ? 'Resultados por termo exato' + : themeActive + ? 'Resultados por tema' + : 'Resultados'} +
++ {data.themeUnavailable + ? 'Comportamento atual do acervo.' + : themeActive + ? 'Confira o indício em cada fala antes de abrir.' + : 'Nenhum termo relacionado foi acrescentado; mostramos a busca literal.'} +
+
+
+ ) : (
+
+ )}
+
+
+
+ Buscar por
+
+
+
+
+
+
+ + {themeUnavailable + ? 'Indisponível agora; mostramos o termo exato.' + : 'Encontra falas relacionadas pelo sentido.'} +
+ (
+
+)
diff --git a/src/components/campaign/speech/SpeechResultCard.tsx b/src/components/campaign/speech/SpeechResultCard.tsx
index 98de302e..956df7b8 100644
--- a/src/components/campaign/speech/SpeechResultCard.tsx
+++ b/src/components/campaign/speech/SpeechResultCard.tsx
@@ -1,4 +1,4 @@
-import { ExternalLinkIcon, PlayIcon } from 'lucide-react'
+import { ExternalLinkIcon, PlayIcon, SparklesIcon } from 'lucide-react'
import Link from 'next/link'
import type { ReactNode } from 'react'
@@ -32,6 +32,42 @@ const SpeechExcerpt = ({ excerpt }: { excerpt: SpeechHighlightedExcerpt }) => {
)
}
+/**
+ * C192 — the theme result provenance: the real excerpt that matched the theme,
+ * with the expanded term highlighted. It replaces the common excerpt (never
+ * coexists with it) and carries no score.
+ */
+const SpeechThemeProvenance = ({ excerpt }: { excerpt: SpeechHighlightedExcerpt }) => {
+ if (excerpt.parts.length === 0) return null
+
+ return (
+
+
+ )
+}
+
+const SpeechThemeBadges = ({ matchedTextSearch }: { matchedTextSearch: boolean }) => (
+ + Por que apareceu +
+
+ {`“${excerpt.truncatedStart ? '… ' : ''}`}
+
+
+
+ Tema
+
+ {matchedTextSearch ? (
+
+ Termo exato
+
+ ) : null}
+
+)
+
const ActionLink = ({
href,
children,
@@ -60,34 +96,47 @@ const SpeechMetaLine = ({
}: {
speech: SpeechListItemViewModel
originLabel?: boolean
+}) => {
+ const items: string[] = []
+ if (originLabel) items.push('Fala de origem')
+ items.push(speech.speechAtLabel)
+ if (speech.type) items.push(speech.type)
+ if (speech.durationLabel) items.push(speech.durationLabel)
+ if (speech.presidingOfficer) items.push(`Presidiu: ${speech.presidingOfficer}`)
+
+ return (
+
+ {items.map((item, index) => (
+
+ {index > 0 ?
+ )
+}
+
+/**
+ * The primary CTA of every result card: a link to the speech (or its trecho)
+ * whose variant/width the caller owns (C192 adds the theme appearance).
+ */
+const SpeechWatchButton = ({
+ speech,
+ watchLabel,
+ variant,
+ className,
+}: {
+ speech: SpeechListItemViewModel
+ watchLabel: string
+ variant: 'default' | 'outline'
+ className: string
}) => (
-
- {originLabel ? (
- <>
- Fala de origem
-
+
)
const SpeechActions = ({
@@ -100,12 +149,12 @@ const SpeechActions = ({
fullWidthOnMobile?: boolean
}) => (
-
+ {
// C174 (option B): a speech that surfaced only because a cut matched the term
// shows the origin note instead of an excerpt the speech does not contain, and
- // the actions sit at the top right (approved scene 05).
- if (!speech.matchedTextSearch) {
+ // the actions sit at the top right (approved scene 05). C192 — a theme result
+ // outranks this branch: the theme evidence lives in the speech itself.
+ if (!speech.matchedTextSearch && speech.themeMatchTerm === null) {
return (
@@ -168,67 +218,109 @@ export const SpeechResultCard = ({
visibleTopics.length +
(speech.scopes.length - visibleScopes.length) +
(speech.keywords.length - visibleKeywords.length)
- const watchLabel = speech.matchKind === 'segment' ? 'Assistir no trecho' : 'Ver fala'
- const excerptNode =
+ {topic.label}
+
+ ))}
+ {visibleScopes.map((scope) => (
+
+ {scope.label}
+
+ ))}
+ {visibleKeywords.map((keyword) => (
+
+ {keyword}
+
+ ))}
+ {hiddenChips > 0 ? (
+
+ +{hiddenChips}
+
+ ) : null}
+
+ )
+ const hasChips = Boolean(speech.topics.length || speech.scopes.length || speech.keywords.length)
return (
-
+
+ ) : (
+
+
{speech.thumbnailUrl ? (
- {speech.topics.length || speech.scopes.length || speech.keywords.length ? (
- {excerptNode}
+ {bodyNode}
- {visibleTopics.map((topic) => (
-
- {topic.label}
-
- ))}
- {visibleScopes.map((scope) => (
-
- {scope.label}
-
- ))}
- {visibleKeywords.map((keyword) => (
-
- {keyword}
-
- ))}
- {hiddenChips > 0 ? (
-
- +{hiddenChips}
-
- ) : null}
+ {isTheme ? (
+ (null)
@@ -32,7 +36,10 @@ export const SpeechResultThumbnail = ({
{settled ? null :
+
+
+ A busca por tema está indisponível agora.
+
+
+ Você pediu “Por tema”. Para não interromper o trabalho, mostramos abaixo os resultados por
+ termo exato.
+
+
+)
diff --git a/src/components/campaign/speech/SpeechThemeRetryButton.tsx b/src/components/campaign/speech/SpeechThemeRetryButton.tsx
new file mode 100644
index 00000000..4b26fcd3
--- /dev/null
+++ b/src/components/campaign/speech/SpeechThemeRetryButton.tsx
@@ -0,0 +1,24 @@
+'use client'
+
+import { useRouter } from 'next/navigation'
+import { useTransition } from 'react'
+
+import { Button } from '@/components/ui/button'
+
+/** C192 — re-runs the same `mode=tema` request after a degraded fallback. */
+export const SpeechThemeRetryButton = () => {
+ const router = useRouter()
+ const [isPending, startTransition] = useTransition()
+
+ return (
+
+ )
+}
diff --git a/src/lib/speechHighlight.ts b/src/lib/speechHighlight.ts
index ccce8261..a844c2dc 100644
--- a/src/lib/speechHighlight.ts
+++ b/src/lib/speechHighlight.ts
@@ -100,9 +100,41 @@ export const findHighlightRanges = (text: string, query: string): SpeechHighligh
}
}
- ranges.sort((left, right) => left.start - right.start || left.end - right.end)
+ return mergeHighlightRanges(ranges)
+}
+
+/**
+ * C192 — every occurrence of the whole normalized PHRASE as a single range, so
+ * a theme match like "acesso universal à saúde" is one continuous band (the
+ * per-term search would drop the "à" and split the band). Falls back to the
+ * per-term ranges when the phrase does not occur contiguously.
+ */
+export const findPhraseRanges = (text: string, phrase: string): SpeechHighlightRange[] => {
+ const needle = normalizeForSearch(phrase)
+ if (!needle || text.length === 0) return []
+
+ const { normalized, sourceIndex } = buildNormalizedIndex(text)
+ if (normalized.length === 0) return []
+
+ const ranges: SpeechHighlightRange[] = []
+ let from = 0
+ while (from <= normalized.length - needle.length) {
+ const at = normalized.indexOf(needle, from)
+ if (at === -1) break
+ ranges.push({
+ start: sourceIndex[at]!,
+ end: sourceIndex[at + needle.length - 1]! + 1,
+ })
+ from = at + 1
+ }
+
+ return ranges.length > 0 ? mergeHighlightRanges(ranges) : findHighlightRanges(text, phrase)
+}
+
+const mergeHighlightRanges = (ranges: readonly SpeechHighlightRange[]): SpeechHighlightRange[] => {
+ const sorted = [...ranges].sort((left, right) => left.start - right.start || left.end - right.end)
const merged: SpeechHighlightRange[] = []
- for (const range of ranges) {
+ for (const range of sorted) {
const last = merged[merged.length - 1]
if (last && range.start <= last.end) {
if (range.end > last.end) last.end = range.end
@@ -142,12 +174,12 @@ export const splitHighlightedParts = (text: string, query: string): SpeechHighli
export const buildHighlightedExcerpt = (
text: string,
query: string,
- { radius = 160 }: { radius?: number } = {},
+ { radius = 160, phrase = false }: { radius?: number; phrase?: boolean } = {},
): SpeechHighlightedExcerpt => {
const trimmed = text.trim()
if (trimmed === '') return { parts: [], truncatedStart: false, truncatedEnd: false }
- const ranges = findHighlightRanges(trimmed, query)
+ const ranges = phrase ? findPhraseRanges(trimmed, query) : findHighlightRanges(trimmed, query)
const focus = ranges[0]
const windowStart = focus ? Math.max(0, focus.start - radius) : 0
const windowEnd = focus
diff --git a/src/lib/speechSearch.ts b/src/lib/speechSearch.ts
index 1f9144f6..ec573aa0 100644
--- a/src/lib/speechSearch.ts
+++ b/src/lib/speechSearch.ts
@@ -21,12 +21,29 @@ type SpeechSearchableRecord = {
}
/**
- * C180 — pure mirror of the textual `where` branch
+ * C180 — pure mirror of a SINGLE textual `where` branch
* (`speechListFilters.buildSpeechTextBranches`): normalized `searchText` LIKE
- * the normalized query, OR a raw official keyword containing the query.
+ * the normalized term, OR a raw official keyword containing the term.
* `keywords` compare case-insensitively (accent still significant) to match the
- * ILIKE `%q%` Postgres runs. Adding or removing a branch there means changing
- * this predicate and its test in the same commit.
+ * ILIKE `%term%` Postgres runs. Adding or removing a branch there means
+ * changing this predicate and its test in the same commit. An empty term never
+ * matches (a branch with no term cannot surface a row).
+ */
+export const speechMatchesSearchTerm = (
+ speech: SpeechSearchableRecord,
+ term: string | undefined,
+): boolean => {
+ const trimmed = term?.trim()
+ if (!trimmed) return false
+ if (normalizeForSearch(speech.searchText ?? '').includes(normalizeForSearch(trimmed))) return true
+ const lowered = trimmed.toLowerCase()
+ return (speech.keywords ?? []).some((keyword) => keyword.toLowerCase().includes(lowered))
+}
+
+/**
+ * C180 — the search query mirror: empty/missing query is an unconditional match
+ * (no textual filter), otherwise any of its terms. C192 reuses
+ * `speechMatchesSearchTerm` for the expanded theme terms.
*/
export const speechMatchesSearchQuery = (
speech: SpeechSearchableRecord,
@@ -34,9 +51,7 @@ export const speechMatchesSearchQuery = (
): boolean => {
const trimmed = query?.trim()
if (!trimmed) return true
- if (normalizeForSearch(speech.searchText ?? '').includes(normalizeForSearch(trimmed))) return true
- const lowered = trimmed.toLowerCase()
- return (speech.keywords ?? []).some((keyword) => keyword.toLowerCase().includes(lowered))
+ return speechMatchesSearchTerm(speech, trimmed)
}
/**
diff --git a/src/lib/speechThemeTerms.ts b/src/lib/speechThemeTerms.ts
new file mode 100644
index 00000000..266847be
--- /dev/null
+++ b/src/lib/speechThemeTerms.ts
@@ -0,0 +1,30 @@
+/**
+ * C192 — sanitization of the LLM-expanded theme terms before they reach the
+ * Payload `where`. The expansion is untrusted model output: `%`/`_`/`\` would
+ * widen the `LIKE`/`ILIKE` patterns, very short tokens produce noise, and the
+ * list has to stay bounded so the textual OR does not explode. Pure and
+ * client-safe.
+ */
+import { normalizeForSearch, uniqueByNormalizedForm } from '@/lib/speechSearch'
+
+export const MAX_SPEECH_THEME_TERMS = 8
+export const MIN_SPEECH_THEME_TERMS = 3
+export const MAX_SPEECH_THEME_TERM_LENGTH = 60
+const MIN_THEME_TERM_LENGTH = 3
+const LIKE_WILDCARDS = /[%_\\]/g
+
+const sanitizeSpeechThemeTerm = (value: string): string =>
+ value
+ .replace(LIKE_WILDCARDS, ' ')
+ .replace(/\s+/g, ' ')
+ .trim()
+ .slice(0, MAX_SPEECH_THEME_TERM_LENGTH)
+ .trim()
+
+/** Removes wildcards, drops too-short/empty terms, dedupes and caps the list. */
+export const normalizeSpeechThemeTerms = (values: readonly string[]): string[] =>
+ uniqueByNormalizedForm(
+ values
+ .map(sanitizeSpeechThemeTerm)
+ .filter((term) => normalizeForSearch(term).length >= MIN_THEME_TERM_LENGTH),
+ ).slice(0, MAX_SPEECH_THEME_TERMS)
diff --git a/src/utilities/ai/expandSpeechSearchTheme.ts b/src/utilities/ai/expandSpeechSearchTheme.ts
new file mode 100644
index 00000000..4bde7b5d
--- /dev/null
+++ b/src/utilities/ai/expandSpeechSearchTheme.ts
@@ -0,0 +1,74 @@
+import 'server-only'
+
+import { deepSeek } from '@ai-sdk/deepseek'
+import { generateObject } from 'ai'
+import { z } from 'zod'
+
+import {
+ MAX_SPEECH_THEME_TERM_LENGTH,
+ MAX_SPEECH_THEME_TERMS,
+ MIN_SPEECH_THEME_TERMS,
+ normalizeSpeechThemeTerms,
+} from '@/lib/speechThemeTerms'
+
+const EXPAND_TIMEOUT_MS = 4000
+const MAX_OUTPUT_TOKENS = 200
+const MAX_THEME_LENGTH = 200
+
+const expandSchema = z.object({
+ terms: z
+ .array(z.string())
+ .describe(
+ `Termos e expressões curtas (${MIN_SPEECH_THEME_TERMS} a ${MAX_SPEECH_THEME_TERMS}) que podem aparecer na transcrição de falas sobre o tema. Lista vazia quando não houver termo confiável.`,
+ ),
+})
+
+const EXPAND_SYSTEM_PROMPT =
+ 'Você ajuda a assessoria de comunicação a achar, no acervo de discursos do deputado Jorge Solla, ' +
+ 'falas sobre um tema mesmo quando ele não usou as palavras exatas da busca. ' +
+ 'Receberá o tema digitado e deve devolver termos e expressões curtas que provavelmente aparecem ' +
+ 'na transcrição de uma fala sobre esse tema — sinônimos, nomes de programas, termos técnicos e ' +
+ 'palavras relacionadas. Inclua a própria expressão do tema quando ela for útil. ' +
+ `Devolva de ${MIN_SPEECH_THEME_TERMS} a ${MAX_SPEECH_THEME_TERMS} termos, cada um com no máximo ${MAX_SPEECH_THEME_TERM_LENGTH} caracteres, sem explicações, ` +
+ 'sem pontuação extra e sem termos genéricos que apareceriam em qualquer discurso (ex.: "Brasil", ' +
+ '"povo", "governo"). Se não houver termo confiável, devolva a lista vazia. Nunca invente fatos.'
+
+type SpeechThemeExpansion = { terms: string[] }
+
+/**
+ * The injectable expansion boundary (tests pass a deterministic resolver, the
+ * same pattern as `SpeechVideoStartResolver`).
+ */
+export type SpeechThemeExpansionResolver = (theme: string) => Promise
+
+/**
+ * C192 — resolves the query into a theme expansion. Never throws: missing key,
+ * empty theme, timeout, provider error or malformed output resolve to `null`,
+ * and the caller falls back to the literal search with a discreet notice. An
+ * empty `terms` list is a legitimate answer (the model ran but had nothing to
+ * add) and is distinct from `null` ("mechanism unavailable").
+ */
+export const expandSpeechSearchTheme: SpeechThemeExpansionResolver = async (theme) => {
+ if (!process.env.DEEPSEEK_API_KEY) return null
+
+ const trimmed = theme.trim().slice(0, MAX_THEME_LENGTH)
+ if (!trimmed) return null
+
+ try {
+ const { object } = await generateObject({
+ model: deepSeek('deepseek-flash'),
+ schema: expandSchema,
+ system: EXPAND_SYSTEM_PROMPT,
+ prompt: trimmed,
+ // Deterministic as the provider allows: pages 2+ of the same search must
+ // not be built from a different expansion.
+ temperature: 0,
+ maxOutputTokens: MAX_OUTPUT_TOKENS,
+ abortSignal: AbortSignal.timeout(EXPAND_TIMEOUT_MS),
+ })
+
+ return { terms: normalizeSpeechThemeTerms(object.terms) }
+ } catch {
+ return null
+ }
+}
diff --git a/src/utilities/speech/speechListFilters.ts b/src/utilities/speech/speechListFilters.ts
index b59c5365..da455242 100644
--- a/src/utilities/speech/speechListFilters.ts
+++ b/src/utilities/speech/speechListFilters.ts
@@ -49,22 +49,48 @@ const buildSpeechFacetWhere = (state: SpeechListState): Where[] => {
return filters
}
-const buildSpeechTextBranches = (q: string): Where[] => [
- { searchText: { like: normalizeForSearch(q) } },
- { keywords: { contains: q } },
-]
+const buildSpeechTextBranches = (q: string, themeTerms: readonly string[] = []): Where[] => {
+ const branches: Where[] = []
+ const seenText = new Set()
+ const seenKeyword = new Set()
+
+ // C192 — the literal query plus the expanded theme terms, each contributing
+ // the same two branches (normalized text / raw keyword). Duplicates are
+ // dropped so an expansion that repeats the query does not widen the OR.
+ for (const term of [q, ...themeTerms]) {
+ const normalized = normalizeForSearch(term)
+ if (normalized && !seenText.has(normalized)) {
+ seenText.add(normalized)
+ branches.push({ searchText: { like: normalized } })
+ }
+ const raw = term.trim()
+ const lowered = raw.toLowerCase()
+ if (raw && !seenKeyword.has(lowered)) {
+ seenKeyword.add(lowered)
+ branches.push({ keywords: { contains: raw } })
+ }
+ }
+
+ return branches
+}
/**
- * The textual branch: normalized speech text OR a raw official keyword. The
- * keyword `contains` compiles to ILIKE `%q%` — case-insensitive, accent still
- * significant. The view-model mirror is `lib/speechSearch.speechMatchesSearchQuery`
- * (C180); a semantics change here has to land there too.
+ * The textual branch: normalized speech text OR a raw official keyword, for the
+ * query and (C192) every expanded theme term. The keyword `contains` compiles
+ * to ILIKE `%q%` — case-insensitive, accent still significant. The view-model
+ * mirror is `lib/speechSearch.speechMatchesSearchTerm`; a semantics change here
+ * has to land there too.
*/
-const buildSpeechTextWhere = (q: string): Where => ({ or: buildSpeechTextBranches(q) })
+const buildSpeechTextWhere = (q: string, themeTerms: readonly string[] = []): Where => ({
+ or: buildSpeechTextBranches(q, themeTerms),
+})
-export const buildSpeechListWhere = (state: SpeechListState): Where => {
+export const buildSpeechListWhere = (
+ state: SpeechListState,
+ themeTerms: readonly string[] = [],
+): Where => {
const filters = buildSpeechFacetWhere(state)
- if (state.q) filters.push(buildSpeechTextWhere(state.q))
+ if (state.q) filters.push(buildSpeechTextWhere(state.q, themeTerms))
return filters.length ? { and: filters } : {}
}
@@ -72,15 +98,18 @@ export const buildSpeechListWhere = (state: SpeechListState): Where => {
/**
* C174 (option B) — the acervo `where` widened to the origin speech of a
* matching cut: the page still paginates by SPEECH, so the origin ids are OR-ed
- * into the textual branch (facets stay AND-ed over every row).
+ * into the textual branch (facets stay AND-ed over every row). C192 adds the
+ * expanded theme terms to that same textual branch; only the literal query
+ * drives the cut-origin lookup.
*/
export const buildSpeechListWhereIncludingCutOrigins = (
state: SpeechListState,
originSpeechIds: readonly number[],
+ themeTerms: readonly string[] = [],
): Where => {
const filters = buildSpeechFacetWhere(state)
if (state.q) {
- const branches = buildSpeechTextBranches(state.q)
+ const branches = buildSpeechTextBranches(state.q, themeTerms)
if (originSpeechIds.length) branches.push({ id: { in: [...originSpeechIds] } })
filters.push({ or: branches })
}
diff --git a/src/utilities/speech/speechListUrl.ts b/src/utilities/speech/speechListUrl.ts
index 58dbfc2e..46defaf8 100644
--- a/src/utilities/speech/speechListUrl.ts
+++ b/src/utilities/speech/speechListUrl.ts
@@ -26,6 +26,14 @@ import {
export const speechPageSize = 25
+/**
+ * C192 — search mode of the acervo. `termo` is the literal search (default,
+ * never serialized so existing deep links stay byte-identical); `tema` asks the
+ * semantic bridge for related terms. Kept as a single-value param, only
+ * meaningful alongside `q`.
+ */
+export type SpeechSearchMode = 'termo' | 'tema'
+
/** Duration buckets are ranges over `durationSeconds`; `sem_duracao` is null. */
export const SPEECH_DURATION_BUCKETS = [
{ value: 'curta', label: 'Até 2 min' },
@@ -51,6 +59,7 @@ export const speechScopeLabels = Object.fromEntries(
export type SpeechListState = {
page: number
q?: string
+ mode?: SpeechSearchMode
years?: number[]
topics?: SpeechTopic[]
scopes?: SpeechScope[]
@@ -70,6 +79,7 @@ type RawSpeechListParams = RawSearchParams
const speechListParamNames = [
'q',
+ 'mode',
'year',
'topic',
'scope',
@@ -95,10 +105,15 @@ const parseMunicipalityValues = (raw: string | string[] | undefined): number[] =
.map((token) => strictDecimalInteger(token))
.filter((id): id is number => id !== undefined && id > 0)
+/** Only `tema` is meaningful; anything else (and `termo`) means the default. */
+const parseSpeechSearchMode = (raw: string | string[] | undefined): SpeechSearchMode | undefined =>
+ firstValue(raw) === 'tema' ? 'tema' : undefined
+
export const parseSpeechListParams = (params: RawSpeechListParams): SpeechListState => {
const rawPage = strictDecimalInteger(firstValue(params.page))
const rawQ = normalizedText(firstValue(params.q))
const q = rawQ && isContactSearchQueryReady(rawQ) ? rawQ : undefined
+ const mode = parseSpeechSearchMode(params.mode)
const years = parseYearValues(params.year)
const topics = parseExhaustiveEnumParam(params.topic, speechTopicSet)
const scopes = parseExhaustiveEnumParam(params.scope, speechScopeSet)
@@ -112,6 +127,7 @@ export const parseSpeechListParams = (params: RawSpeechListParams): SpeechListSt
return {
page: rawPage ?? 1,
...(q ? { q } : {}),
+ ...(mode ? { mode } : {}),
...(years.length ? { years } : {}),
...(topics.length ? { topics } : {}),
...(scopes.length ? { scopes } : {}),
@@ -127,6 +143,7 @@ const speechListStateToRawParams = (
): RawSpeechListParams => ({
page: String(page),
q: state.q,
+ mode: state.mode,
year: state.years?.map(String),
topic: state.topics,
scope: state.scopes,
@@ -141,6 +158,9 @@ export const serializeCanonicalSpeechListSearchParams = (
): URLSearchParams => {
const params = new URLSearchParams()
if (canonicalState.q) params.set('q', canonicalState.q)
+ // `termo` is the default and never serialized; `tema` only makes sense with a
+ // query, so a theme param without `q` canonicalizes away.
+ if (canonicalState.mode === 'tema' && canonicalState.q) params.set('mode', 'tema')
for (const year of canonicalState.years ?? []) params.append('year', String(year))
for (const topic of canonicalState.topics ?? []) params.append('topic', topic)
for (const scope of canonicalState.scopes ?? []) params.append('scope', scope)
diff --git a/src/utilities/speech/speechOmnibox.ts b/src/utilities/speech/speechOmnibox.ts
index 3777d6a8..00546dd7 100644
--- a/src/utilities/speech/speechOmnibox.ts
+++ b/src/utilities/speech/speechOmnibox.ts
@@ -22,6 +22,7 @@ import {
speechTopicLabels,
type SpeechDurationBucket,
type SpeechListState,
+ type SpeechSearchMode,
} from '@/utilities/speech/speechListUrl'
export type SpeechFilterOption = {
@@ -29,6 +30,12 @@ export type SpeechFilterOption = {
label: string
}
+/**
+ * C192 — the omnibox input's DOM id, shared by the filters bar and the empty
+ * state's "Reformular busca" focus action.
+ */
+export const SPEECH_OMNIBOX_ID = 'speech-omnibox'
+
export type SpeechOmniboxAction =
| { kind: 'url'; state: SpeechListState }
| { kind: 'clear'; state: SpeechListState }
@@ -238,13 +245,32 @@ export const removeSpeechOmniboxChip = ({
state: SpeechListState
chipId: string
}): SpeechOmniboxAction => {
- if (chipId === 'q') return { kind: 'url', state: withPageReset({ ...state, q: undefined }) }
+ // Dropping the query also drops the theme mode: a theme without a query has
+ // nothing to expand.
+ if (chipId === 'q') {
+ return { kind: 'url', state: withPageReset({ ...state, q: undefined, mode: undefined }) }
+ }
const { key, value } = chipPrefix(chipId)
const next = mutateFacet(withPageReset(state), key, value, 'remove')
return { kind: 'url', state: next ?? state }
}
+/**
+ * C192 — the search mode toggle. `tema` only sticks with a query; `termo`
+ * (the default) clears the param so the URL stays canonical and shareable.
+ */
+export const applySpeechSearchMode = ({
+ state,
+ mode,
+}: {
+ state: SpeechListState
+ mode: SpeechSearchMode
+}): SpeechOmniboxAction => ({
+ kind: 'url',
+ state: withPageReset({ ...state, mode: mode === 'tema' && state.q ? 'tema' : undefined }),
+})
+
export const clearSpeechOmnibox = (_state: SpeechListState): SpeechOmniboxAction => ({
kind: 'clear',
state: { page: 1 },
diff --git a/src/utilities/speech/speechPageData.ts b/src/utilities/speech/speechPageData.ts
index 743df116..bae9d337 100644
--- a/src/utilities/speech/speechPageData.ts
+++ b/src/utilities/speech/speechPageData.ts
@@ -2,8 +2,13 @@ import 'server-only'
import type { Payload } from 'payload'
+import { canReadSpeechCatalog } from '@/lib/campaignRoles'
import { measuredVideoLagSeconds, parseYoutubeVideoId } from '@/lib/speechVod'
import type { CampaignUser, Speech } from '@/payload-types'
+import {
+ expandSpeechSearchTheme,
+ type SpeechThemeExpansionResolver,
+} from '@/utilities/ai/expandSpeechSearchTheme'
import { createEntityNotFoundError } from '@/utilities/entityNotFound'
import { loadMunicipalityLabelsByIds } from '@/utilities/loadNamesByIds'
import { getYouTubeVideoStart } from '@/utilities/socialFeed/youtubeFeed'
@@ -155,17 +160,36 @@ export type SpeechAcervoPageData = {
totalDocs: number
totalPages: number
filterOptions: SpeechFilterOptions
+ /**
+ * C192 — true when the actor asked for `mode=tema` but the expansion
+ * mechanism was unavailable; the page shows the discreet fallback notice.
+ */
+ themeUnavailable: boolean
+ /** C192 — true when the expansion actually contributed terms. */
+ themeApplied: boolean
}
export const loadSpeechAcervoPageData = async (
payload: Payload,
user: CampaignUser,
searchParams: Promise | SpeechListSearchParams,
+ expandTheme: SpeechThemeExpansionResolver = expandSpeechSearchTheme,
): Promise => {
const rawSearchParams = await searchParams
const canonicalUrl = resolveSpeechListUrl(rawSearchParams)
const state = canonicalUrl.state
+ // C192 — only expand for an actor who may read the catalog (the `find` below
+ // is still the final, fail-closed barrier) and only with a query.
+ const themeRequested = state.mode === 'tema' && Boolean(state.q)
+ let themeTerms: readonly string[] = []
+ let themeUnavailable = false
+ if (themeRequested && canReadSpeechCatalog(user.role)) {
+ const expansion = await expandTheme(state.q ?? '')
+ if (expansion) themeTerms = expansion.terms
+ else themeUnavailable = true
+ }
+
// C174 (option B) — a speech also shows up when one of its cuts matches the
// term by title/description, even if the speech text itself does not.
const originSpeechIds = state.q ? await loadSpeechCutOriginSpeechIds(payload, user, state.q) : []
@@ -176,7 +200,7 @@ export const loadSpeechAcervoPageData = async (
limit: speechPageSize,
page: state.page,
sort: '-speechAt',
- where: buildSpeechListWhereIncludingCutOrigins(state, originSpeechIds),
+ where: buildSpeechListWhereIncludingCutOrigins(state, originSpeechIds, themeTerms),
// C174 — the row only needs its normalized text to tell whether it matched
// the term itself (option B); the unsearched list does not pay for it.
select: state.q ? { ...speechListSelect, searchText: true } : speechListSelect,
@@ -210,6 +234,7 @@ export const loadSpeechAcervoPageData = async (
query: state.q,
municipalityLabels,
cuts: cutsBySpeech.get(speech.id) ?? [],
+ themeTerms,
}),
),
state: resolvedUrl.state,
@@ -217,6 +242,8 @@ export const loadSpeechAcervoPageData = async (
totalDocs: result.totalDocs,
totalPages: result.totalPages,
filterOptions,
+ themeUnavailable,
+ themeApplied: themeTerms.length > 0,
}
}
diff --git a/src/utilities/speech/speechViewModels.ts b/src/utilities/speech/speechViewModels.ts
index f5d9e22e..7d060830 100644
--- a/src/utilities/speech/speechViewModels.ts
+++ b/src/utilities/speech/speechViewModels.ts
@@ -17,7 +17,11 @@ import {
type SpeechHighlightPart,
} from '@/lib/speechHighlight'
import { speechPosterHref, speechPosterTarget } from '@/lib/speechPoster'
-import { normalizeForSearch, speechMatchesSearchQuery } from '@/lib/speechSearch'
+import {
+ normalizeForSearch,
+ speechMatchesSearchQuery,
+ speechMatchesSearchTerm,
+} from '@/lib/speechSearch'
import {
correctedExcerptOffsetSeconds,
excerptOffsetSeconds,
@@ -55,7 +59,7 @@ export type SpeechListRecord = {
searchText?: string | null
}
-type SpeechListMatchKind = 'segment' | 'keyword' | 'fallback'
+type SpeechListMatchKind = 'segment' | 'keyword' | 'theme' | 'fallback'
export type SpeechListItemViewModel = {
id: number
@@ -89,6 +93,12 @@ export type SpeechListItemViewModel = {
* the term; the card then swaps the excerpt for the honest origin note.
*/
matchedTextSearch: boolean
+ /**
+ * C192 — the expanded theme term that matched the speech text/keywords, or
+ * null when the search was literal (or the expansion did not surface this
+ * row). The card uses it to label the result and to explain why it appeared.
+ */
+ themeMatchTerm: string | null
}
export type SpeechDetailSegmentViewModel = {
@@ -185,6 +195,41 @@ const pickMatchingSegment = (
})
}
+/**
+ * C192 — the first expanded theme term that actually surfaced this speech. The
+ * gate is the `speechMatchesSearchTerm` mirror (the same predicate the `where`
+ * runs), so the card never claims a theme the search did not use. The evidence
+ * is the passage that carries the term, or the official keyword when that is
+ * what matched. Returns undefined when no theme term applies to this row.
+ */
+const pickThemeMatch = (
+ speech: SpeechListRecord,
+ segments: readonly SpeechSegmentRecord[],
+ themeTerms: readonly string[],
+): { term: string; segment?: SpeechSegmentRecord; keyword?: string } | undefined => {
+ for (const term of themeTerms) {
+ const trimmed = term.trim()
+ const normalized = normalizeForSearch(trimmed)
+ if (!normalized || !speechMatchesSearchTerm(speech, trimmed)) continue
+
+ if (normalizeForSearch(speech.searchText ?? '').includes(normalized)) {
+ const segment =
+ segments.find((item) => normalizeForSearch(item.text).includes(normalized)) ??
+ segments.find((item) => {
+ const text = normalizeForSearch(item.text)
+ return speechSearchTerms(trimmed).some((word) => text.includes(word))
+ }) ??
+ segments[0]
+ return { term: trimmed, segment }
+ }
+
+ const lowered = trimmed.toLowerCase()
+ const keyword = (speech.keywords ?? []).find((item) => item.toLowerCase().includes(lowered))
+ if (keyword) return { term: trimmed, keyword }
+ }
+ return undefined
+}
+
export const buildWatchHref = (
speechId: number,
segment: SpeechSegmentRecord | undefined,
@@ -216,6 +261,7 @@ export const toSpeechListItemViewModel = ({
query,
municipalityLabels,
cuts = [],
+ themeTerms = [],
}: {
speech: SpeechListRecord
segments: readonly SpeechSegmentRecord[]
@@ -223,6 +269,8 @@ export const toSpeechListItemViewModel = ({
municipalityLabels: ReadonlyMap
/** C174 — the cuts of this speech, nested in the result card. */
cuts?: SpeechCuts
+ /** C192 — expanded theme terms; empty in the literal search. */
+ themeTerms?: readonly string[]
}): SpeechListItemViewModel => {
const matchedSegment = pickMatchingSegment(segments, query)
const q = query?.trim()
@@ -232,8 +280,25 @@ export const toSpeechListItemViewModel = ({
Boolean(normalizedQuery) &&
(speech.keywords ?? []).some((keyword) => normalizeForSearch(keyword).includes(normalizedQuery))
+ // C192 — the theme evidence wins the excerpt so the card's "Por que apareceu"
+ // block shows the passage that actually matched, even when the speech also
+ // contains the literal query.
+ const themeMatch = pickThemeMatch(speech, segments, themeTerms)
+
const excerptSource =
- matchedSegment?.text ?? segments[0]?.text ?? speech.summary ?? speech.officialTranscript ?? ''
+ themeMatch?.segment?.text ??
+ themeMatch?.keyword ??
+ matchedSegment?.text ??
+ segments[0]?.text ??
+ speech.summary ??
+ speech.officialTranscript ??
+ ''
+
+ // C192 — the theme passage highlights the whole phrase as one band (the
+ // per-term split would drop the "à" and break it into pieces).
+ const excerpt = themeMatch
+ ? buildHighlightedExcerpt(excerptSource, themeMatch.term, { phrase: true })
+ : buildHighlightedExcerpt(excerptSource, q ?? '')
return {
id: speech.id,
@@ -241,8 +306,14 @@ export const toSpeechListItemViewModel = ({
type: speech.type ?? null,
durationLabel: formatSpeechDuration(speech.durationSeconds),
presidingOfficer: speech.presidingOfficer ?? null,
- excerpt: buildHighlightedExcerpt(excerptSource, q ?? ''),
- matchKind: matchedSegment ? 'segment' : keywordMatch ? 'keyword' : 'fallback',
+ excerpt,
+ matchKind: matchedSegment
+ ? 'segment'
+ : keywordMatch
+ ? 'keyword'
+ : themeMatch
+ ? 'theme'
+ : 'fallback',
topics: topicViewModels(speech),
scopes: scopeViewModels(speech),
keywords: speech.keywords ?? [],
@@ -252,6 +323,7 @@ export const toSpeechListItemViewModel = ({
officialTextUrl: speech.officialTextUrl ?? null,
cuts: [...cuts],
matchedTextSearch: speechMatchesSearchQuery(speech, query),
+ themeMatchTerm: themeMatch?.term ?? null,
}
}
diff --git a/tests/e2e/campaignSpeechAcervo.e2e.spec.ts b/tests/e2e/campaignSpeechAcervo.e2e.spec.ts
index b2b30346..0b0d0542 100644
--- a/tests/e2e/campaignSpeechAcervo.e2e.spec.ts
+++ b/tests/e2e/campaignSpeechAcervo.e2e.spec.ts
@@ -335,6 +335,43 @@ test.describe('communication vertical (C154/C162)', () => {
expect(filteredHtml).toContain('Limpar busca e filtros')
})
+ test('theme mode degrades honestly to the exact search without the key (C192)', async ({
+ campaign,
+ campaignRequest,
+ }) => {
+ const marker = campaign.fixtures.value('temadeg')
+ await createSpeech(campaign, { marker })
+
+ const user = await campaign.fixtures.createCampaignUser('communicator')
+ const request = await campaignRequest(user, user.password)
+
+ // The e2e environment blanks DEEPSEEK_API_KEY (playwright.config.ts), so the
+ // expansion is unavailable and the page must fall back with the notice.
+ const themed = await request.get(`/campanha/comunicacao/acervo?q=${marker}&mode=tema`)
+ expect(themed.status()).toBe(200)
+ const themedHtml = rendered(await themed.text())
+ expect(themedHtml).toContain('Modo de busca')
+ expect(themedHtml).toContain('Termo exato')
+ expect(themedHtml).toContain('Por tema')
+ expect(themedHtml).toContain('data-testid="speech-theme-fallback"')
+ expect(themedHtml).toContain('A busca por tema está indisponível agora.')
+ expect(themedHtml).toContain('Tentar por tema novamente')
+ expect(themedHtml).toContain('Resultados por termo exato')
+ expect(themedHtml).toContain('data-testid="speech-theme-fallback"')
+ // The exact results still render and keep the highlighted term.
+ expect(themedHtml).toContain(marker)
+ expect(themedHtml).toContain(' {
loadSpeechDetailPageData(payload, communicator, 999_999_999),
).rejects.toBeInstanceOf(SpeechNotFoundError)
})
+
+ it('finds a speech by expanded theme terms and explains the match (C192)', async () => {
+ const runId = randomUUID().slice(0, 8)
+ const marker = `tema${runId}`
+ const id = await createSpeech({
+ segments: [
+ {
+ startSeconds: 0,
+ endSeconds: 3,
+ text: `Garantir o atendimento universal ${marker} na rede pública`,
+ },
+ ],
+ })
+
+ const { coordinator } = await createUsers()
+ const expansionCalls: string[] = []
+ const data = await loadSpeechAcervoPageData(
+ payload,
+ coordinator,
+ { q: 'defesa do SUS', mode: 'tema' },
+ async (theme) => {
+ expansionCalls.push(theme)
+ return { terms: [`atendimento universal ${marker}`] }
+ },
+ )
+
+ expect(expansionCalls).toEqual(['defesa do SUS'])
+ expect(data.themeUnavailable).toBe(false)
+ expect(data.themeApplied).toBe(true)
+ const row = data.rows.find((item) => item.id === id)
+ expect(row?.matchKind).toBe('theme')
+ expect(row?.themeMatchTerm).toBe(`atendimento universal ${marker}`)
+ expect(row?.matchedTextSearch).toBe(false)
+ expect(row?.excerpt.parts.some((part) => part.highlighted)).toBe(true)
+ })
+
+ it('degrades to the literal search when the expansion is unavailable (C192)', async () => {
+ const runId = randomUUID().slice(0, 8)
+ const marker = `literal${runId}`
+ const id = await createSpeech({
+ segments: [{ startSeconds: 0, endSeconds: 3, text: `A defesa do SUS ${marker} no plenário` }],
+ })
+
+ const { coordinator } = await createUsers()
+ const data = await loadSpeechAcervoPageData(
+ payload,
+ coordinator,
+ { q: `defesa do SUS ${marker}`, mode: 'tema' },
+ async () => null,
+ )
+
+ expect(data.themeUnavailable).toBe(true)
+ expect(data.themeApplied).toBe(false)
+ const row = data.rows.find((item) => item.id === id)
+ expect(row?.themeMatchTerm).toBeNull()
+ expect(row?.matchedTextSearch).toBe(true)
+ })
+
+ it('never expands for an actor outside the catalog gate (C192)', async () => {
+ const { advisor } = await createUsers()
+ let called = false
+ await expect(
+ loadSpeechAcervoPageData(payload, advisor, { q: 'SUS', mode: 'tema' }, async () => {
+ called = true
+ return { terms: ['saúde'] }
+ }),
+ ).rejects.toThrow(/permissão/i)
+ expect(called).toBe(false)
+ })
})
diff --git a/tests/unit/expandSpeechSearchTheme.unit.spec.ts b/tests/unit/expandSpeechSearchTheme.unit.spec.ts
new file mode 100644
index 00000000..34006066
--- /dev/null
+++ b/tests/unit/expandSpeechSearchTheme.unit.spec.ts
@@ -0,0 +1,69 @@
+// @vitest-environment node
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const { generateObjectMock, deepSeekMock } = vi.hoisted(() => ({
+ generateObjectMock: vi.fn(),
+ deepSeekMock: vi.fn(() => 'mock-model'),
+}))
+
+vi.mock('ai', () => ({ generateObject: generateObjectMock }))
+vi.mock('@ai-sdk/deepseek', () => ({ deepSeek: deepSeekMock }))
+
+import { expandSpeechSearchTheme } from '@/utilities/ai/expandSpeechSearchTheme'
+
+beforeEach(() => {
+ process.env.DEEPSEEK_API_KEY = 'test-deepseek-key'
+ generateObjectMock.mockReset()
+ deepSeekMock.mockClear()
+})
+
+afterEach(() => {
+ delete process.env.DEEPSEEK_API_KEY
+})
+
+describe('expandSpeechSearchTheme (C192)', () => {
+ it('returns the sanitized terms the model produced', async () => {
+ generateObjectMock.mockResolvedValue({
+ object: { terms: ['SUS%', 'saúde pública', 'sus', 'ab'] },
+ })
+
+ await expect(expandSpeechSearchTheme('defesa do SUS')).resolves.toEqual({
+ terms: ['SUS', 'saúde pública'],
+ })
+ })
+
+ it('honra a lista vazia como resposta legítima (não é indisponibilidade)', async () => {
+ generateObjectMock.mockResolvedValue({ object: { terms: [] } })
+
+ await expect(expandSpeechSearchTheme('tema qualquer')).resolves.toEqual({ terms: [] })
+ })
+
+ it('curto-circuita sem chave sem chamar o provedor', async () => {
+ delete process.env.DEEPSEEK_API_KEY
+
+ await expect(expandSpeechSearchTheme('SUS')).resolves.toBeNull()
+ expect(generateObjectMock).not.toHaveBeenCalled()
+ })
+
+ it('curto-circuita um tema vazio', async () => {
+ await expect(expandSpeechSearchTheme(' ')).resolves.toBeNull()
+ expect(generateObjectMock).not.toHaveBeenCalled()
+ })
+
+ it('degrada para null em erro do provedor — nunca lança', async () => {
+ generateObjectMock.mockRejectedValue(new Error('provider down'))
+
+ await expect(expandSpeechSearchTheme('SUS')).resolves.toBeNull()
+ })
+
+ it('envia o tema e um abortSignal limitado ao modelo', async () => {
+ generateObjectMock.mockResolvedValue({ object: { terms: ['SUS'] } })
+
+ await expandSpeechSearchTheme('defesa do SUS')
+
+ const call = generateObjectMock.mock.calls[0]![0] as { prompt: string; abortSignal: unknown }
+ expect(call.prompt).toBe('defesa do SUS')
+ expect(call.abortSignal).toBeInstanceOf(AbortSignal)
+ })
+})
diff --git a/tests/unit/speechHighlight.unit.spec.ts b/tests/unit/speechHighlight.unit.spec.ts
index 90538fc3..30af789d 100644
--- a/tests/unit/speechHighlight.unit.spec.ts
+++ b/tests/unit/speechHighlight.unit.spec.ts
@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest'
import {
buildHighlightedExcerpt,
findHighlightRanges,
+ findPhraseRanges,
matchesSearchTerms,
splitHighlightedParts,
} from '@/lib/speechHighlight'
@@ -42,6 +43,32 @@ describe('findHighlightRanges', () => {
})
})
+describe('findPhraseRanges (C192)', () => {
+ it('highlights the whole phrase as one continuous range, keeping the accents', () => {
+ const text = 'Defendemos o atendimento público e acesso universal à saúde para todos'
+ const ranges = findPhraseRanges(text, 'acesso universal à saúde')
+
+ expect(ranges).toHaveLength(1)
+ expect(text.slice(ranges[0]!.start, ranges[0]!.end)).toBe('acesso universal à saúde')
+ })
+
+ it('finds overlapping occurrences of the same phrase', () => {
+ expect(findPhraseRanges('ana ana', 'ana')).toEqual([
+ { start: 0, end: 3 },
+ { start: 4, end: 7 },
+ ])
+ })
+
+ it('falls back to the per-term ranges when the phrase is not contiguous', () => {
+ const ranges = findPhraseRanges('saúde pública e muito acesso', 'acesso universal')
+ expect(ranges).toEqual([{ start: 22, end: 28 }])
+ })
+
+ it('returns nothing for an empty phrase', () => {
+ expect(findPhraseRanges('texto', '')).toEqual([])
+ })
+})
+
describe('matchesSearchTerms', () => {
it('requires every term, in any order', () => {
expect(matchesSearchTerms('A defesa do SUS e da saúde', 'saude sus')).toBe(true)
diff --git a/tests/unit/speechListFilters.unit.spec.ts b/tests/unit/speechListFilters.unit.spec.ts
index 44736262..d9673779 100644
--- a/tests/unit/speechListFilters.unit.spec.ts
+++ b/tests/unit/speechListFilters.unit.spec.ts
@@ -122,3 +122,61 @@ describe('buildSpeechListWhereIncludingCutOrigins (C174)', () => {
expect(buildSpeechListWhereIncludingCutOrigins(state, [])).toEqual(buildSpeechListWhere(state))
})
})
+
+describe('buildSpeechListWhere theme expansion (C192)', () => {
+ it('ORs the query with every expanded theme term', () => {
+ const where = buildSpeechListWhere(parseSpeechListParams({ q: 'defesa do SUS' }), [
+ 'saúde pública',
+ 'SUS',
+ ])
+
+ expect(where).toEqual({
+ and: [
+ {
+ or: [
+ { searchText: { like: 'defesa do sus' } },
+ { keywords: { contains: 'defesa do SUS' } },
+ { searchText: { like: 'saude publica' } },
+ { keywords: { contains: 'saúde pública' } },
+ { searchText: { like: 'sus' } },
+ { keywords: { contains: 'SUS' } },
+ ],
+ },
+ ],
+ })
+ })
+
+ it('dedupes a term that repeats the query', () => {
+ expect(buildSpeechListWhere(parseSpeechListParams({ q: 'SUS' }), ['SUS'])).toEqual({
+ and: [{ or: [{ searchText: { like: 'sus' } }, { keywords: { contains: 'SUS' } }] }],
+ })
+ })
+
+ it('keeps the facets AND-ed and the cut origins OR-ed alongside the expansion', () => {
+ expect(
+ buildSpeechListWhereIncludingCutOrigins(
+ parseSpeechListParams({ q: 'reforma', topic: ['saude'] }),
+ [7],
+ ['saúde'],
+ ),
+ ).toEqual({
+ and: [
+ { topics: { in: ['saude'] } },
+ {
+ or: [
+ { searchText: { like: 'reforma' } },
+ { keywords: { contains: 'reforma' } },
+ { searchText: { like: 'saude' } },
+ { keywords: { contains: 'saúde' } },
+ { id: { in: [7] } },
+ ],
+ },
+ ],
+ })
+ })
+
+ it('stays byte-identical to today without theme terms', () => {
+ const state = parseSpeechListParams({ q: 'reforma' })
+ expect(buildSpeechListWhere(state, [])).toEqual(buildSpeechListWhere(state))
+ })
+})
diff --git a/tests/unit/speechListUrl.unit.spec.ts b/tests/unit/speechListUrl.unit.spec.ts
index 8acc197f..e34a45cd 100644
--- a/tests/unit/speechListUrl.unit.spec.ts
+++ b/tests/unit/speechListUrl.unit.spec.ts
@@ -67,6 +67,12 @@ describe('parseSpeechListParams', () => {
expect(state.topics).toBeUndefined()
expect(state.durations).toBeUndefined()
})
+
+ it('parses the theme mode and ignores any other value (C192)', () => {
+ expect(parseSpeechListParams({ q: 'SUS', mode: 'tema' }).mode).toBe('tema')
+ expect(parseSpeechListParams({ q: 'SUS', mode: 'termo' }).mode).toBeUndefined()
+ expect(parseSpeechListParams({ q: 'SUS', mode: 'exato' }).mode).toBeUndefined()
+ })
})
describe('serializeCanonicalSpeechListSearchParams', () => {
@@ -84,6 +90,18 @@ describe('serializeCanonicalSpeechListSearchParams', () => {
expect(params.getAll('topic')).toEqual(['saude', 'educacao'])
expect(params.getAll('duration')).toEqual(['curta'])
})
+
+ it('serializes mode=tema only alongside a query (C192)', () => {
+ expect(
+ serializeCanonicalSpeechListSearchParams(
+ parseSpeechListParams({ q: 'SUS', mode: 'tema' }),
+ ).toString(),
+ ).toBe('q=SUS&mode=tema')
+ // A theme without a query canonicalizes away.
+ expect(
+ serializeCanonicalSpeechListSearchParams(parseSpeechListParams({ mode: 'tema' })).toString(),
+ ).toBe('')
+ })
})
describe('buildSpeechListHref', () => {
@@ -93,6 +111,15 @@ describe('buildSpeechListHref', () => {
)
expect(buildSpeechListHref(parseSpeechListParams({}), 1)).toBe('/campanha/comunicacao/acervo')
})
+
+ it('keeps the exact-search deep link byte-identical (C192)', () => {
+ expect(buildSpeechListHref(parseSpeechListParams({ q: 'SUS' }), 1)).toBe(
+ '/campanha/comunicacao/acervo?q=SUS',
+ )
+ expect(buildSpeechListHref(parseSpeechListParams({ q: 'SUS', mode: 'tema' }), 1)).toBe(
+ '/campanha/comunicacao/acervo?q=SUS&mode=tema',
+ )
+ })
})
describe('resolveSpeechListUrl', () => {
@@ -107,6 +134,15 @@ describe('resolveSpeechListUrl', () => {
expect(resolved.state.page).toBe(2)
expect(resolved.redirectHref).toContain('page=2')
})
+
+ it('canonicalizes a theme mode without a query into a redirect (C192)', () => {
+ const withQuery = resolveSpeechListUrl({ q: 'SUS', mode: 'tema' })
+ expect(withQuery.state.mode).toBe('tema')
+ expect(withQuery.redirectHref).toBeUndefined()
+
+ const empty = resolveSpeechListUrl({ mode: 'tema' })
+ expect(empty.redirectHref).toBe('/campanha/comunicacao/acervo')
+ })
})
describe('buildSpeechFiltersKey', () => {
diff --git a/tests/unit/speechOmnibox.unit.spec.ts b/tests/unit/speechOmnibox.unit.spec.ts
index b8ba6e84..3dd9ac31 100644
--- a/tests/unit/speechOmnibox.unit.spec.ts
+++ b/tests/unit/speechOmnibox.unit.spec.ts
@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest'
import { parseSpeechListParams, type SpeechListState } from '@/utilities/speech/speechListUrl'
import {
applySpeechOmniboxSuggestion,
+ applySpeechSearchMode,
buildSpeechOmniboxChips,
clearSpeechOmnibox,
removeSpeechOmniboxChip,
@@ -96,9 +97,34 @@ describe('removeSpeechOmniboxChip', () => {
expect(emptied.state.topics).toBeUndefined()
})
- it('removes the search chip', () => {
- const action = removeSpeechOmniboxChip({ state: state({ q: 'SUS' }), chipId: 'q' })
+ it('removes the search chip and the theme mode with it (C192)', () => {
+ const action = removeSpeechOmniboxChip({
+ state: state({ q: 'SUS', mode: 'tema' }),
+ chipId: 'q',
+ })
expect(action.state.q).toBeUndefined()
+ expect(action.state.mode).toBeUndefined()
+ })
+})
+
+describe('applySpeechSearchMode (C192)', () => {
+ it('sets tema only with a query and resets the page', () => {
+ expect(applySpeechSearchMode({ state: state({ q: 'SUS', page: '4' }), mode: 'tema' })).toEqual({
+ kind: 'url',
+ state: { page: 1, q: 'SUS', mode: 'tema' },
+ })
+
+ expect(applySpeechSearchMode({ state: state({ page: '4' }), mode: 'tema' }).state.mode).toBe(
+ undefined,
+ )
+ })
+
+ it('clears the mode back to the exact search', () => {
+ const action = applySpeechSearchMode({
+ state: state({ q: 'SUS', mode: 'tema' }),
+ mode: 'termo',
+ })
+ expect(action.state.mode).toBeUndefined()
})
})
diff --git a/tests/unit/speechSearch.unit.spec.ts b/tests/unit/speechSearch.unit.spec.ts
index c9ea9615..91bff36e 100644
--- a/tests/unit/speechSearch.unit.spec.ts
+++ b/tests/unit/speechSearch.unit.spec.ts
@@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest'
import {
normalizeForSearch,
speechMatchesSearchQuery,
+ speechMatchesSearchTerm,
uniqueByNormalizedForm,
} from '@/lib/speechSearch'
@@ -47,3 +48,18 @@ describe('speechMatchesSearchQuery', () => {
expect(speechMatchesSearchQuery(speech, ' ')).toBe(true)
})
})
+
+describe('speechMatchesSearchTerm (C192)', () => {
+ it('mirrors a single textual where branch', () => {
+ const speech = { searchText: 'a saude publica baiana', keywords: ['Farmácia Popular'] }
+ expect(speechMatchesSearchTerm(speech, 'SAÚDE Pública')).toBe(true)
+ expect(speechMatchesSearchTerm(speech, 'FARMÁCIA')).toBe(true)
+ expect(speechMatchesSearchTerm(speech, 'educação')).toBe(false)
+ })
+
+ it('never matches an empty term', () => {
+ const speech = { searchText: 'a saude publica', keywords: ['SUS'] }
+ expect(speechMatchesSearchTerm(speech, undefined)).toBe(false)
+ expect(speechMatchesSearchTerm(speech, ' ')).toBe(false)
+ })
+})
diff --git a/tests/unit/speechThemeTerms.unit.spec.ts b/tests/unit/speechThemeTerms.unit.spec.ts
new file mode 100644
index 00000000..3434ffbb
--- /dev/null
+++ b/tests/unit/speechThemeTerms.unit.spec.ts
@@ -0,0 +1,32 @@
+// @vitest-environment node
+
+import { describe, expect, it } from 'vitest'
+
+import { MAX_SPEECH_THEME_TERMS, normalizeSpeechThemeTerms } from '@/lib/speechThemeTerms'
+
+describe('normalizeSpeechThemeTerms (C192)', () => {
+ it('removes LIKE wildcards so the expansion cannot widen the pattern', () => {
+ expect(normalizeSpeechThemeTerms(['saúde%', 'a_b', 'c\\d'])).toEqual(['saúde', 'a b', 'c d'])
+ })
+
+ it('drops empty and too-short terms', () => {
+ expect(normalizeSpeechThemeTerms(['', ' ', 'ab', 'SUS', 'de'])).toEqual(['SUS'])
+ })
+
+ it('dedupes by normalized form keeping the first spelling', () => {
+ expect(normalizeSpeechThemeTerms(['Saúde Pública', 'saude publica', 'SUS'])).toEqual([
+ 'Saúde Pública',
+ 'SUS',
+ ])
+ })
+
+ it('caps the list length', () => {
+ const values = Array.from({ length: 20 }, (_, index) => `termo ${index}`)
+ expect(normalizeSpeechThemeTerms(values)).toHaveLength(MAX_SPEECH_THEME_TERMS)
+ })
+
+ it('truncates a single term to the max length', () => {
+ const term = 'x'.repeat(90)
+ expect(normalizeSpeechThemeTerms([term])[0]).toHaveLength(60)
+ })
+})
diff --git a/tests/unit/speechViewModels.unit.spec.ts b/tests/unit/speechViewModels.unit.spec.ts
index e5cb9d57..35c53354 100644
--- a/tests/unit/speechViewModels.unit.spec.ts
+++ b/tests/unit/speechViewModels.unit.spec.ts
@@ -64,3 +64,115 @@ describe('toSpeechListItemViewModel thumbnail (C182 — frame of the speech)', (
expect(viewModel({ durationSeconds: 252, eventId: 67091 }).thumbnailUrl).toBeNull()
})
})
+
+describe('toSpeechListItemViewModel theme match (C192)', () => {
+ const segment = (text: string) => ({ startSeconds: 0, endSeconds: 3, text })
+ const themeRow = ({
+ text,
+ query,
+ themeTerms,
+ keywords = [],
+ searchText,
+ }: {
+ text: string
+ query?: string
+ themeTerms: string[]
+ keywords?: string[]
+ searchText?: string
+ }) =>
+ toSpeechListItemViewModel({
+ speech: { id: 1, speechAt: '2026-08-11T18:48', keywords, searchText },
+ segments: [segment(text)],
+ query,
+ municipalityLabels: new Map(),
+ themeTerms,
+ })
+
+ it('surfaces the theme passage with the expanded term highlighted', () => {
+ const row = themeRow({
+ text: 'Defendemos o atendimento público e acesso universal à saúde',
+ searchText: 'defendemos o atendimento publico e acesso universal a saude',
+ query: 'defesa do SUS',
+ themeTerms: ['acesso universal'],
+ })
+
+ expect(row.matchKind).toBe('theme')
+ expect(row.themeMatchTerm).toBe('acesso universal')
+ expect(row.matchedTextSearch).toBe(false)
+ expect(row.excerpt.parts.some((part) => part.highlighted)).toBe(true)
+ })
+
+ it('keeps the theme term when the speech also matches the literal query', () => {
+ const row = themeRow({
+ text: 'A defesa do SUS e da saúde pública baiana',
+ searchText: 'a defesa do sus e da saude publica baiana',
+ query: 'SUS',
+ themeTerms: ['saúde pública'],
+ })
+
+ expect(row.matchKind).toBe('segment')
+ expect(row.themeMatchTerm).toBe('saúde pública')
+ expect(row.matchedTextSearch).toBe(true)
+ })
+
+ it('matches a keyword as theme evidence and uses it as the excerpt', () => {
+ const row = themeRow({
+ text: 'Uma fala sobre outro assunto',
+ query: 'defesa do SUS',
+ themeTerms: ['Farmácia Popular'],
+ keywords: ['Farmácia Popular'],
+ })
+
+ expect(row.matchKind).toBe('theme')
+ expect(row.themeMatchTerm).toBe('Farmácia Popular')
+ const excerptText = row.excerpt.parts.map((part) => part.text).join('')
+ expect(excerptText).toContain('Farmácia Popular')
+ expect(row.excerpt.parts.some((part) => part.highlighted)).toBe(true)
+ })
+
+ it('does not claim a theme the where never used (word-only coincidence)', () => {
+ const row = themeRow({
+ text: 'O atendimento público é prioridade',
+ searchText: 'o atendimento publico e prioridade',
+ query: 'defesa do SUS',
+ themeTerms: ['atendimento universal'],
+ })
+
+ expect(row.themeMatchTerm).toBeNull()
+ expect(row.matchKind).toBe('fallback')
+ })
+
+ it('stays literal without theme terms or when none matches', () => {
+ expect(
+ themeRow({ text: 'A defesa do SUS', query: 'SUS', themeTerms: [] }).themeMatchTerm,
+ ).toBeNull()
+ expect(
+ themeRow({ text: 'A defesa do SUS', query: 'SUS', themeTerms: ['educação'] }).themeMatchTerm,
+ ).toBeNull()
+ })
+
+ it('never claims a theme term the where mirror did not match (C192)', () => {
+ // "saúde pública" never appears contiguously in the search text, so the
+ // mirror rejects it and only the term that really matched is claimed.
+ expect(
+ themeRow({
+ text: 'Saúde para todos e a rede pública de atendimento',
+ searchText: 'saude para todos e a rede publica de atendimento',
+ query: 'defesa do SUS',
+ themeTerms: ['saúde pública', 'atendimento'],
+ }).themeMatchTerm,
+ ).toBe('atendimento')
+ })
+
+ it('falls back to keywords as theme evidence when the text does not match', () => {
+ const row = themeRow({
+ text: 'Uma fala sobre outro assunto',
+ query: 'defesa do SUS',
+ themeTerms: ['Farmácia Popular'],
+ keywords: ['Farmácia Popular'],
+ })
+
+ expect(row.themeMatchTerm).toBe('Farmácia Popular')
+ expect(row.excerpt.parts.some((part) => part.highlighted)).toBe(true)
+ })
+})
+ {hasChips ?
- ) : null}
+ ) : (
+ <>
+ {hasChips ? {chips}
: }
+
+
+
+ Abrir Diário Oficial
+
+ ) : null}
+
{chips}
: null}
-
-
- {speech.officialTextUrl ? (
-
-
- Abrir Diário Oficial
-
- ) : null}
-
+
+
+
+ Abrir Diário Oficial
+
+ ) : null}
+
+
+ )}
{speech.cuts.length ?