mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-20 01:33:05 +00:00
Troca o motor do modo tema (Câmara + internet) de expansão lexical para embeddings (Deep Infra, BAAI/bge-m3), com índice próprio (speechEmbedding), ranking por proximidade em memória, evidência real do trecho mais próximo, vazio honesto por limiar e degradação para a busca literal. Inclui a collection oculta + migration, o CLI pnpm acervo:index (--dry-run/--limit/ --source/--force/--probe), o port do design aprovado e a suíte de testes. Pós-rebase: o snapshot da migration seguinte (20260926_062039_add_archive_photo, do C231 já na main) foi regenerado para incluir speech_embedding — sem ele o próximo migrate:create recriaria a tabela. Closes #1360
282 lines
10 KiB
TypeScript
282 lines
10 KiB
TypeScript
/**
|
|
* Speech acervo URL contract (C154): state, param parse/canonicalize and
|
|
* hrefs, same shape as `peopleListUrl`/`supporterUi` over the shared
|
|
* `campaignListUrl` helpers. Facet enums are exhaustive (selecting every
|
|
* member equals no filter); year/phase/municipality are data-driven and
|
|
* validated structurally.
|
|
*/
|
|
import {
|
|
acervoSortIsDuration,
|
|
parseAcervoSort,
|
|
parseAcervoThemeSort,
|
|
type AcervoSortKey,
|
|
} from '@/lib/acervoListSort'
|
|
import { ACERVO_SOURCE_INTERNET, parseAcervoSource } from '@/lib/acervoSource'
|
|
import { CAMPAIGN_COMMUNICATION_ACERVO } from '@/lib/campaignPaths'
|
|
import { isContactSearchQueryReady } from '@/lib/contactSearchQuery'
|
|
import {
|
|
SPEECH_SCOPES,
|
|
SPEECH_TOPICS,
|
|
type SpeechScope,
|
|
type SpeechTopic,
|
|
} from '@/lib/speechFacets'
|
|
import {
|
|
allParamValues,
|
|
buildListHref,
|
|
firstValue,
|
|
normalizedText,
|
|
parseExhaustiveEnumParam,
|
|
parseMunicipalityValues,
|
|
parseYearValues,
|
|
resolveListUrl,
|
|
strictDecimalInteger,
|
|
type RawSearchParams,
|
|
} from '@/utilities/campaignListUrl'
|
|
|
|
export const speechPageSize = 25
|
|
|
|
/**
|
|
* C192/C229 — search mode of the acervo. `termo` is the literal search
|
|
* (default, never serialized so existing deep links stay byte-identical);
|
|
* `tema` asks the sense engine (C229) for related speeches. 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' },
|
|
{ value: 'media', label: '2 a 5 min' },
|
|
{ value: 'longa', label: 'Mais de 5 min' },
|
|
{ value: 'sem_duracao', label: 'Sem duração' },
|
|
] as const
|
|
|
|
export type SpeechDurationBucket = (typeof SPEECH_DURATION_BUCKETS)[number]['value']
|
|
|
|
export const speechDurationLabels = Object.fromEntries(
|
|
SPEECH_DURATION_BUCKETS.map(({ value, label }) => [value, label]),
|
|
) as Record<SpeechDurationBucket, string>
|
|
|
|
export const speechTopicLabels = Object.fromEntries(
|
|
SPEECH_TOPICS.map(({ value, label }) => [value, label]),
|
|
) as Record<SpeechTopic, string>
|
|
|
|
export const speechScopeLabels = Object.fromEntries(
|
|
SPEECH_SCOPES.map(({ value, label }) => [value, label]),
|
|
) as Record<SpeechScope, string>
|
|
|
|
export type SpeechListState = {
|
|
/**
|
|
* C216 — the web speeches source. Absent means the Câmara source; only the
|
|
* exact `source=internet` value is recognized (fail-closed on the default).
|
|
*/
|
|
source?: 'internet'
|
|
page: number
|
|
q?: string
|
|
mode?: SpeechSearchMode
|
|
years?: number[]
|
|
topics?: SpeechTopic[]
|
|
scopes?: SpeechScope[]
|
|
/** Câmara-only facet: `phase` is ignored (and not serialized) for the web. */
|
|
phases?: string[]
|
|
municipalities?: number[]
|
|
durations?: SpeechDurationBucket[]
|
|
/**
|
|
* C216 — the web list ordering; the Câmara contract has no sort. C229 — in
|
|
* the theme mode the relevance order is the default (`sort` absent) and
|
|
* `recentes` becomes a real state; the exact mode keeps its bytes.
|
|
*/
|
|
sort?: AcervoSortKey
|
|
}
|
|
|
|
/** Server-loaded filter options (years/phases present, cited municipalities). */
|
|
export type SpeechFilterOptions = {
|
|
years: number[]
|
|
phases: string[]
|
|
municipalities: { value: string; label: string }[]
|
|
}
|
|
|
|
type RawSpeechListParams = RawSearchParams
|
|
|
|
const speechListParamNames = [
|
|
// C216 — additive params of the web speeches source; the Câmara URL contract
|
|
// keeps its bytes (they are never serialized without `source=internet`).
|
|
'source',
|
|
'q',
|
|
'mode',
|
|
'year',
|
|
'topic',
|
|
'scope',
|
|
'phase',
|
|
'municipality',
|
|
'duration',
|
|
'sort',
|
|
'page',
|
|
] as const
|
|
|
|
const speechListParamNameSet = new Set<string>(speechListParamNames)
|
|
const speechTopicSet = new Set<string>(SPEECH_TOPICS.map(({ value }) => value))
|
|
const speechScopeSet = new Set<string>(SPEECH_SCOPES.map(({ value }) => value))
|
|
const speechDurationSet = new Set<string>(SPEECH_DURATION_BUCKETS.map(({ value }) => value))
|
|
const MAX_PHASE_LENGTH = 80
|
|
|
|
/** 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 => {
|
|
// C216 — the web source is a dimension of the same contract. Unknown source
|
|
// values fall back to the Câmara (fail-closed); the web source has no Fase
|
|
// facet, so `phase` is ignored there instead of leaking into its canonical URL.
|
|
const isWeb = parseAcervoSource(params) === 'internet'
|
|
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<SpeechTopic>(params.topic, speechTopicSet)
|
|
const scopes = parseExhaustiveEnumParam<SpeechScope>(params.scope, speechScopeSet)
|
|
const phases = isWeb
|
|
? []
|
|
: allParamValues(params.phase).filter((token) => token.length <= MAX_PHASE_LENGTH)
|
|
const municipalities = parseMunicipalityValues(params.municipality)
|
|
const durations = parseExhaustiveEnumParam<SpeechDurationBucket>(
|
|
params.duration,
|
|
speechDurationSet,
|
|
)
|
|
// C229 — the web sort is mode-aware: the theme mode defaults to relevance
|
|
// (`sort` absent) and recognizes `recentes`/`relevancia`; the exact mode
|
|
// keeps the C216 rule (only the duration orders are meaningful).
|
|
const sort = isWeb
|
|
? mode === 'tema'
|
|
? parseAcervoThemeSort(params.sort)
|
|
: parseAcervoSort(params.sort)
|
|
: undefined
|
|
|
|
return {
|
|
...(isWeb ? { source: ACERVO_SOURCE_INTERNET } : {}),
|
|
page: rawPage ?? 1,
|
|
...(q ? { q } : {}),
|
|
...(mode ? { mode } : {}),
|
|
...(years.length ? { years } : {}),
|
|
...(topics.length ? { topics } : {}),
|
|
...(scopes.length ? { scopes } : {}),
|
|
...(phases.length ? { phases } : {}),
|
|
...(municipalities.length ? { municipalities } : {}),
|
|
...(durations.length ? { durations } : {}),
|
|
...(sort ? { sort } : {}),
|
|
}
|
|
}
|
|
|
|
const speechListStateToRawParams = (
|
|
state: SpeechListState,
|
|
page = state.page,
|
|
): RawSpeechListParams => ({
|
|
source: state.source,
|
|
page: String(page),
|
|
q: state.q,
|
|
mode: state.mode,
|
|
year: state.years?.map(String),
|
|
topic: state.topics,
|
|
scope: state.scopes,
|
|
phase: state.phases,
|
|
municipality: state.municipalities?.map(String),
|
|
duration: state.durations,
|
|
sort: state.sort,
|
|
})
|
|
|
|
/** Expects already-canonical state (from parse or a rule-preserving toggle). */
|
|
export const serializeCanonicalSpeechListSearchParams = (
|
|
canonicalState: SpeechListState,
|
|
): URLSearchParams => {
|
|
const params = new URLSearchParams()
|
|
// C216 — `source=internet` always serialized: it is what selects the web
|
|
// source. The Câmara URL keeps its exact bytes (no source, no sort).
|
|
if (canonicalState.source === 'internet') params.set('source', 'internet')
|
|
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)
|
|
for (const phase of canonicalState.phases ?? []) params.append('phase', phase)
|
|
for (const municipality of canonicalState.municipalities ?? []) {
|
|
params.append('municipality', String(municipality))
|
|
}
|
|
for (const duration of canonicalState.durations ?? []) params.append('duration', duration)
|
|
// C216 — `recentes` is the exact-mode default and never serialized; C229 —
|
|
// in the theme mode relevance took that place, so an explicit `recentes` is
|
|
// a real state and serializes. Both rules live on the web source only.
|
|
if (
|
|
canonicalState.source === 'internet' &&
|
|
canonicalState.sort &&
|
|
(canonicalState.mode === 'tema' || acervoSortIsDuration(canonicalState.sort))
|
|
) {
|
|
params.set('sort', canonicalState.sort)
|
|
}
|
|
if (canonicalState.page > 1) params.set('page', String(canonicalState.page))
|
|
return params
|
|
}
|
|
|
|
const buildSpeechListSearchParams = (state: SpeechListState, page = state.page): URLSearchParams =>
|
|
serializeCanonicalSpeechListSearchParams(
|
|
parseSpeechListParams(speechListStateToRawParams(state, page)),
|
|
)
|
|
|
|
export const buildSpeechListHref = (state: SpeechListState, page: number): string =>
|
|
buildListHref(state, buildSpeechListSearchParams, CAMPAIGN_COMMUNICATION_ACERVO, page)
|
|
|
|
export const buildSpeechFiltersKey = (state: SpeechListState): string =>
|
|
buildSpeechListSearchParams(state).toString()
|
|
|
|
/**
|
|
* C216 — Payload sort order of the web list: the default is the publication
|
|
* order (`-speechAt`) and a duration order only lists rows with a measured
|
|
* duration (the `where` gates `durationSeconds exists`; Postgres sorts NULLS
|
|
* FIRST on DESC).
|
|
*/
|
|
export const webSpeechSortOrder = (state: SpeechListState): string => {
|
|
switch (state.sort) {
|
|
case 'duracao_maior':
|
|
return '-durationSeconds'
|
|
case 'duracao_menor':
|
|
return 'durationSeconds'
|
|
default:
|
|
return '-speechAt'
|
|
}
|
|
}
|
|
|
|
/**
|
|
* C216 — whether the actor narrowed the list (query/mode or any facet). The
|
|
* empty state uses it to tell "nothing was ever catalogued" from "the filters
|
|
* hid everything"; `source` and pagination are not filters.
|
|
*/
|
|
export const speechHasActiveFilters = (state: SpeechListState): boolean =>
|
|
Boolean(
|
|
state.q ||
|
|
state.mode ||
|
|
state.years?.length ||
|
|
state.topics?.length ||
|
|
state.scopes?.length ||
|
|
state.phases?.length ||
|
|
state.municipalities?.length ||
|
|
state.durations?.length,
|
|
)
|
|
|
|
export const resolveSpeechListUrl = (
|
|
params: RawSpeechListParams,
|
|
totalPages?: number,
|
|
): {
|
|
state: SpeechListState
|
|
href: string
|
|
redirectHref?: string
|
|
} =>
|
|
resolveListUrl({
|
|
params,
|
|
paramNameSet: speechListParamNameSet,
|
|
parse: parseSpeechListParams,
|
|
buildSearchParams: buildSpeechListSearchParams,
|
|
basePath: CAMPAIGN_COMMUNICATION_ACERVO,
|
|
totalPages,
|
|
})
|