docs(plan): S45 — central de conteúdos — cards verticais no catálogo e na seção da home (Related #1410)

docs/plans/central-conteudos-cards-verticais.md

@@ -0,0 +1,125 @@
+# S45 — Central de Conteúdos — cards verticais no catálogo e na seção da home
+
+Status: rascunho
+Atualizado em: 2026-10-01
+Issue: #1410
+Priority: P1
+Impeccable: B — encaixe no slot/card existente, sem rota ou tela nova
+Design UI: docs/plans/central-conteudos-cards-verticais-ui-design.html
+Appetite: ~1–2 dias eng; um outcome verificável — o vertical aparece inteiro e o horizontal também, no catálogo e na seção da home
+Responsável: —
+
+## Intenção
+
+A Central de Conteúdos (`/conteudos`) tem 281 peças publicadas, quase todas vindas do Instagram: Reels em 9:16 e fotos de feed em 4:5. São justamente as formas verticais que o eleitor reconhece e repassa. Mas os cards do board foram desenhados para mídia horizontal — o slot é `aspect-video` (16:9) em todas as superfícies —, então o enquadramento vertical é cortado no `object-cover` e o board parece uma parede de thumbs horizontais, todos iguais.
+
+O pedido é corrigir o enquadramento na Central e na seção dela na home (S39/S42): o card passa a apresentar a peça na forma em que ela respira — vertical é o padrão do board e nunca é cortado; peça genuinamente horizontal aparece inteira, em letterbox na superfície neutra, nunca esticada nem cortada. O board fica honesto: dá para reconhecer o Reel e a foto antes de decidir assistir ou baixar.
+
+## Persona e fluxo
+
+- **Persona / contexto:** eleitor/simpatizante no celular, chegando por link do WhatsApp ou rolando a home; reconhece o material pelo formato (Reel, foto de feed) e decide o que assistir, baixar ou repassar.
+- **Job principal:** reconhecer a peça no formato em que ela foi feita, sem enquadramento cortado que a descaracterize, e escolher o que consumir.
+- **Fluxo desejado:** abre `/conteudos` (ou passa pela seção da home) → vê cada peça na forma real: Reel em 9:16, foto em 4:5, arte de modelo vertical; peça horizontal inteira em letterbox → reconhece e escolhe → toca para reproduzir/baixar como hoje → no detalhe, se a página entrar no escopo, o mesmo enquadramento (coerência card→detalhe).
+- **Anti-goals de produto:** não é redesenho da Central nem da home; não cria rota, tela, player ou galeria; não mexe em filtros, busca, ações, kill switch ou copy; não carrega mídia sozinha; não vira masonry nem grade de altura variável; não puxa dimensão real de mídia (migration/ffprobe) nesta fatia.
+
+### Esboço de fluxo (B)
+
+```text
+[visitante no celular] → /conteudos (ou seção da Central na home)
+→ card da peça na forma em que ela respira
+   ├─ vertical (Reel 9:16 · foto 4:5 · arte de modelo S38 vertical)
+   │     → enquadramento inteiro, nunca cortado
+   ├─ horizontal genuíno → peça inteira em letterbox na superfície neutra
+   │     → nunca esticado, nunca cortado
+   └─ áudio/texto/link → forma decidida pela coerência do board (sem enquadramento a preservar)
+→ itens sintéticos de modelo do S38 seguem a mesma grade (convite para /cards intacto)
+→ toque reproduz/baixa como hoje (mídia só no toque)
+[se a página da peça entrar no escopo] → /conteudos/<slug> com o mesmo enquadramento do card
+[peça despublicada] → some como hoje (kill switch intacto)
+```
+
+### Design UI (B)
+
+- Design UI (gate): `docs/plans/central-conteudos-cards-verticais-ui-design.html` — cenas do catálogo e da seção da home em ~390 e ~1280: card full vertical (vídeo 9:16, foto 4:5), compacto de foto, item de modelo S38 vertical, peça horizontal em letterbox e a grade sem overflow.
+
+## Objetivo e aceite
+
+- No catálogo `/conteudos` e na seção da Central na home, peça vertical aparece no enquadramento vertical recomendado, **nunca cortada** — Reel (9:16) e foto/carrossel (4:5) preservam o que o autor enquadrou.
+- Peça genuinamente horizontal aparece **inteira**, em letterbox na superfície neutra — nunca esticada nem cortada; o board deixa de ser uma parede de thumbs 16:9.
+- Os itens sintéticos de modelo do S38, que dividem a mesma grade, ganham arte vertical para a coerência do board — **sem mudar a semântica de convite para `/cards`** (seguem itens, não peças, sem cromo de mídia).
+- Guardrails: sem rota/tela nova; mídia continua só no toque (sem autoplay); reprodução, download, compartilhar, filtros, busca e copy intocados; kill switch instantâneo intocado; sem analytics nem PII nova; **nenhuma migration/schema/ffprobe decidido aqui** — v1 decide a forma pelo tipo, não pela dimensão real da mídia.
+- Celular primeiro: nenhum overflow horizontal novo (o e2e mede ≤1 px a 390) e nenhuma mídia pesada antecipada.
+- **Decidido no gate:** incluir também a página da peça (`ContentPieceDetail`) no mesmo enquadramento, pela coerência card→detalhe — nada de Issue sucessora.
+- Demais seções da home, shell/nav e ficha interna intocados.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — é enquadramento visual, não número: nenhum contador, série, ranking ou métrica nova.
+- **Decisões desbloqueadas:** o eleitor reconhece a peça no formato real e decide o que consumir; a comunicação passa a ler o board como ele foi publicado (Reel × foto × horizontal). A contagem de circulação segue no mecanismo anônimo existente (C213), sem métrica nova.
+- **Forma:** _adiada ao plano de implementação_ — aqui só a restrição de produto: o formato apresentado é o da própria peça, nunca um recorte inventado.
+
+## Dados da decisão (literais)
+
+- Item `S45`; slug `central-conteudos-cards-verticais`; tipo `feature`; Priority `P1`; Impeccable `B` ("encaixe no slot/card existente, sem rota ou tela nova" — mesmo enquadramento de classe do C226); model `deepseek/deepseek-flash`.
+- Superfícies no escopo: (1) catálogo `/conteudos` — cards de peça full (video/audio/link) e compacto (foto/texto), **e** os itens sintéticos de modelo do S38 que compartilham a mesma grade (coerência do board, sem mudar a semântica de convite para `/cards`); (2) seção da home S39/S42 (`ContentPieceHomeCard`, thumb mobile de 124px e bloco `sm+`).
+- Regra de produto central: o card apresenta a peça na forma em que ela respira — **vertical é o padrão do board; o enquadramento de peça vertical nunca é cortado**. Peças genuinamente horizontais aparecem inteiras (**letterbox na superfície neutra**), nunca esticadas nem cortadas.
+- Formas recomendadas (o designer decide o número final no artefato): vídeo/Reel → **9:16**; foto/carrossel → **4:5**; arte dos itens de modelo S38 → **vertical**; áudio/texto/link não têm enquadramento a preservar — o designer decide a forma pela coerência do board.
+- Sem dado de orientação/dimensão no item público hoje: a v1 decide a forma **pelo tipo**, não pela dimensão real da mídia; se o designer/impl optar por forma adaptativa por dimensão real, isso é decisão de implementação, **não requisito de produto**.
+- Decisão do gate: incluir também o palco da página da peça (`ContentPieceDetail`) no mesmo item, pela coerência card→detalhe (`docs/plans/central-conteudos-cards-verticais-ui-design.html`, cena 05).
+- **Supersessão explícita:** a decisão D5 do C226 ("o slot é 16:9 nas três superfícies", `docs/plans/central-conteudos-preview-frame-video-impl.md:91`) fica **revogada na parte do 16:9**.
+- Relação **#1399 C240** (carrossel como conteúdo de primeira classe, `in-progress`, plano+design commitados, ainda sem código): reescreve os MESMOS arquivos (`contentPieceCatalog.ts`, `ContentPieceCard/Media/Detail`, catálogo/página pública) e seu design usa stage `aspect-video`. S45 **não roda em paralelo com C240** — o registrador grava `serializes: []` e a ordem fica **sem fixação** (decisão do gate): o executor coordena no claim; quem rodar depois porta sobre a base do outro (o design do C240 se ajusta ao palco vertical se o S45 vier primeiro).
+- Relação **#1358 C228** (P3, aberto): é só cromo do mesmo slot (play 68px, acentos, badge) e o body manda fechá-lo antes de mexer no `ContentPieceMedia`. Para o S45, **C228 não bloqueia** (cromo ≠ ratio); o executor deve saber que ele existe e não puxar o cromo para dentro desta fatia.
+- Fora de escopo (literal): galeria multi-mídia do C240; cromo do C228; imagem OG; filtros/busca/ações/kill switch/copy; ficha interna da assessoria; acervo/outras verticais; redesenho do shell/nav/home além do card da seção.
+
+## Direção no codebase (hipótese)
+
+- **Cards hoje:** `ContentPieceCard.tsx:99-129` compacto (foto/texto/outro) com thumb `h-24 w-32`; `:132-162` card full com `ContentPieceMedia className="aspect-video"` (`:143`). `ContentPieceCatalog.tsx:47-53` divide large (video/audio/link) vs compact (image/text/other); grids `sm:grid-cols-2 lg:grid-cols-3` (`:67`) e `sm:grid-cols-2` (`:79`). `ContentPieceHomeCard.tsx:74-87`: mobile `grid-cols-[124px_1fr]`, mídia `aspect-video self-start` (`:86`); `ContentPieceHomeBoard.tsx:241-245` grade `sm:grid-cols-2 lg:grid-cols-3`. `ContentCatalogCardItem.tsx:23-58,68-109`: arte `min-h-40 sm:aspect-video` (`:26`) e `grid-cols-[128px_1fr] sm:block` (`:75`).
+- **Slot de mídia:** `ContentPieceMedia.tsx:110-126` — o slot não tem aspecto próprio; o host passa a classe. Imagem `object-cover` (`:190`), frame de vídeo `object-cover` (`:277`), vídeo em play `object-contain` (`:235`). Usado por catálogo, card da home e página da peça (`ContentPieceDetail.tsx:53-61`, slot `aspect-video` em `:60`).
+- **Sem dado de orientação:** `ContentPiecePublicItem` (`contentPieceCatalog.ts:364-404`) não tem width/height; `ContentPiecePublicFile` (`:406-411`) só id/path/mimeType/downloadFilename; `mediaOf` (`:672-680`) descarta `url/thumbnailURL/width/height`. O DB tem dims só para imagem (`src/payload-types.ts:1398-1399`; sharp em `payload.config.ts:188`), mas o VM descarta; vídeo não tem dims em lugar nenhum (sem ffprobe). O frame do C226 preserva o aspecto com ffmpeg `scale=640:-2` (`contentPieceFrame.ts:102`) e o VM só expõe `framePath` (`contentPieceCatalog.ts:757-763`), nunca dims.
+- **Precedentes visuais verticais:** `CampaignStorySection.tsx:50-52` (`aspect-[9/16]`, `max-w-[420px] lg:max-w-[300px]`); reels internos `ReelLibraryCard.tsx:13`/`ReelPlayer.tsx:12,26` (`aspect-[9/16]`); home S3 `CampaignContentCard.tsx:16-17,44` (`coverAspect 'video'|'square'`); `/fotos` `ArchivePhotoCard.tsx:37` (`aspect-square sm:aspect-[4/3]`); `/cards` `CardModelTile.tsx:16,44-45` usa spacer in-flow (bug WebKit com aspect-ratio); modelos verticais em `cardModels.ts:90-161` (1080×1440, 1000×1440, 1080×1920).
+- **Evidência do volume:** 281 peças publicadas, todas Instagram (`docs/changelog/2026-10-01-c230-prune.md:1`); Reels = vídeo e feed = foto pelo MIME (`contentPiece.ts:248-264`); stories nunca entram (C230). Não há medição de proporção vertical×horizontal no repo.
+- **Testes a respeitar:** `tests/e2e/frontendConteudos.e2e.spec.ts` (contagens `article[data-content-piece]`, frame antes/depois do play `:342,360`, seção da home `:745-805`, overflow ≤1 em 390, bounding boxes `:908-912`; frame stubado 320×180 `:212-224`); units `contentPieceMedia.unit.spec.tsx`, `contentPieceHomeSelection.unit.spec.ts:84-108` (pina keys da projeção lean — não engordar), `contentPieceCatalog.unit.spec.ts`; manifesto e2e já cobre `components/conteudos`/`(home)`/`conteudos` (`scripts/lib/e2e-affected-manifest.mjs:170-201`).
+- **Risco de acoplamento:** o slot `ContentPieceMedia` é compartilhado (catálogo, home, detalhe) — o ratio vale para os hosts atuais e futuros; C240 reescreve os mesmos arquivos; os bounding boxes do e2e e o frame stub 320×180 podem acusar a mudança de ratio; não editar as seções irmãs da home.
+
+## Dependências
+
+- Nenhuma dura — catálogo (S27/S28), itens de modelo (S38), seção da home (S39/S42) e frame do C226 já estão no repo.
+- **#1399 C240** — relação registrada acima: serializa (ordem sem fixação; coordenação no claim); sem código ainda. **#1358 C228** — não bloqueia (cromo ≠ ratio); ciência do executor.
+- Design UI aprovado no gate.
+
+## Fora de escopo
+
+- Galeria multi-mídia do C240 e a promoção de carrossel a conteúdo de primeira classe.
+- Cromo do C228 (play 68px, acentos radiais, badge, sombra) e qualquer polimento visual do slot.
+- Imagem OG; filtros, busca, ações, kill switch e copy; ficha interna da assessoria.
+- Acervo de falas e outras verticais internas; redesenho do shell/nav/home além do card da seção.
+- Forma adaptativa por dimensão real de mídia (migration/ffprobe) e qualquer mudança de schema.
+
+## Rabbit holes de produto
+
+- **"Já que verticaliza, redesenha a Central inteira".** Se alguém "só completar": novo board, nova hierarquia, header, filtros. **Corte neste item:** só o enquadramento dos cards e a grade existentes.
+- **"Masonry/altura variável por peça".** Se alguém "só completar": layout novo, colunas quebradas, e2e de overflow refeito. **Corte:** grade atual, uma forma por tipo de peça.
+- **"Detecta a dimensão de toda mídia agora".** Se alguém "só completar": migration de width/height, ffprobe no acervo, backfill. **Corte:** v1 decide pelo tipo; adaptativa é decisão de implementação futura, não requisito.
+- **"Cover em tudo para o board ficar uniforme".** Se alguém "só completar": corta o vertical para preencher o slot e destrói o pedido. **Corte:** vertical inteiro; horizontal em letterbox.
+- **"Autoplay no card para aproveitar o formato".** Se alguém "só completar": vídeo carregando no board, quebra do contrato do S27. **Corte:** mídia só no toque, como hoje.
+
+## Questões em aberto (produto)
+
+- **Forma por tipo ou adaptativa pela dimensão real da mídia?** **Decidido no gate:** **A** — por tipo na v1 (vídeo 9:16, foto 4:5, arte de modelo 3:4); adaptativa por dimensão real vira decisão de implementação posterior, sem migration/ffprobe nesta fatia.
+- **Foto compacta continua linha ou vira card vertical cheio?** **Decidido no gate:** **A** — mantém a linha compacta e corrige o enquadramento do thumb (96×120, 4:5), preservando a leitura de varredura do board.
+- **A página da peça entra no mesmo item?** **Decidido no gate:** **A** — sim, `ContentPieceDetail` com o mesmo palco vertical (coerência card→detalhe; cena 05 do artefato).
+- **Onde ficam as ações no card vertical?** **Decidido no gate:** **A** — abaixo da mídia, como hoje; mantém os alvos de toque do S27.
+- **Áudio e link ficam verticais ou largos?** **Decidido no gate:** **B** — permanecem largos (não há enquadramento a preservar); decisão fechada no artefato.
+
+## Referências
+
+- GitHub Issue — a registrar (`pnpm agent:register`).
+- Design UI (gate): `docs/plans/central-conteudos-cards-verticais-ui-design.html`.
+- Planos irmãos: `central-conteudos-publica.md` (S27) · `central-conteudos-cards-no-catalogo.md` (S38) · `central-conteudos-secao-home.md` (S39) · `central-conteudos-secao-home-share-filtro.md` (S42) · `central-conteudos-preview-frame-video.md` e `-impl.md:91` (C226, D5 superseded na parte do 16:9) · `central-conteudos-carrossel.md` (C240, #1399).
+- Arquivos-pista: `src/components/conteudos/ContentPieceCard.tsx:99-162` · `ContentPieceCatalog.tsx:47-79` · `ContentPieceHomeCard.tsx:74-87` · `ContentPieceHomeBoard.tsx:241-245` · `ContentCatalogCardItem.tsx:23-109` · `ContentPieceMedia.tsx:110-277` · `ContentPieceDetail.tsx:53-61` · `src/lib/contentPieceCatalog.ts:364-411,672-680,757-763` · `src/components/campaign/.../CardModelTile.tsx:16,44-45` e `src/lib/cardModels.ts:90-161`.
+- Testes: `tests/e2e/frontendConteudos.e2e.spec.ts:212-224,342,360,745-805,908-912` · units de `contentPieceMedia`/`contentPieceHomeSelection`/`contentPieceCatalog` · `scripts/lib/e2e-affected-manifest.mjs:170-201`.
+- `AGENTS-public.md` — convenções do site público (mídia, cache, kill switch).
+
+## Self-score (shaping)
+
+**5/5** — (1) fatia = um outcome verificável (vertical inteiro, horizontal em letterbox, no catálogo e na home); (2) appetite ~1–2 dias cabe: enquadramento no slot/cards existentes, sem rota, tela ou migração; (3) persona/job/aceite em linguagem de produto, com a regra central e os guardrails; (4) direção no codebase é hipótese, com achados e precedentes citados como pista; (5) zero decisão dura de engenharia — sem schema/migration/ffprobe, com as cinco dúvidas de produto posicionadas e as relações C240/C228 registradas.