A varredura de produção (2026-09-14) achou 33 falas em selCodColecaoCsv=J e 1 com o parâmetro vazio: o endpoint devolve 'Documento não encontrado' e a mesma data/página resolve na coleção D que a busca atual da Câmara gera. Aliases J/vazio → D, puros e unit-testados; DCN e demais códigos ficam como estão.
35 KiB
Impl: Acervo de falas: "Abrir fonte" abre o PDF oficial do Diário (fim do visualizador legado)
Status: aprovado Atualizado em: 2026-09-14 Issue: #988 Intenção: docs/plans/acervo-abrir-fonte-pdf-oficial.md Appetite restante: herdado (~1 dia eng + uma passada de máquina de resolução; sem migration)
Leitura da intenção
- Outcome: toda fala do acervo entrega "Abrir fonte" apontando para o PDF oficial do Diário em
https://imagem.camara.leg.br/Imagem/d/pdf/<narquivo>(#page=<página>quando a URL legada tinhatxPagina); reimport/backfill não reintroduzdc_20b.asp/dc_20.asp/montaPdf.asp; o reparo dos discursos já importados roda com guard de escrita, é idempotente e reporta cobertura (falas/datas atualizadas, falhas). A página do acervo nunca depende da Câmara para renderizar. - O que NÃO negociar:
- Destino é o PDF direto (não o visualizador legado, não o
montaPdfintermediário, não YouTube como padrão); resolver offline/cacheado, uma resolução por publicação compartilhada pelas falas daquela data. - Falha de resolução não entrega link morto: cai no fallback existente (
youtubeUrl; sem ele, botão oculto) e o relatório lista a data como pendência. - Reparo com guard de escrita (
CAMARA_IMPORT_CONFIRM=1viarequiresWriteConfirm), read-only isento (--coverage/--verify-links;--dry-runnovo), reexecutável; cache/report emdata/camara/(gitignored desde C152). - Sem reimportar ASR/LLM, sem tocar VOD (
vodPlaybackUrl/vodDownloadUrl), sem novo campo/segundo link, sem mudar crédito CC BY nem URL pública do acervo.
- Destino é o PDF direto (não o visualizador legado, não o
- O que reavaliar (hipóteses da "Direção no codebase"):
- Consumidores do link (
SpeechResultCard.tsx:125-130, detalhe[id]/page.tsx:63,121-128): nenhuma mudança de UI — o href é direto (sourceUrl = officialTextUrl ?? youtubeUrlemspeechViewModels.ts:221/:249). Os arquivos são referência de leitura, não de escrita. - Estender
--verify-links/--coverage: reavaliado para um corte menor — o--repair-links --dry-runé o verificador read-only (scan + classificação + plano, sem rede quando tudo é direto); a resolução do reparo já verifica cada PDF com Range antes de gravar (D3/D5). - Quando rodar o reparo (intenção recomendou após o merge, assumido): reavaliado para pré-merge no SHA do branch, precedente C155/OPS79 — a reparação é script-only (não depende do deploy) e assim o PR carrega a prova viva; o runbook §C160 executa igual se o operador preferir pós-merge (D8).
- Falha →
null: vale para o write path do import; no reparo, escrevernulldestruiria a única pista da pendência e tiraria a linha do scanner — o reparo deixa a linha intocada e sai vermelho (D4).
- Consumidores do link (
Fatos de código e medição (2026-09-14):
| Verificação | Resultado |
|---|---|
| Gravação atual | scripts/import-camara-speeches.mjs:468 — officialTextUrl: speech.urlTexto ?? null (bundle :458-484; upsert :487). Nenhum outro writer; único ponto do link |
| Consumers | speechViewModels.ts:39/78/221/249; SpeechResultCard.tsx:125-130; [id]/page.tsx:63,121-128 |
| Legado no repo | nenhuma referência a dc_20/montaPdf/narquivo em src/ ou tests/; camaraSpeeches.mjs não tem nada de URL oficial |
| Infra reusável | ensureCachedDownload (cli.mjs:190-228; ext json devolve parseado); probeVodLink (camaraFetch.mjs:129); guard assertWriteAllowed (:870-878) + assertLocalDatabase (:894); writeReport (:614); precedente recover-media.mjs:79-85 |
| e2e | tests/e2e/campaignSpeechAcervo.e2e.spec.ts:44 usa URL fictícia e asserta "Abrir fonte" — não muda (manifest cobre src/utilities/speech, scripts/lib/e2e-affected-manifest.mjs:279-285) |
| URL legada real | https://imagem.camara.gov.br/dc_20b.asp?largura=&altura=&tipoForm=diarios&selCodColecaoCsv=D&Datain=8%2F2%2F2023&txPagina=73&txSuplemento=&enviar=Pesquisar |
Hop 1 .gov.br → .leg.br |
302 com a mesma query; ~135s no teste frio (intenção mediu 25–85s) |
Hop 2 .leg.br → montaPdf |
302 montaPdf.asp?narquivo=DCD0020230208000210000.PDF&npagina=73; ~5,4s; set-cookie ASP |
| PDF direto | https://imagem.camara.leg.br/Imagem/d/pdf/DCD0020230208000210000.PDF → 206 application/pdf em 0,4s com Range 0-1023 (~43,6 MB) |
| Fragmento | #page=73 = txPagina legado / npagina do redirect |
| Exemplos resolvidos | 25/06/2020 → DCD0020200625001020000.PDF#page=129; 28/09/2011 → DCD28SET2011.pdf (ano antigo, nome curto); 10/03/2026 → DCD0020260310000250000.PDF |
narquivo |
não derivável da data (número do Diário fora da URL); só seguindo o redirect — por isso a resolução é cacheada por publicação |
Abordagem recomendada
Evoluir o dono do acervo (C153/C155) com (1) normalização do link no write path do import e (2) um modo de reparo one-off no mesmo CLI, com resolução cacheada por publicação e verificação do PDF antes de gravar.
flowchart LR
subgraph IMPORT["Import (dono) — grava sempre PDF direto"]
A["API discursos<br/>urlTexto = dc_20b.asp"] --> B["classify/parse puro<br/>camaraSpeeches.mjs"]
B -->|legacy| C["resolveOfficialPdfUrl<br/>.leg.br → 302 montaPdf<br/>camaraFetch.mjs"]
C --> P["probeLink Range<br/>200/206 application/pdf"]
P --> D["ensureCachedDownload json<br/><out>/diario/<publicação>.json"]
D --> E["buildOfficialPdfUrl<br/>#page=txPagina"]
B -->|direct / montaPdf| E
B -->|falha| F["null → fallback<br/>youtubeUrl / botão oculto"]
E --> G[("speech.officialTextUrl")]
end
subgraph REPAIR["Reparo one-off — --repair-links"]
H["scan speech<br/>officialTextUrl não-nulo"] --> I["planOfficialLinkRepairs (puro)<br/>agrupa por publicação"]
I --> J["resolve 1×/publicação<br/>cache + probe"]
J -->|"--dry-run (read-only)"| K["relatório, zero escrita"]
J -->|"write + CAMARA_IMPORT_CONFIRM=1"| G
end
G --> L["UI: Abrir fonte<br/>href direto — sem mudança"]
F --> L
Opções consideradas: A) estender o dono (import-camara-speeches.mjs + camaraSpeeches.mjs/camaraFetch.mjs) com normalização no processSpeech e modo --repair-links [--dry-run]; B) script separado repair-camara-links.mjs + normalização só no import; C) re-importar tudo com --all para corrigir o campo; D) resolver no render/clique.
Recomendação: A — um CLI, um cache, um guard, um relatório; o reparo reusa bootstrap/loadCliEnv/writeReport/ensureCachedDownload e o import reusa a mesma resolução.
Rejeitadas: B — twin que duplica bootstrap, guard, cache e a sabedoria da Câmara (dois lugares para o mesmo bug); C — custo de ASR/LLM e risco de regressão em dados bons (o escopo é só o link); D — latência de 5–135s ou pendura no request do usuário e acopla o render à Câmara.
Decisões de engenharia
D1 — Dono único: normalização no import + modo de reparo no mesmo CLI (barato; a decisão que importa é não criar twin)
- Opções: A)
--repair-linksnoimport-camara-speeches.mjs+ normalização emprocessSpeech; B) script novo de reparo; C) reparo via--allre-importando tudo; D) SQL manual no runbook. - Recomendação: A — o import é o dono do campo desde a C153; o reparo é "o mesmo pipeline sem ASR/LLM": varre
speechcomofficialTextUrlnão-nulo (overrideAccess: true,pagination: false,selectmínimo), agrupa por publicação, resolve uma vez por grupo, atualiza só quem muda. Nenhuma escrita fora despeech.officialTextUrl. - Rejeitadas: B — segundo CLI para o mesmo conhecimento (flags, guard, cache, host rewrite) = drift; C — reexecuta página de evento/VOD/ASR (custo e risco) para corrigir um campo; D — sem idempotência, sem relatório e sem guard.
D2 — Resolução pela cadeia de redirect, com host reescrito (caro: é a única fonte do narquivo)
- Opções: A) seguir o redirect HTTP com
fetch(redirect: 'follow';response.urlfinal =montaPdf.asp?narquivo=…&npagina=…) e parsearnarquivo/npagina; reescrever.gov.br→.leg.brantes do lookup (fallback para a URL original); B) derivar o nome do PDF da data; C) raspar o HTML/meta-refresh domontaPdf; D) pedir a URL pronta à API. - Recomendação: A — medido: o
narquivosó aparece depois do 302, eresponse.urlentrega omontaPdfsem parsear HTML; o rewrite pula o hop de ~135s (medido) e o fallback cobre a exceção. Validação de host na URL final (imagem.camara.leg.br) para não seguir redirect fora da Câmara (fail-closed, precedente de origem restrita dorecover-media). - Rejeitadas: B — provado impossível (o número do Diário não está na URL); C — frágil (meta-refresh muda) e desnecessário com
response.url; D — não existe endpoint para isso na API open-data.
D3 — Resolução cacheada e verificada (barato, semântica de cache importa)
- Opções: A)
ensureCachedDownload(extjson) comcacheDir: <out>/diario, chave por publicação (date + collection + supplement),downloadinjetado que segue o redirect e prova o PDF com Range (200/206 application/pdf) antes de devolver o buffer — falha lança, então nada é cacheado; cache só guarda sucesso; B) cache próprio em memória; C) sem cache (uma resolução por fala); D) cachear também falhas. - Recomendação: A — padrão explícito do dono (
ensureCachedDownloademcli.mjs:190), uma chamada de rede por publicação/ever, sobrevive a reexecuções e o--dry-runaquece o cache do write. GeneralizarprobeVodLink→probeLink(url, …)comcontentTypeno retorno (um helper HTTP de probe para VOD e PDF; o único call site existente é o--verify-links). - Rejeitadas: B — re-resolve a cada run (a reparação seria repetida ~700×); C — uma chamada por fala (997×) e o import de um dia pagaria o mesmo hop de novo; D — veneno de cache: uma falha transitória bloquearia o reparo para sempre.
- Forma do JSON cacheado:
{ archiveFileName, page, finalUrl, checkedAt }(auditoria; identifiers em inglês, onarquivoda Câmara viraarchiveFileName); o fragmento#pageé montado por fala, nunca cacheado.
D4 — Semântica de falha nos dois write paths (caro: dado real)
- Opções: A) import: falha →
officialTextUrl = null(fallback existente), preservandoexisting.officialTextUrlse já for direto; reparo: falha → não escreve a linha, reporta a publicação e o run termina vermelho, reexecutável; B)nullnos dois; C) manter o legado nos dois; D) falha silenciosa. - Recomendação: A — no import (execução autônoma) o aceite manda nada de link morto → fallback (
youtubeUrl; sem ele, botão oculto), com falhastage: 'official-link'no relatório; no reparo (sessão de operador) escrevernulldestruiria a única pista da pendência e removeria a linha do scanner — a linha fica intocada, o run sai 1 e a próxima passada é idempotente. Preservar o direto anterior em falha evita que um reimport com rede ruim apague um reparo bom. - Rejeitadas: B no reparo — perde a pista e a capacidade de retry; C — viola o aceite "reimport não reintroduz o legado"; D — inaceitável (o relatório é o produto da operação).
D5 — Verificação read-only pós-reparo: o menor corte (barato)
- Opções: A)
--repair-links --dry-runcomo aceite (contadiretas/legadas/desconhecidas, lista datas pendentes; sem rede quando tudo é direto) + a verificação de PDF embutida na resolução (D3); B) estender--verify-linkspara probe-arofficialTextUrl; C) modo novo--verify-official <n>; D) colunalegacyTextUrlno--coverage. - Recomendação: A — determinístico, sem rede, sem guard, e já é o veículo do relatório; a reachability do PDF é provada na própria resolução (
probeLinkantes de cachear/gravar), então um probe de amostra não adiciona garantia nova (o PDF é estático; o VOD, que é regenerável, continua coberto pelo--verify-links). - Rejeitadas: B — muda a semântica da amostra de VOD (rows sem VOD e com oficial ficariam de fora) e duplica o que a resolução já prova; C — cerimônia; D — redundante com o dry-run (revisitar se um dia houver série histórica de saúde do link).
D6 — Guard do modo de reparo (caro: fail-closed)
- Opções: A)
--repair-links --dry-run= read-only (exige sóDATABASE_URL);--repair-links= write, passa porassertWriteAllowed(CAMARA_IMPORT_CONFIRM=1quandoNODE_ENV=production/host não-local/ALLOW_REMOTE_DB) e porassertLocalDatabase; B) read-only por padrão +--applypara escrever; C) escrever sempre que--repair-linksfor passado. - Recomendação: A — vocabulário existente do CLI (o modo é a ação; a flag de ambiente é a intenção), precedente literal de
recover-mediae do próprio import;--dry-runsem--repair-linksmorre no parse;--repair-linksnão combina com--all/--date/--legislature/--coverage/--verify-linksnem com--limit/--skip-transcribe/--reclassify. - Rejeitadas: B — diverge do CLI atual (
--alljá escreve com guard) sem ganho de segurança; C — perde o dry-run barato e o planejamento.
D7 — Testes proporcionais (barato)
- Opções: A) unit dos puros novos com as URLs reais medidas + int do estado do import; B) e2e/CLI com rede; C) nenhum teste novo; D) extrair
parseArgspara teste. - Recomendação: A — os puros (
classifyOfficialTextUrl,parseLegacyOfficialUrl,parseMontaPdfUrl,buildOfficialPdfUrl,publicationCacheKey,planOfficialLinkRepairs) são exatamente onde a regra frágil mora e falham em silêncio sem teste; o int dospeechImportganha a asserção doofficialTextUrlnofindSpeechImportState; o e2ecampaignSpeechAcervoexistente não muda (a URL fictícia e o assert "Abrir fonte" continuam) e roda selecionado pelo manifest (src/utilities/speech). - Rejeitadas: B — flaky, depende da Câmara e não prova a regra; C — o classifier/grouper são a parte que erra; D — desproporcional (fill-in futuro se a CLI crescer).
D8 — Onde e quando o reparo roda (caro: dado real; ordem documentada)
- Opções: A) pré-merge no homeserver, checkout
~/teqo-backfillno SHA do branch, dry-run → write → dry-run (precedente C155/OPS79), com o resultado no PR; B) pós-merge/deploy no SHA de main (recomendação assumida da intenção); C) junto do próximo import. - Recomendação: A — o reparo não depende do deploy (script-only; nenhuma migration), então rodar antes do merge entrega a prova viva no PR e fecha a Issue com produção já reparada; o guard é o mesmo e a passada é idempotente. O runbook §C160 documenta a mesma sequência para reexecução pós-merge, se preferirem.
- Rejeitadas: B — deixa a janela "mergeado e Issue fechada com o legado no ar" dependente de um operador não agendado, sem prova viva no PR; C — acopla um defeito de UI à janela do próximo import.
Componentes / mudanças
| Arquivo | Mudança |
|---|---|
scripts/lib/camaraSpeeches.mjs (puro) |
classifyOfficialTextUrl(raw) → none|direct|legacy|montaPdf|unknown; isLegacyDiarioUrl(raw) (shape legado mesmo malformado); parseLegacyOfficialUrl(raw) → { lookupUrl (.gov.br→.leg.br), publication {date ISO, collection, supplement}, page }; parseMontaPdfUrl(raw) → { archiveFileName, page }; buildOfficialPdfUrl(archiveFileName, page) → /Imagem/d/pdf/<archiveFileName>[#page=]; officialTextUrlFallback(existingUrl) (preserva só PDF direto); publicationCacheKey(publication) (filesystem-safe); planOfficialLinkRepairs(rows) → { groups, directUpdates, alreadyDirect, unknown, unresolvable, none } |
scripts/lib/camaraFetch.mjs (HTTP) |
resolveOfficialPdfUrl(legacyUrl, { timeoutMs: 180_000, attempts: 2 }) — parse estrito (fail-closed se não for link legado), rewrite do host, redirect: 'follow', lê response.url, valida host Câmara, parseia montaPdf/PDF direto, retorna { archiveFileName, page, pdfUrl, finalUrl }, lança em falha; renomear probeVodLink → probeLink (mesmo comportamento + campo contentType; único call site em --verify-links) |
scripts/import-camara-speeches.mjs (dono) |
--repair-links + --dry-run no parseArgs/HELP/modeLabel; normalização em processSpeech (classifica/parseia/resolve com ensureCachedDownload em <out>/diario; falha → null preservando direto anterior; report.officialLink; falha stage:'official-link'); runRepairLinks (scan/plan/resolve/update/relatório repair-links-<runAt>.json); hint do guard aponta §C155/§C160 |
src/utilities/speech/speechImport.ts |
SpeechImportState.officialTextUrl (select + retorno) para a preservação em falha; nenhuma outra semântica muda |
tests/unit/camaraSpeeches.unit.spec.ts |
Unit dos 6 puros com as URLs reais (legada .gov.br, .leg.br, montaPdf, PDF direto, ano curto, null/desconhecida; datas 2023-02-08/2020-06-25; páginas 73/129) |
tests/int/speechImport.int.spec.ts |
Asserção de officialTextUrl no findSpeechImportState (bundle com URL direta) |
docs/ops/teqo-1313-deploy.md |
Nova ## C160 — reparo do link oficial do acervo (PDF direto do Diário): pré-requisitos, dry-run → write → dry-run, esperado, rollback, comportamento medido da Câmara |
docs/changelog/2026-09-14-c160.md (novo) |
Entrada curta com os números medidos na passada de produção |
Sem migration, sem schema, sem access, sem UI, sem package.json (pnpm camara:import existe), sem Consent. data/camara/ já é gitignored (.gitignore:77); o cache novo é data/camara/diario/.
Dados → forma (relatórios)
- Import (delta no relatório C153/C155): por fala,
officialLink: 'none'|'direct'|'resolved'|'failed'|'unknown'(fill-in de nome); falha entra emfailures[]comstage: 'official-link'e mensagem. OspeechLine/stdout pode mostrarlink oficial resolvido/link oficial falhou— sem contadores novos obrigatórios. - Reparo (
repair-links-<runAt>.json,<out>/reports/):scanned(falas comofficialTextUrlnão-nulo),withoutLink(totalspeech− scanned),alreadyDirect,unknown[](id + url, intocados);publications[]:{ key, lookupUrl, archiveFileName, state: 'resolved'|'failed', rows, pages[], error? };unresolvable[]: legados malformados (ficam intocados e o write sai 1 — nenhum link legado pode permanecer);updates[]:{ id, speechAt, legislature, previousUrl, nextUrl }(planejado no dry-run; aplicado no write);totals:{ legacy, updated, failedPublications, failedRows, remainingLegacy };dryRun,runAt,elapsedMs,options.
- Stdout:
falas: N com link (D diretas, L legadas em P publicações, U desconhecidas); M sem link→publicações: R resolvidas, F falhas→dry-run: L seriam atualizadas/atualizadas: L; legadas restantes: 0. Falhas listadas comkey/data/erro. - Destino: JSONs no homeserver (
/srv/hdd/backups/teqo-camara/reports/), nada commitado; resumo no corpo do PR, no changelog e no runbook.
Fases verificáveis
- Puros + unit (≈0,25 dia). Implementar os 6 helpers em
camaraSpeeches.mjse os unit com as URLs reais medidas. Prova:pnpm test:unitverde (casos novos),pnpm lint,pnpm typecheck. Quota: ~150 linhas no lib + ~120 no spec. - Rede + import (≈0,25 dia).
resolveOfficialPdfUrl+probeLink; normalização emprocessSpeech;SpeechImportState.officialTextUrl. Prova local (teqo_wt160):pnpm camara:import --date <dia real> --limit 1→ linha com PDF direto (#page), sem falhaofficial-link; reexecução =cache hite mesmo valor. Se a rede workstation→Câmara estiver instável, o smoke real vira a Fase 4 (homeserver). Quota: ~60 linhas emcamaraFetch+ ~60 no import + ~4 nospeechImport. - Reparo (≈0,25 dia). Modo
--repair-links/--dry-run,planOfficialLinkRepairsno caminho, relatório e guards. Prova local: fixture com a URL legada real → dry-run não escreve (valores intactos); write → linha vira PDF direto; 2ª passada = 0 updates/remainingLegacy: 0; URL desconhecida viraunknownsem escrita; falha de publicação força exit 1 no write (e 0 no dry-run). Quota: ~120 linhas + ~40 no int. - Ops em produção (pré-merge; ≈1h preparo + ~1h de resolução + ~10min). Após push do branch:
~/teqo-backfillno SHA do branch,pnpm install, envs de~/stack/.env+~/stack/teqo-1313.env,DATABASE_URLreescrito para o proxy127.0.0.1:5433,--out /srv/hdd/backups/teqo-camara. Passos:--repair-links --dry-run(mede falas/legadas/publicações; 0 falhas esperadas; aquece o cache) →CAMARA_IMPORT_CONFIRM=1 pnpm camara:import --repair-links→--repair-links --dry-run(0 legadas) →pnpm camara:import --coverage(acervo íntegro). Prova: JSONs + números no PR. - Fechamento (≈0,5h). Runbook §C160 + changelog com os números medidos;
pnpm gate:fast,pnpm test:int, e2ecampaignSpeechAcervo(selecionado pelo manifest desrc/utilities/speech— preservado, sem mudanças);pnpm push; PRCloses #988+ auto-merge. Quota: 1 PR; prova: checkchecksverde.
Rabbit holes / Não escopo (engenharia)
- Espelhar PDFs no Garage, baixar o Diário, gerar clipes — não (intenção corta).
- Resolver no
render/clique ou cache HTTP na página — não; resolução offline por publicação. - Nova migration/campo/segundo link, UI, Consent, access — não; o
officialTextUrlé o mesmo campo. - Estender
--verify-links/--coveragepara link oficial, modo--verify-official, probe periódico — não (D5). - Fórmula para o
narquivo, crawler do Diário, fallback de meta-refresh — não; o redirect é a fonte. - Generalizar o resolver para o Senado/comissões/outras publicações — não.
- Parallelizar resoluções, otimizar wall clock — não; uma por publicação, com cache e pausa educada.
- Refatorar
parseArgsinteiro ou promover o resolver a utilitysrc/— não; dono éscripts/. - Commitar cache/relatórios — não (
data/camara/gitignored).
Adiado com gatilho (triage do simplify)
- Conversão
montaPdfduplicada (2 call sites:resolveOfficialTextUrleplanOfficialLinkRepairs): extrair um helper puro no lib quando um 3º call site aparecer ou a regra mudar. - Wiring do fallback do import (preservar PDF direto anterior em falha de resolução) coberto pelo unit de
officialTextUrlFallback, não pela closure do script: extrair o resolvedor com deps injetadas se o caminho de falha ganhar um modo novo ou o fallback for modificado. - Sanitize da cache key (
publicationCacheKey) funde códigos de coleção com caracteres não previstos (_): revisitar se aparecer coleção real fora de[A-Za-z0-9].
Riscos e mitigação
| Risco | Mitigação |
|---|---|
Fonte lenta/instável (.gov.br 135s frio; hangs) |
Rewrite .leg.br no lookup; timeout 180s + 2 tentativas; fallback para a URL original; cache por publicação; falha vira pendência, nunca link morto |
Shape do redirect mudar (montaPdf renomeado/host novo) |
Resolver valida host e formato e falha fechado; unit pina os shapes com URL real; report lista as datas; gatilho de revisitação no runbook |
| Reimport regride um link já reparado | Normalização no write path; preservar existing direto em falha; aceite pós-passada = --repair-links --dry-run com 0 legadas |
| Cache envenenado por falha transitória | download lança em falha ⇒ ensureCachedDownload não grava; cache só de sucesso; próxima passada tenta de novo |
| Falha parcial no reparo | Linhas falhas ficam intocadas, run sai 1, relatório lista as datas; reexecução idempotente (só o que falta é re-resolvido) |
| ~700 publicações × ~5s = wall clock alto | Cache por publicação; dry-run aquece o cache do write (write ≈ só updates no DB); pausa de 250ms; medir no dry-run |
narquivo errado/PDF 404 ou HTML anti-bot |
probeLink com Range antes de cachear/gravar: exige 200/206 application/pdf; sem probe ok, não escreve |
| Escrita concorrente com o app em produção | Update de um único campo em speech, sequencial, sem locks de outras tabelas; janela de baixa atividade |
| Rollback | Não há schema a desfazer; previousUrl de cada linha no JSON do run; reexecução do import/reparo sempre reconstrói o valor direto |
Aceite de engenharia
- Aceite de produto da intenção coberto: nenhuma fala entrega
dc_20b.asp/dc_20.asp/montaPdf.asp; clique abre o PDF direto (com#pagequando haviatxPagina); render do acervo não depende da Câmara. - Import grava sempre PDF direto (ou
nullno fallback); reimport não reintroduz legado; falha reportada comstage: 'official-link'. --repair-links --dry-runread-only (sem guard, sem escrita);--repair-linkscomCAMARA_IMPORT_CONFIRM=1+assertLocalDatabase; não combina com outros modos;--dry-runexige--repair-links.- Reparo idempotente e com cobertura: 2ª passada = 0 updates/0 legadas; report com falas/datas atualizadas, falhas e
remainingLegacy; produção com 0 legadas após a passada. - Sem migration/schema/UI/Consent; VOD e transcrições intocados; crédito "Fonte: Câmara dos Deputados · CC BY 4.0" mantido;
data/camara/fora do git. - Invariantes AGENTS/engineering-standards: copy pt-BR/identificadores em inglês;
overrideAccess: truecom comentário de bypass (CLI sem sessão); escrita em uma única collection (sem transação multi-collection); semContact/collection paralela. - Testes: unit novos verdes (puros com URLs reais); int do
speechImportatualizado; e2ecampaignSpeechAcervopreservado e verde (selecionado via manifest);pnpm gate:fast+ CI verdes. - Runbook
§C160edocs/changelog/2026-09-14-c160.mdcom os números medidos; PRCloses #988com auto-merge.
Self-score decision-quality
| Critério | Nota | Justificativa |
|---|---|---|
| 1. Decisões caras têm rejeitadas | 5 | D1 (dono único vs twin/script novo), D2 (redirect vs fórmula/raspagem), D4 (falha nos dois write paths), D6 (guard), D8 (timing em produção) com opções, recomendação e rejeitadas justificadas; o barato (nomes de campos, n de probe, formato do stdout) ficou como fill-in. |
| 2. Abordagem cabe no appetite | 5 | ~1 dia eng; sem migration/schema/UI; reusa ensureCachedDownload, probeLink, guards, writeReport e os puros do dono; a passada de máquina é cacheada por publicação (não 997 resoluções). |
| 3. Rabbit holes nomeados | 5 | Espelhar PDFs, resolver no render, schema/segundo link, extensão de --verify-links/--coverage, generalização para outras casas, paralelização e commit de artefatos explicitamente cortados. |
| 4. Depth check (reusa donos/shells) | 5 | Nenhum módulo/collection/rota nova: o dono (import-camara-speeches.mjs), os puros (camaraSpeeches.mjs), o HTTP (camaraFetch.mjs), o cache (ensureCachedDownload), o guard (requiresWriteConfirm/assertLocalDatabase), o relatório (writeReport) e o estado (findSpeechImportState) são estendidos no lugar; sem twin. |
| 5. Intenção (aceite) preservada | 4 | Todo o aceite mapeado; dois desvios conscientes documentados — timing do reparo (pré-merge com precedente C155/OPS79, em vez do "após o merge" assumido) e falha no reparo deixar a linha intocada + exit 1 (em vez de null), ambos com rejeitadas e alternativa no runbook. |
Média: 4,8 (≥4).