teqo-backup/docs/changelog/2026-09-26-c232.md
Francisco Solla 671af1e21f
Some checks are pending
Deploy / preflight (push) Waiting to run
Deploy / verify (push) Blocked by required conditions
Deploy / deploy staging (teqo-staging) (push) Blocked by required conditions
Deploy / requeue when main advanced (push) Blocked by required conditions
Deploy / deploy production (teqo-1313) (push) Blocked by required conditions
feat(C232): pré-catalogar o acervo de fotos com IA local e curadoria que vence
Collection archivePhoto ganha o grupo catalog (legenda/descrição/cena/texto
visível/temas/pessoas/município/origem/catalogedAt), curatedFields (o que a
assessoria edita nunca é sobrescrito), takenOn e searchText com índice GIN trgm
(migration aditiva add_archive_photo_catalog); hook beforeValidate deriva o
índice e marca curadoria só em edição humana; pipeline transacional baixa os
bytes privados, prepara JPEG <=1024px com sharp e mescla o VLM local com o
gazetteer/catálogo curado (pessoas só do TEXTO, nunca de rosto); CLI
pnpm archive:catalog (plan/--apply/--verify, recibo honesto, idempotente por
catalogedAt) com engine OpenAI-compatible na rede privada atrás de guarda de
host (ARCHIVE_VISION_ALLOW_REMOTE é o escape); client HTTP com retry/timeout e
parser zod fail-closed; resolver de município extraído para owner compartilhado
com o catálogo de peças delegando; unit/int novos e runbook staging-primeiro.
2026-09-26 12:30:34 -03:00

2.8 KiB

C232 — catalogação com IA do acervo de fotos (2026-09-26): as 6,5k fotos do acervo privado (archivePhoto, C231) ganham ficha pré-catalogada revisável no admin: legenda/descrição pt-BR, atividade/cena (vocabulário fechado de 11 valores), texto visível (OCR do próprio VLM), temas do vocabulário existente (SPEECH_TOPICS), município pelo gazetteer (regra conservadora: Salvador/zona ambíguo → null, resolver extraído para src/utilities/municipality/municipalityMentionResolver.ts com o catálogo de peças delegando) e pessoas públicas só do catálogo curado, lidas do texto — nunca inferidas de rosto. O engine de visão é um endpoint OpenAI-compatible local (ARCHIVE_VISION_BASE_URL/MODEL/API_KEY — Ollama/llama.cpp/vLLM; nenhum fornecedor pinado) atrás de guarda falha-fechado de host privado (isPrivateVisionHost/assertLocalVisionEndpoint em scripts/lib/cli.mjs, escape explícito ARCHIVE_VISION_ALLOW_REMOTE=1 com o escopo registrado no recibo): PII/rostos não saem da rede sem decisão; terceiro/híbrido rejeitados com gatilho de revisita. A curadoria vence a IA pelo mesmo trio do C230 (ARCHIVE_PHOTO_CURATED_FIELDS no lib + hook beforeValidate que marca campo alterado só quando há req.user e não é escrita do sistema + fresh-read dentro da transação em src/utilities/flickr/archivePhotoCatalog.ts, que baixa os bytes privados via downloadPrivateMediaToFile, prepara JPEG ≤1024px com sharp, injeta o analisador e grava só campo não curado); catalog.source = ai | metadata | none (nada a propor é estado final honesto) e catalog.catalogedAt é a chave de idempotência. O passe é o CLI de manutenção pnpm archive:catalog (plan default / --apply com ARCHIVE_CATALOG_CONFIRM=1 + TEQO_ENV + 4 S3_* / --verify read-only que sai 1 com pendentes; --limit canário; recibo JSON datado em data/archive/reports/), com client HTTP com retry/timeout em scripts/lib/archiveVisionApi.mjs e parser zod fail-closed no lib. A busca interna é o admin stock: searchText normalizado com índice GIN trgm + takenOn (derivado do wall clock do Flickr, meio-dia UTC) + facetas filtráveis (município/cena/temas/pessoas/data/origem); alt é refinado a partir da caption só quando nunca curado. Migration aditiva add_archive_photo_catalog (grupo catalog, curatedFields, takenOn, searchText + índices). Testes: unit do contrato puro/parser/merge, do client (fetch mockado), do parser/recibo e dos guardas por subprocesso; int sobre teqo_test (catálogo grava e deriva o índice, curadoria vence, falha não escreve e retenta, skip por catalogedAt, fontes ai/metadata/none, marcação só em edição humana); sem e2e novo (superfície admin stock, OPS72). Runbook staging-primeiro com canário em docs/ops/teqo-1313-deploy.md. Impl plan: docs/plans/acervo-fotos-catalogacao-ia-impl.md.