teqo-backup/docs/plans/ops52-media-recuperar-arquivos.md

6.6 KiB
Raw Blame History

OPS52-media — Recuperar os arquivos de media de produção (capas dos artigos)

Status: registrado Atualizado em: 2026-08-18 Issue: #10 Priority: P1 Model: cursor-grok-4.5-medium Impeccable: A — N/A (sem mudança de UI; a seção renderiza certo) Rascunho UI: N/A — sem UI Appetite: ~0,5–1 dia eng; um outcome verificável Responsável: —

Intenção

Entregamos a seção de conteúdos (artigos) na home de campanha (S1, 2026-08-17) e as capas dos artigos não carregam — nem na seção nova, nem nas páginas de artigo. O diagnóstico aponta para um débito pré-existente à migração Blob→Garage (OPS52): as 40 rows da collection media (capas dos ~39 posts) têm URL relativa /api/media/file/<filename> e o arquivo não existe em lugar nenhum (disco perdido, bucket Garage vazio, sem objetos no Blob com essas chaves). O contrato de URL está certo — o Payload serve /api/media/file/<filename> pelo proxy do storage (comprovado no código do Payload 3.82 + OPS52) — só falta o arquivo no bucket de produção para a URL resolver. A seção S1 apenas tornou o problema visível na home; o site público está com imagens quebradas na reta final da eleição.

Persona e fluxo

  • Persona / contexto: visitante da home de campanha (celular, meio de funil) vendo a seção "Acompanhe de perto" sem capas; editor abrindo artigo sem imagem; quem executa (dev/ops) recuperando arquivos.
  • Job principal: capa de todo artigo carrega no site público.
  • Fluxo desejado: visitante rola a home → vê cards com capa → abre o artigo → capa e corpo renderizam; editor sobe conteúdo novo e a capa nova aparece.
  • Anti-goals de produto: NÃO reescrever URLs públicas em massa; NÃO trocar o contrato de URL (relativa via proxy) que o OPS52 definiu; NÃO inventar placeholder "em breve" em card sem imagem.

Esboço de fluxo (A — sem UI)

[home S1: card sem capa hoje] → [arquivo restaurado no bucket prod] → [GET /api/media/file/<filename> → 200]
→ [cards com capa; artigo renderiza] → [uploads novos seguem funcionando pelo mesmo proxy]

Objetivo e aceite

  • As ~40 capas de media de produção resolvem: GET https://jorgesolla1313.com.br/api/media/file/<filename> retorna 200 com a imagem para todas as rows (verificação por curl/script, uma por filename).
  • A seção S1 da home e as páginas de artigo exibem as capas; nenhum erro de imagem no console do navegador.
  • As rows da collection media não mudam de URL nem são recriadas sem necessidade — o contrato relativo já é o que o proxy serve; se o executor recriar rows, precisa preservar os filename (chave determinística <slug>.<ext> do seed) para as URLs continuarem resolvendo.
  • Uploads novos (admin, seed, atividades) continuam servindo pelo mesmo proxy (sem regressão).
  • Fail-closed mantido: sem credencial S3 válida, nenhum upload/escrita no bucket — nunca gravar em storage errado.
  • Zero mudança de schema/migration/Consent; nenhuma collection nova.

Dados (intenção)

  • Vou apresentar dados? Não — são imagens, não métricas.
  • Decisões desbloqueadas: nenhuma de produto nova (quem decide "o quê" já está no aceite; a fidelidade da capa é a Q1).
  • Forma: N/A.

Direção no codebase (hipótese)

  • Áreas prováveis: scripts/seed-posts.mjs (ensureCoverMedia — precedente de upload determinístico <slug>.<ext>, idempotente por filename); bucket de produção Garage teqo-media (env S3_* do ~/stack/teqo-1313.env); sem mudança esperada em src/payload.config.ts/src/utilities/mediaStorage.ts (contrato já comprovado).
  • Precedente a olhar: Issue #3/OPS52 (decisão A→B: bucket privado + proxy /api/media/file); docs/plans/ops52-blob-vercel-para-garage.md e -impl.md (prova de contrato PUT/GET/DELETE e runbook do bucket).
  • Risco de acoplamento: a execução escreve no bucket de produção — ferramenta de reconciliação deve ser explícita sobre o alvo (nunca rodar contra bucket/ambiente errado; o guard de DB local não cobre bucket); a fonte primária dos arquivos é o WordPress de origem (jorgesolla.com.br — o mesmo fetch do seed), com o Vercel Blob store (chaves determinísticas) e dumps antigos como fontes secundárias. Nenhuma PII envolvida (imagens públicas).

Dependências

  • OPS52 (concluído — storage real definido e deployado). Nenhuma outra.

Fora de escopo

  • Deletar objetos/contas do Vercel Blob (fica para depois do cutover estável — já anotado no OPS52).
  • Tornar o bucket público, CDN ou otimização/redimensionamento de imagem.
  • Retrabalho da seção S1 ou das páginas de artigo (a UI renderiza certo; o problema é a media).
  • Outros storages ou coleções além de media.

Rabbit holes de produto

  • Reescrever URLs das 40 rows no banco. Se alguém "só completar": reescrita em massa desnecessária e frágil — o contrato relativo já é o que o proxy serve. Corte: arquivo no bucket com a chave certa resolve a URL; DB intocado.
  • Caçar arquivos em dumps antigos. O Postgres não guarda bytes de media (Payload armazena no storage), então dump não tem as imagens. Corte: WordPress é a fonte primária (o seed prova o fetch ao vivo); Blob store secundário.
  • "Consertar" a seção com placeholder/imagem fake. Card sem capa degrada para a banda cinza já existente — não inventar imagem nem texto "em breve". Corte: restaurar o máximo possível e registrar as exceções reais.

Questões em aberto (produto)

  • Prioridade: subir de P2 para P1? O defeito é visível no site público (home S1 + artigos) na reta final da eleição. Recomendação: P1. (assumido — validar)
  • Fidelidade da capa restaurada? Opções: A) capa atual do WordPress de origem para cada post (mesma fonte do seed — o que o público já conhece) | B) aceitar qualquer imagem disponível. Recomendação: A — restauração fiel à origem, com registro das raras exceções. (assumido — validar)
  • E se alguma capa não for recuperável? Opções: A) card sem imagem (degradação existente: banda cinza) | B) placeholder. Recomendação: A — honesto e já implementado. (assumido — validar)

Referências

  • Forgejo Issue #10 (OPS52-media, ready) e #3 (OPS52, concluído)
  • docs/plans/ops52-blob-vercel-para-garage.md / -impl.md (contrato do proxy, runbook do bucket)
  • scripts/seed-posts.mjs (ensureCoverMedia — upload determinístico e idempotente)
  • src/collections/Media.ts, src/utilities/mediaStorage.ts (fail-closed S3_*)
  • AGENTS.md §Media/OPS52 (estado de produção: bucket teqo-media, endpoint tailnet, proxy /api/media/file)