teqo-backup/src/utilities/content/contentPieceCataloging.ts
Francisco Solla 71a27aa4ec feat(C211): Central de Conteúdos interna — envio em lote, link, catalogação e publicação
Envio em lote (1 request raw-body por arquivo, fan-out ≤2, até 50 arquivos) e
adicionar por link (Instagram/YouTube; extração só pela Graph API da conta
própria, senão peça-link) em /campanha/comunicacao/conteudos. Cada peça tem
estado próprio (Processando/Pronto/Falhou + Reprocessar), transcrição/texto e
catalogação automática revisável; publicar/despublicar preserva arquivo, slug
e publishedAt.

- collections contentPiece + contentMedia (upload privado no S3) e migration
  20260923_032714_add_content_piece (slug único gerado no 1º publish,
  sourceUrl única, searchText com índice trigram)
- pipeline reusa C199 (job after() + reaper + retry condicional, transcrição
  DeepInfra, ffmpeg/chunk), o classificador de facetas do acervo e o
  institutionCatalog; curatedFields impede o job de sobrescrever curadoria
- gate único canReadCommunicationCatalog (advisor/leader negados); delete
  só pelo admin; sem Consent novo
- UI portada do design aprovado (lista desktop + cards mobile, diálogo de
  lote com progresso por arquivo, diálogo de link, ficha editável, kill
  switch); nav/chrome/column-picker/manifest atualizados
- instagramFeed expõe mediaUrl; revalidateTag ganha wrapper seguro fora de
  request (fixtures/scripts)
- testes: 2 unit specs, 1 int spec (16 casos) e 7 e2e na vertical
- follow-up de engenharia: #1267 (docs/plans/escala-dry-pos-c211.md)

Closes #1254
2026-09-23 02:06:08 -03:00

266 lines
9.1 KiB
TypeScript

