mirror of
https://github.com/fsolla/teqo.git
synced 2026-11-20 01:33:05 +00:00
270 lines
16 KiB
Markdown
270 lines
16 KiB
Markdown
# Impl: OPS52-media — Recuperar os arquivos de media de produção (capas dos artigos)
|
||
|
||
Status: aprovado (gate humano 2026-08-18)
|
||
Atualizado em: 2026-08-18
|
||
Issue: #10 (OPS52-media)
|
||
Intenção: docs/plans/ops52-media-recuperar-arquivos.md
|
||
Appetite restante: herdado (~0,5–1 dia eng; um outcome verificável)
|
||
|
||
## Leitura da intenção
|
||
|
||
- **Outcome:** as ~40 capas de media de produção resolvem no site público:
|
||
`GET https://jorgesolla1313.com.br/api/media/file/<filename>` → **200 com a
|
||
imagem** para toda row; seção S1 da home e artigos exibem as capas; uploads
|
||
novos continuam servindo; fail-closed de storage mantido; **zero mudança de
|
||
schema/migration/Consent**.
|
||
- **O que NÃO negociar:** URLs das rows intocadas (contrato relativo via proxy);
|
||
sem reescrita em massa no banco; sem placeholder "em breve"; sem gravar em
|
||
storage errado; DB nunca escrito pela ferramenta de recuperação.
|
||
- **O que reavaliar:** a hipótese "só falta o arquivo no bucket" precisa de um
|
||
pre-flight — ver Evidência E3 (rota de media de prod hoje **pendura**, não 404).
|
||
|
||
## Evidência coletada (2026-08-18, probes read-only)
|
||
|
||
- **E1 — Fonte das capas no WordPress:** o REST `_embed` de jorgesolla.com.br
|
||
tem **7/43** posts com `wp:featuredmedia`; a maioria das capas do seed vem do
|
||
fallback **primeira imagem inline do corpo** (`processContent` em
|
||
`scripts/seed-posts.mjs` — resolução compartilhada via `resolveCoverSource`).
|
||
A recuperação replica essa resolução exata (featured → senão 1º `img[src]` do
|
||
HTML), senão cobre errado. Todas as 42 capas resolvidas de hoje estão no host
|
||
`jorgesolla.com.br` (probe) — o que permite o allowlist de host no download.
|
||
- **E2 — Contrato de URL:** aceite e AGENTS.md dizem `/api/media/file/<filename>`;
|
||
o frontend usa `cover.url` relativo como `src` (src/components/PostCard.tsx:26)
|
||
e o staticHandler do `@payloadcms/storage-s3` serve a rota streamando o objeto
|
||
(getObject com range/etag-304 nativos; `NoSuchKey` → 404 rápido, ver
|
||
`node_modules/@payloadcms/storage-s3/dist/staticHandler.js`).
|
||
- **E3 — Rota de media em prod HOJE:** `curl -I https://jorgesolla1313.com.br/api/media/file/<filename>`
|
||
→ conexão TLS ok, **sem resposta em 25s+** (não é 404). O handler 404-rápido
|
||
para chave ausente ⇒ o `headObject` do container prod provavelmente **não
|
||
completa** (rota container→Garage tailnet suspeita; Garage está vivo e
|
||
alcançável pelo tailnet desta máquina — 403 no probe sem assinatura). O
|
||
pre-flight do runbook separa "arquivo faltando" (esta Issue) de
|
||
"container prod sem rota ao Garage" (infra — provável sucessor OPS se
|
||
confirmado; o aceite desta Issue exige a rota pública 200).
|
||
- **E4 — Postgres prod não exposto ao host** (5432 do homeserver recusou
|
||
conexão): o script de recuperação roda **no homeserver**, dentro da rede do
|
||
compose (padrão do serviço `teqo-1313-migrate`), com `~/stack/teqo-1313.env`
|
||
(DATABASE*URL resolve o serviço `postgres`; S3*\* presentes).
|
||
- **E5 — Rows:** 40 rows de `media` (39 capas do seed + 1 órfã provável),
|
||
`filename` único e indexado; o mapeamento row→post é exato via
|
||
`post.coverImage` (FOREIGN KEY confirmada no schema local); fallback
|
||
filename-derivado para órfãs.
|
||
|
||
## Abordagem recomendada
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[rows media + posts.coverImage] -->|Payload find, DB prod| B[recover-media.mjs]
|
||
C[WordPress REST _embed<br/>scripts/lib/wpArticles.mjs] -->|slug -> coverUrl<br/>featured | inline 1o img| B
|
||
B -->|PutObject key = filename<br/>SDK S3 SigV4, bucket teqo-media| G[Garage prod]
|
||
B -.->|--dry-run headObject<br/>--verify HEAD URL pública| R[relatório por row]
|
||
P[browser] -->|GET /api/media/file/<filename>| X[Payload staticHandler] --> G
|
||
```
|
||
|
||
**Opções consideradas:**
|
||
|
||
- **A — Script CLI commitado `scripts/recover-media.mjs`** (modo `reconcile` /
|
||
`--dry-run` / `--verify`), lendo rows do DB prod e escrevendo SÓ objetos no
|
||
bucket via `@aws-sdk/client-s3`, com guards fail-closed e runbook no
|
||
homeserver. **Recomendada.**
|
||
- B — One-off manual no homeserver (curl/SDK em scratch) sem código commitado —
|
||
sem evidência de aceite reproduzível, sem guard de alvo, contrário à própria
|
||
intenção ("ferramenta de reconciliação deve ser explícita sobre o alvo").
|
||
- C — Estender `scripts/seed-posts.mjs` com `--restore` — acopla seed de
|
||
conteúdo (guard local-only, idempotência por slug) com recuperação de prod
|
||
(bucket + DB remoto): semântica confusa, risco de rodar contra DB errado.
|
||
|
||
**Recomendação: A** — porque o problema é um débito operacional de prod com
|
||
aceite verificável (200 por filename): um CLI commitado com o mesmo padrão de
|
||
guard dos seeds (all-or-nothing S3, `ALLOW_REMOTE_DB=true` explícito, echo do
|
||
alvo) é a forma reproduzível e segura; os modos `--dry-run`/`--verify` dão o
|
||
pre-flight e o aceite sem depender de credencial.
|
||
|
||
**Rejeitadas:** B (não reproduzível, sem guard de alvo); C (acopla dois
|
||
contratos de guard diferentes no mesmo script; o seed é local-first por design).
|
||
|
||
### Componentes / mudanças
|
||
|
||
- **`scripts/lib/wpArticles.mjs`** (novo — extração do dono, sem twin):
|
||
move de `scripts/seed-posts.mjs` o que é fetch puro do WordPress
|
||
(`BASE_URL`, `USER_AGENT`, `stripHtml`, `fetchViaRestApi`, o typedef
|
||
`Article`) e adiciona `inlineCoverUrl(html)` (1ª `img[src]` — a peça que o
|
||
`processContent` do seed usa como fallback; idêntica semântica). O seed
|
||
importa daqui (comportamento inalterado; `fetchViaHtmlArchive` e
|
||
`processContent` permanecem no seed). Helpers puros adicionais:
|
||
`slugFromFilename(filename)` (remove a última extensão) e a resolução
|
||
`resolveCoverSource(article)` (`article.coverUrl || inlineCoverUrl(...)`).
|
||
Unit-testados (padrão dos módulos de `scripts/lib`).
|
||
- **`scripts/recover-media.mjs`** (novo): fluxo — _(desde OPS52-media-guard,
|
||
#37, o reconcile também exige `MEDIA_RECOVER_CONFIRM=1` antes de qualquer
|
||
passo abaixo — ver `docs/plans/ops52-media-guard-impl.md`)_
|
||
1. `loadCliEnv` + `assertLocalDatabase('media:recover', hint do runbook)` +
|
||
`resolveS3StorageEnv(process.env)` (reuso de `src/utilities/mediaStorage.ts`;
|
||
aborta se `enabled: false` — recuperação é operação de prod, nunca storage
|
||
local) → **echo do alvo** (host do DB, endpoint, bucket) antes de qualquer
|
||
escrita.
|
||
2. Leitura read-only: `payload.find` em `media` (todas as rows) e em `post`
|
||
com `coverImage` (depth 0) → mapa `mediaId → post.slug`; fallback
|
||
`slugFromFilename(row.filename)`.
|
||
3. `fetchArticlesFromWordPress()` → mapa `slug → coverUrl` (featured →
|
||
inline 1º img, exatamente como o seed).
|
||
4. Por row: resolve cover; `fetch` do cover (User-Agent do seed);
|
||
`PutObjectCommand` key **= `row.filename` verbatim**, `ContentType` =
|
||
content-type do download (os bytes reais mandam no decode — o nome do
|
||
arquivo é cosmético no contrato), sobrescreve (idempotente).
|
||
5. Relatório por row (uploaded / sem-cover / erro) + resumo; **nunca**
|
||
`payload.create/update` — o script só lê o DB.
|
||
- **Modos:** default = reconcile (plano + upload); `--dry-run` = plano +
|
||
`headObject` por key (presente/ausente), zero escrita; `--verify` = `HEAD`
|
||
de cada filename contra a URL pública (`NEXT_PUBLIC_SITE_URL` ou
|
||
`https://jorgesolla1313.com.br`), o aceite da Issue, sem credencial de bucket.
|
||
- **Timeouts fail-fast:** `@aws-sdk/client-s3` + `@smithy/node-http-handler`
|
||
(devDependencies, versões já no lockfile) com `connectionTimeout: 5s` /
|
||
`requestTimeout: 15s` — endpoint inalcançável falha em segundos, não pendura
|
||
(mitiga o sintoma da E3 no runbook).
|
||
- **`package.json`:** `media:recover` (mesma fiação `--import=tsx/esm
|
||
--import=./scripts/seed-loader.mjs` dos seeds — os hooks de `post` chamam
|
||
`revalidateTag`).
|
||
- **Migration:** nenhuma. **Access/Consent:** intocados (`media.read` público;
|
||
a tool não autentica nada).
|
||
- **Runbook + docs:** seção no impl plan (ordem do homeserver) + nota curta no
|
||
AGENTS.md (seeds/media §) apontando o runbook; entrada
|
||
`docs/changelog/2026-08-18-ops52-media.md` + `pnpm changelog:build`.
|
||
- **UI:** N/A (Impeccable A — a seção S1 renderiza certo; problema é a media).
|
||
|
||
## Revisão pós-simplify (2026-08-18 — 3 revisores, fixes absorvidos)
|
||
|
||
- Download de capa com `AbortSignal.timeout(30s)`; fetch do REST com signal
|
||
opcional (60s no recover; o seed passa nenhum — semântica do fallback
|
||
intacta).
|
||
- Covers constrangidas a http(s) no host do WP (`resolveCoverDownloadUrl`;
|
||
relativas resolvem contra a origem) e só `image/*` é armazenado — sem SSRF
|
||
do homeserver, sem objeto não-imagem servido same-origin pelo proxy.
|
||
- `--verify` não resolve S3\_\* (config parcial não mata o aceite); origin do
|
||
verify ecoado no resumo de alvo.
|
||
- `--dry-run` sai com exit 1 quando QUALQUER checagem do bucket falha
|
||
(pre-flight honesto — all-erro ≠ 0).
|
||
- `resolveMediaCoverSources` extraído puro para a lib e unit-testado
|
||
(mapeamento row→post→cover, fallback e classificação de fonte); `fmt` e o
|
||
twin do `processContent` corrigidos.
|
||
- DevDeps com range `^` (convenção do repo); script `media:recover` fora do
|
||
bloco `db:seed:`; typedef `Article` via `@import` no seed.
|
||
|
||
## Fases verificáveis
|
||
|
||
1. **Lib + refactor do seed** — `scripts/lib/wpArticles.mjs` + seed importando
|
||
(fetch idêntico); unit tests de `slugFromFilename` / `inlineCoverUrl` /
|
||
`resolveCoverSource`; `pnpm gate:fast` + `pnpm format:check` + `knip` +
|
||
`check:cycles`; conferir `git diff` do seed = só import.
|
||
2. **Script de recuperação** — `recover-media.mjs` + npm script + devDeps;
|
||
`--dry-run` contra DB local (rows vazias — valida guards e caminho read-only);
|
||
unit dos helpers puros; gates da fase 1 repetidos.
|
||
3. **Docs + changelog** — runbook no impl plan, nota no AGENTS.md,
|
||
`docs/changelog/2026-08-18-ops52-media.md`, `pnpm changelog:build` +
|
||
`pnpm changelog:check`.
|
||
4. **Gates finais** — `pnpm gate:fast`, `pnpm format:check`, `pnpm exec knip`,
|
||
`pnpm check:cycles`, `pnpm test` (unit+int), `pnpm build` local.
|
||
5. **Execução em prod (pós-merge, runbook — humano):**
|
||
|
||
## Runbook de execução em produção (pós-merge, humano)
|
||
|
||
> **Estado 2026-08-18 (executado):** 38/40 objetos restaurados e servindo 200 em
|
||
> `/api/media/file/...`; exceções sem fonte: `fim-escala-6x1.jpg` e
|
||
> `jorgesolla.jpg` (404 honesto — rows manuais, não referenciadas por posts).
|
||
> **E3 resolvido na raiz:** o container prod não alcançava o Garage — o
|
||
> firewall do host derrubava TODA a sub-rede do docker (gateway, LAN e tailnet:
|
||
> tudo bloqueado — o `headObject` pendurava e a rota de media dava timeout).
|
||
> Fix aplicado no homeserver (reversível):
|
||
>
|
||
> 1. `sudo ufw allow from 10.0.11.0/24 to any port 3900 proto tcp` (INPUT)
|
||
> 2. `sudo ufw route allow from 10.0.11.0/24 to any port 3900 proto tcp` (FWD)
|
||
> 3. `extra_hosts: ["host.docker.internal:host-gateway"]` nos serviços
|
||
> `teqo-1313` e `teqo-1313-migrate` do `~/stack/docker-compose.yml`
|
||
> (sobrevive aos deploys — o OPS53 edita o compose in-place; backup
|
||
> `docker-compose.yml.pre-ops52-media-hostgateway`)
|
||
> 4. `S3_ENDPOINT=http://host.docker.internal:3900` no `~/stack/teqo-1313.env`
|
||
> (o tailnet IP continua sendo o endpoint da workstation)
|
||
|
||
Ordem das próximas execuções (pós-merge, humano):
|
||
|
||
1. **Deploy do merge em `main`** (CI OPS53) — o script e a lib chegam ao
|
||
homeserver com a imagem do SHA.
|
||
2. **Pre-flight no homeserver** (rede do compose, env do stack
|
||
`~/stack/teqo-1313.env` — `DATABASE_URL` resolve o serviço `postgres` e as
|
||
`S3_*` já estão lá):
|
||
```bash
|
||
cd ~/stack
|
||
set -a; source teqo-1313.env; set +a
|
||
ALLOW_REMOTE_DB=true pnpm media:recover --dry-run
|
||
```
|
||
Esperado: `headObject` de cada filename responde `presente`/`ausente` em
|
||
segundos. Se TODAS as rows derem `erro` (timeout/ECONNREFUSED), o container
|
||
não alcança o Garage — repetir o diagnóstico do estado acima (firewall +
|
||
extra_hosts + endpoint) antes de recuperar.
|
||
3. **Recuperar** (o reconcile escreve no bucket — guard de intenção explícita
|
||
OPS52-media-guard exige `MEDIA_RECOVER_CONFIRM=1`; sem ela o script recusa
|
||
com a mensagem e o comando correto):
|
||
```bash
|
||
MEDIA_RECOVER_CONFIRM=1 ALLOW_REMOTE_DB=true pnpm media:recover
|
||
```
|
||
Esperado: 40 uploads (`PutObject` key = filename; idempotente por overwrite),
|
||
exceções reais (sem cover / download 404) listadas no relatório — conferir
|
||
e registrar na Issue; exit 1 se houver falhas.
|
||
4. **Aceite:**
|
||
```bash
|
||
ALLOW_REMOTE_DB=true pnpm media:recover --verify
|
||
```
|
||
Esperado: `38/40 filenames respondendo 200 em https://jorgesolla1313.com.br`
|
||
(as 2 exceções seguem 404 — aceite da Issue contempla o registro honesto).
|
||
Se persistir pendurando (erro/timeout) com objetos no bucket → confirmar
|
||
container→Garage (passo 2) — agora a causa raiz conhecida é firewall.
|
||
5. **Check visual:** home de campanha (seção "Acompanhe de perto") e 1–2
|
||
páginas de artigo com capa; console do navegador sem erro de imagem.
|
||
6. **Exceções:** `fim-escala-6x1.jpg` e `jorgesolla.jpg` (rows manuais sem
|
||
fonte no WP) → reportar na Issue #10; o card degrada para a banda cinza
|
||
existente (sem placeholder, sem placeholder "em breve").
|
||
|
||
## Rabbit holes / Não escopo (engenharia)
|
||
|
||
- **Testar o script ponta a ponta desta máquina** — impossível por contrato:
|
||
sem S3\_\* (fail-closed) e sem DB prod; a prova E2E é o runbook do homeserver
|
||
(padrão OPS52 fase 3: prova de contrato manual, humana).
|
||
- **`--verify` exigir credencial** — não: URL pública é o aceite; sem bucket.
|
||
- **Consertar a rota/connectivity container→Garage** — se o pre-flight/verify
|
||
confirmar E3 como infra, é sucessor OPS (documentar diagnóstico no runbook),
|
||
não muda nada desta entrega.
|
||
- **Deletar a store do Vercel Blob / bucket público / CDN** — já fora de escopo
|
||
do OPS52/intenção.
|
||
- **Reescrever URLs das rows / recriar rows** — proibido pelo aceite; a tool
|
||
grava só objetos.
|
||
|
||
## Riscos e mitigação
|
||
|
||
- **R1 — Rota pública segue pendurando após recuperar objetos (E3 real).**
|
||
Mitigação: pre-flight no runbook (dry-run com timeout fail-fast já sinaliza
|
||
endpoint inalcançável; `--verify` pós-upload é o aceite). Se confirmar
|
||
infra container→Garage: reportar na Issue e abrir sucessor OPS — o aceite
|
||
desta Issue depende da rota 200, e o objeto restaurado é condição necessária
|
||
mas o caminho de rede é do ambiente.
|
||
- **R2 — Capa do WP mudou desde o seed (featured nova / imagem removida).**
|
||
Q1 da intenção aceita a capa atual do WP como fonte; exceções reais
|
||
(fetch 404/erro) são registradas e o card degrada para a banda cinza já
|
||
existente — sem placeholder.
|
||
- **R3 — Órfã (40ª row) não resolve por post nem por slug.**
|
||
Exceção no relatório; humano decide (registrar na Issue). Não inventar fonte.
|
||
- **R4 — Guard de alvo insuficiente (rodar contra bucket errado).**
|
||
`resolveS3StorageEnv` fail-closed (todas ou nenhuma) + echo do alvo +
|
||
`ALLOW_REMOTE_DB=true` obrigatório para DB remoto (mesmo padrão dos seeds).
|
||
- **R5 — Extensão ≠ conteúdo (row `.jpg` com webp no WP).**
|
||
`ContentType` = o do download (bytes reais decodificam); extensão é cosmética
|
||
no contrato de URL. Mencionado no runbook.
|
||
|
||
## Aceite de engenharia
|
||
|
||
- [ ] Aceite de produto da intenção ainda coberto: 200 público por filename das
|
||
~40 rows, DB intocado, uploads novos intocados, fail-closed mantido
|
||
- [ ] Invariantes AGENTS/engineering-standards: identificadores em inglês;
|
||
guard local de DB reusado; zero access/Consent/transação tocados
|
||
- [ ] Testes de domínio: unit dos helpers puros de `wpArticles.mjs` e da
|
||
resolução row→cover; gates da checklist do AGENTS rodados
|
||
- [ ] Docs: runbook de execução em prod + nota AGENTS.md + changelog
|