import 'server-only'
import { deepSeek } from '@ai-sdk/deepseek'
import { generateObject } from 'ai'
import type { Payload } from 'payload'
import { z } from 'zod'
import {
CONTENT_PIECE_DESCRIPTION_MAX_LENGTH,
CONTENT_PIECE_INSTITUTION_MAX_LENGTH,
CONTENT_PIECE_TITLE_MAX_LENGTH,
contentPieceTopicLabel,
contentPieceTypeLabels,
type ContentPieceType,
} from '@/lib/contentPiece'
import { institutionCatalog, institutionSpellings } from '@/lib/institutionCatalog'
import { type SpeechTopic } from '@/lib/speechFacets'
import { matchMunicipalityMentions, type SpeechFacetInput } from '@/lib/speechGazetteer'
import { normalizeForSearch } from '@/lib/speechSearch'
import { classifySpeech } from '@/utilities/speech/speechClassifier'
/**
* C211 — the automatic cataloguing of one content piece: the offline gazetteer
* for city/topics, the C153 classifier (gazetteer + validated LLM refinement)
* for the themes and one bounded DeepSeek call for title/description. Every
* step is fail-closed and never throws: a provider outage degrades to the
* deterministic fallback, and the assessoria's edits always win (the job only
* writes fields absent from `curatedFields`).
*/
const SUGGESTION_TIMEOUT_MS = 8000
const MAX_EXCERPT_CHARS = 2000
const MAX_OUTPUT_TOKENS = 500
export type ContentPieceCatalogResult = {
title?: string
description?: string
topics?: SpeechTopic[]
municipalityId?: number | null
institution?: string
source: 'ai' | 'fallback' | 'none'
}
type ContentPieceClassifier = (input: SpeechFacetInput) => Promise<{
facets: { topics: SpeechTopic[] }
}>
type ContentPieceSuggester = (input: {
type: ContentPieceType
currentTitle: string
transcript: string
cityLabel: string | null
topics: readonly SpeechTopic[]
}) => Promise<{ title: string; description: string; source: 'ai' | 'fallback' }>
const suggestionSchema = z.object({
title: z
.string()
.describe('Título curto em português (no máximo 120 caracteres), sem aspas nem prefixos.'),
description: z
.string()
.describe(
'Descrição factual em português (no máximo 600 caracteres) do que a peça mostra, sem inventar fatos.',
),
})
const SYSTEM_PROMPT =
'Você cataloga peças de campanha do deputado federal Jorge Solla (PT-BA) para a Central de Conteúdos da campanha. ' +
'Receberá o tipo da peça e a transcrição automática (ASR) do material, que pode ter ruído. ' +
'Escreva um título curto e concreto (o assunto da peça, não o nome do deputado) e uma descrição de uma a duas ' +
'frases, em português do Brasil, adequadas para apresentar o material a quem vai compartilhar no WhatsApp. ' +
'Use apenas o que está na transcrição; nunca invente números, acordos, cidades ou citações.'
const clip = (value: string, maximum: number): string => value.trim().slice(0, maximum).trim()
const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
/** Deterministic fallback: never empty, never invents a fact. */
export const buildContentPieceFallbackMetadata = ({
type,
currentTitle,
cityLabel,
topics,
}: {
type: ContentPieceType
currentTitle: string
cityLabel: string | null
topics: readonly SpeechTopic[]
}): { title: string; description: string; source: 'fallback' } => {
const typeLabel = contentPieceTypeLabels[type].toLowerCase()
const topicLabels = topics.slice(0, 3).map(contentPieceTopicLabel)
const parts = [
`${contentPieceTypeLabels[type]} da campanha de Jorge Solla 1313`,
cityLabel ? `em ${cityLabel}` : null,
topicLabels.length > 0 ? `sobre ${topicLabels.join(', ')}` : null,
].filter((part): part is string => part !== null)
return {
title: clip(currentTitle, CONTENT_PIECE_TITLE_MAX_LENGTH) || `Peça de ${typeLabel}`,
description: clip(`${parts.join(' ')}.`, CONTENT_PIECE_DESCRIPTION_MAX_LENGTH),
source: 'fallback',
}
}
/**
* One-shot AI title/description for the piece, on the same DeepSeek path as
* the acervo AI (C167): never throws, never blocks the job. Missing key, empty
* excerpt, timeout or unusable output all resolve to the deterministic
* fallback.
*/
const suggestContentPieceMetadata: ContentPieceSuggester = async ({
type,
currentTitle,
transcript,
cityLabel,
topics,
}) => {
const fallback = buildContentPieceFallbackMetadata({ type, currentTitle, cityLabel, topics })
const excerpt = transcript.trim().slice(0, MAX_EXCERPT_CHARS)
if (!excerpt || !process.env.DEEPSEEK_API_KEY) return fallback
try {
const { object } = await generateObject({
model: deepSeek('deepseek-flash'),
schema: suggestionSchema,
system: SYSTEM_PROMPT,
prompt: [
`Tipo: ${contentPieceTypeLabels[type]}`,
`Título atual: ${currentTitle}`,
cityLabel ? `Cidade: ${cityLabel}` : null,
`Transcrição (ASR): "${excerpt}"`,
]
.filter((line): line is string => line !== null)
.join('\n'),
temperature: 0.3,
maxOutputTokens: MAX_OUTPUT_TOKENS,
abortSignal: AbortSignal.timeout(SUGGESTION_TIMEOUT_MS),
})
const title = clip(object.title, CONTENT_PIECE_TITLE_MAX_LENGTH)
const description = clip(object.description, CONTENT_PIECE_DESCRIPTION_MAX_LENGTH)
if (!title || !description) return fallback
return { title, description, source: 'ai' }
} catch {
return fallback
}
}
/**
* The city rule is deliberately conservative: the gazetteer mention list is
* converted to distinct cities, and only a city with exactly ONE catalog entry
* resolves. Salvador has one entry per TSE zone, so a bare "Salvador" mention
* is ambiguous and stays empty — the assessoria picks the zone on the ficha.
*/
export const resolveContentPieceMunicipalityId = async ({
payload,
transcript,
}: {
payload: Payload
transcript: string
}): Promise<number | null> => {
const mentions = matchMunicipalityMentions(transcript)
const cities = new Set(mentions.map((entry) => entry.city))
if (cities.size !== 1) return null
const entries = mentions.filter((entry) => entry.city === [...cities][0])
if (entries.length !== 1) return null
const found = await payload.find({
collection: 'municipality',
where: { slug: { equals: entries[0]!.slug } },
depth: 0,
limit: 1,
pagination: false,
// Intentional admin bypass: the município catalog is read-only geography.
overrideAccess: true,
})
return found.docs[0]?.id ?? null
}
/**
* Matches the institution catalog against the text: a spelling counts only as a
* whole word (accent/case insensitive), and more than one matching institution
* is ambiguous and stays empty.
*/
export const resolveContentPieceInstitution = (transcript: string): string | undefined => {
const haystack = normalizeForSearch(transcript)
const matched = institutionCatalog.filter((entry) =>
institutionSpellings(entry).some((spelling) => {
const needle = normalizeForSearch(spelling)
return (
needle.length > 0 &&
new RegExp(`(^|[^a-z0-9])${escapeRegExp(needle)}([^a-z0-9]|$)`).test(haystack)
)
}),
)
return matched.length === 1 ? matched[0]!.name : undefined
}
/**
* The cataloguing entry point of the job. Runs the gazetteer + the C153
* classifier + the suggestion, and returns only what it is confident about.
* An empty transcript (a photo, a card, a silent video) skips every external
* call and returns `source: 'none'` — the type/title the upload derived stay.
*/
export const catalogContentPiece = async ({
payload,
type,
title,
transcript,
classify = classifySpeech,
suggest = suggestContentPieceMetadata,
}: {
payload: Payload
type: ContentPieceType
title: string
transcript: string | null
classify?: ContentPieceClassifier
suggest?: ContentPieceSuggester
}): Promise<ContentPieceCatalogResult> => {
const text = transcript?.trim() ?? ''
if (!text) return { source: 'none' }
let topics: SpeechTopic[] = []
try {
const classification = await classify({ transcript: text })
topics = [...new Set(classification.facets.topics)]
} catch {
// The classifier contract is "never throws"; if it does, the catalogue
// still gets city/institution/title from the gazetteer and the fallback.
}
const municipalityId = await resolveContentPieceMunicipalityId({ payload, transcript: text })
const municipality = municipalityId
? await payload
.findByID({
collection: 'municipality',
id: municipalityId,
depth: 0,
select: { name: true },
// Intentional admin bypass: the município catalog is read-only geography.
overrideAccess: true,
})
.catch(() => null)
: null
const suggestion = await suggest({
type,
currentTitle: title,
transcript: text,
cityLabel: municipality?.name ?? null,
topics,
})
const institution = resolveContentPieceInstitution(text)?.slice(
0,
CONTENT_PIECE_INSTITUTION_MAX_LENGTH,
)
return {
title: suggestion.title,
description: suggestion.description,
...(topics.length > 0 ? { topics } : {}),
...(municipalityId !== null ? { municipalityId } : {}),
...(institution ? { institution } : {}),
source: suggestion.source,
}
}