diff --git a/docs/changelog/2026-09-18-c194.md b/docs/changelog/2026-09-18-c194.md new file mode 100644 index 00000000..2deb0817 --- /dev/null +++ b/docs/changelog/2026-09-18-c194.md @@ -0,0 +1 @@ +**C194 — Biblioteca de reels na vertical Comunicação (2026-09-18):** a assessoria produzia os Reels de tutorial fora do Teqo e não tinha onde se servir do material pronto; o C193 registrou o modelo e os arquivos privados, e o C194 entregou a biblioteca. (1) **Lista** em `/campanha/comunicacao/reels` — grid de capas 9:16 (o card inteiro é o link), só `published`, ordenada por `-publishedAt`, com paginação pelo shell do sistema de listas e vazio honesto ("a produção acontece fora desta tela"); loader próprio `src/utilities/reels/reelPageData.ts` (Local API `overrideAccess:false` + `user`, `select` enxuto) e URL `src/utilities/reels/reelListUrl.ts` (só `page`). (2) **Detalhe** em `/campanha/comunicacao/reels/[id]` — player 9:16 (`video-audio ?? video`, time nativo), painel de downloads (CTA primário "Baixar vídeo sem áudio" com `?download=1`; vídeo com áudio, mp3 e `.srt` como linhas quando existem, com motivo honesto quando não) e transcrição/roteiro em texto com copiar (owner `copyFeedback` parametrizado por assunto) — sem duração (o modelo não tem campo; a decisão visual foi adaptada pelo `designer`, tier primário). (3) **Kill switch** no detalhe: `POST .../reels/[id]/publicacao` via `campaignJsonMutationRoute` + `setReelPublishedForActor` (gate fresco do papel, update único, sem transação, hook do C193 re-carimba `publishedAt`); despublicar tira da lista e bloqueia player/downloads na tela com "Republicar" no lugar (a rota de mídia do C193 responde 404 a `draft`/`unpublished` — decisão B herdada, sem link morto), e a transcrição (texto, não mídia) permanece legível. (4) **Acesso**: só `communicator`/`coordinator`/`candidate` (fail-closed; `advisor`/`leader` redirecionados, rota de mutação com mensagem de domínio própria). (5) **Fiação**: 3º sub-item "Reels" da vertical no `nav.ts` (teste do pin atualizado), rule da lista no `campaignPageChrome.ts` (o detalhe resolve chrome próprio), paths em `campaignPaths.ts`, e o rename mecânico do gate `speechCatalog` → `communicationCatalog` (dono `campaignPageActor.ts`; inclui a referência que o C193 deixou passar em `speechPageData.ts`, que quebrava o typecheck do `main`). (6) **Sem migration, sem Consent, sem `Media.read`/rota do C193 tocados, site público e cards idênticos.** (7) **Testes**: unit de view models (arquivos bloqueados fora de `published`, capa/alt, publicação), nav/chrome/gate; int do loader (lista só publicados e ordenada, matriz de papéis, detalhe em qualquer status, `ReelNotFoundError`) e do kill switch (despublicar não apaga, republicar re-carimba `publishedAt`, negado/inexistente); e2e novo `campaignReel` (HTTP: lista/detalhe/download, anônimo 404, unpublish sem lista e sem mídia, republicar volta, advisor/leader negados) mapeado no manifest. `pnpm gate:fast` verde + e2e local do spec novo e das mesmas superfícies (cortes/acervo) verdes. diff --git a/docs/plans/c201-typecheck-main-impl.md b/docs/plans/c201-typecheck-main-impl.md new file mode 100644 index 00000000..35e20428 --- /dev/null +++ b/docs/plans/c201-typecheck-main-impl.md @@ -0,0 +1,77 @@ +# Impl: C201 — Typecheck da main quebrado após C192×C193: import órfão de canReadSpeechCatalog + +Status: aprovado +Atualizado em: 2026-09-18 +Issue: #1169 +Intenção: body da Issue (sem plano linkado — o body é a spec) +Appetite restante: herdado (P1 de fix mecânico — ~5 min de execução; o custo real é a verificação) + +## Leitura da intenção + +- **Outcome:** `main` volta a passar typecheck e o pipeline de deploy volta a publicar; zero referências ao predicado antigo `canReadSpeechCatalog` em `src/`/`tests/`/`scripts/`; #1169 fechada como `done`+`in-prod` com o registro do commit que consertou. +- **O que NÃO negociar:** o fix já está em `main` (`c7d1fd29`) e altera exatamente as 2 referências de `src/utilities/speech/speechPageData.ts` (import :5 + uso :187) para `canReadCommunicationCatalog`; a semântica do predicado é preservada (`communicator || unrestricted` — coordinator/candidate — em `src/lib/campaignRoles.ts:27`); histórico/migrations não se editam retroativamente; fail-closed de acesso intacto. +- **O que reavaliar:** a premissa implícita "há diff a produzir" não se aplica — HEAD == origin/main == `c7d1fd29` (branch idêntica ao main). O desfecho desta sessão é **verificação + fechamento do tracker**, sem PR. + +## Abordagem recomendada + +```mermaid +flowchart LR + C193["C193 bdaf3c7c: renomeia predicado
canReadSpeechCatalog → canReadCommunicationCatalog"] --> QUEBRA["verify do deploy falha TS2305"] + C192["C192 45eef25b: importa nome antigo
speechPageData.ts:5 e :187"] --> QUEBRA + QUEBRA --> FIX["fix c7d1fd29 em main
import :5 + uso :187 no nome novo"] + FIX --> F1["F1 gate local no HEAD
pnpm gate:fast = lint + typecheck + unit"] + FIX --> F2["F2 observar run 35398929341
verify → deploy-staging (deadline ~60 min)"] + F2 --> F3["F3 smoke staging read-only
/campanha/comunicacao/acervo → login, não 500"] + F1 --> F4["F4 fechar #1169
done + in-prod, remove in-progress,
comentário com commit/run"] + F3 --> F4 +``` + +**Opções consideradas:** A | B | C + +**Recomendação:** **C — sessão de verificação no HEAD** (`c7d1fd29`): rodar `pnpm gate:fast` local, observar o run de deploy `35398929341` (`verify` → `deploy-staging`), smoke de staging read-only na rota da vertical e fechar #1169 no tracker citando commit + run. É a única opção compatível com o estado real do repositório (diff-zero) e fecha o ciclo P1 sem inventar trabalho. + +**Rejeitadas:** **A — refazer o fix numa branch nova + PR:** o commit já está em `main`; um PR sem diff é inválido e o auto-merge não teria o que mergear (e o flip pós-merge não roda sem PR). **B — reverter/re-aplicar por rebase:** não há divergência — HEAD == origin/main == `c7d1fd29`; rebase de branch idêntica é no-op e só arrisca reescrever histórico. + +### Componentes / mudanças + +- **Código:** nenhuma mudança nesta sessão. O fix integral está em `src/utilities/speech/speechPageData.ts` (:5 import, :187 uso de `canReadCommunicationCatalog`); o predicado renomeado vive em `src/lib/campaignRoles.ts:27`. +- **Referências órfãs:** busca em `src/`, `tests/` e `scripts/` não encontra mais `canReadSpeechCatalog` (apenas docs históricos); nenhum outro órfão do rename do C193 entre importadores de `@/lib/campaignRoles`. +- **Changelog:** já registrado em `docs/changelog/2026-09-18-c193-fix-rename.md` (`pnpm gate:fast` verde — 364 arquivos / 3867 testes — e int `speechAcervo`/`reel` 22 verdes no commit do fix). +- **Artefatos desta entrega:** este plano + o registro de fechamento na Issue #1169 (comentário com commit/run/desfecho). +- **Migration:** sem migration (rename de símbolo, sem mudança de schema). +- **Access / Consent:** sem Consent e sem mudança de access — a matriz de papéis segue coberta pelos int existentes (`tests/int/speechAcervo.int.spec.ts:329,408` — inclui "never expands outside the catalog gate" —, `speechCatalog.int.spec.ts:123`, `speechExcerpts.int.spec.ts:135`, `reel.int.spec.ts`). +- **UI:** sem UI nova — nenhuma superfície muda; a rota `/campanha/comunicacao/acervo` é a mesma (só o gate interno renomeado). + +### Dados → forma (se aplicável) + +Não aplicável: nenhuma forma de dado nova ou alterada — a mudança é só o identificador do predicado (rename já aplicado). + +## Fases verificáveis + +1. **Gate local no HEAD (`c7d1fd29`)** — `pnpm gate:fast` (lint + `typecheck` + `test:unit`) deve sair verde (o typecheck era o job vermelho por TS2305). Unit relevantes como sinal direto: `tests/unit/campaignNav.unit.spec.ts:68`, `tests/unit/aiToolsScope.unit.spec.ts:37`. Evidência: saída verde do comando. +2. **Observar o run de deploy `35398929341` (HEAD `c7d1fd29`)** — `preflight` já success, `verify` in_progress; acompanhar até `verify` success e `deploy-staging` publicar o SHA. Deadline de observação ~60 min do `createdAt`; não intervir (sem cancelar/re-dispatch) salvo falha real. +3. **Smoke de staging (read-only)** — `https://staging.jorgesolla1313.com.br/campanha/comunicacao/acervo` **sem sessão** deve redirecionar ao login (não 500); conferir também que a página de login responde. Nenhuma escrita, nenhuma credencial de campanha. +4. **Fechar a Issue #1169** — labels `done` + `in-prod`, remover `in-progress`; comentário citando o commit `c7d1fd29`, o run `35398929341` e o desfecho do smoke; `gh issue close 1169`. Sem PR, o fechamento é manual (o flip `issue-done-on-main-merge` depende de PR, que não existe neste caso). + +## Rabbit holes / Não escopo (engenharia) + +- Recriar o fix em branch nova/PR vazio (opção A) ou rebase/re-aplicação (opção B): rejeitados no gate — diff-zero. +- Rodar e2e full local: fora — o `verify` do deploy já roda a suíte full uma vez por commit; rodar de novo localmente não acrescenta sinal. +- Reauditar a série C192/C193 inteira ou caçar outros órfãos de rename: verificado zero remanescentes; expandir sem evidência é custo puro. +- Mexer em `deploy.yml`/preflight/requeue ou aprovar `deploy-production` nesta sessão: fora — produção tem required reviewer (decisão humana) e não é critério da C201. +- Editar o body/plano da Issue (spec) ou o changelog do fix: imutáveis. + +## Riscos e mitigação + +- **Run falha por motivo alheio (flake/infra, ex.: e2e conhecido ou runner offline)** → reportar como observação e **não** tratar como regressão da C201; distinguir pelo arquivo/job que falhou (nada do run toca o rename além do typecheck que já passou no commit). +- **Fechamento manual do tracker sem PR** → exige citar commit + run no comentário; não fechar como `in-prod` antes do staging publicado; nunca deixar `in-progress` residual. +- **`deploy-staging` estoura timeout / runner indisponível** → infra: vira observação (file-miss), não defeito; `done` ainda pode ser registrado com o verify verde, `in-prod` só com staging verde. +- **Deadline ~60 min** → se o run ainda estiver `in_progress` ao estourar, aguardar/observar sem intervir; registrar o estado real no comentário da Issue. + +## Aceite de engenharia + +- [ ] Aceite de produto da intenção ainda coberto (typecheck de `main` verde; vertical de comunicação operacional em staging) +- [ ] Invariantes AGENTS/engineering-standards (sem edição retroativa de migrations/histórico, sem force-push, rename já aplicado no dono do símbolo) +- [ ] Testes de domínio previstos (unit/int) onde access/write paths mudam — não mudam; matriz de papéis re-validada pelo gate local e pelos int existentes da vertical +- [ ] Evidência esperada: saída verde do `pnpm gate:fast` local no HEAD + job `verify` success do run `35398929341` + smoke de staging (redirect ao login, sem 500) + #1169 fechada com comentário commit/run +- [ ] Self-score decision-quality: 4/5 (C é a única opção com diff-zero; rejeitadas nomeadas; rabbit holes e riscos de infra delimitados) diff --git a/docs/plans/reels-biblioteca-impl.md b/docs/plans/reels-biblioteca-impl.md new file mode 100644 index 00000000..5d199d04 --- /dev/null +++ b/docs/plans/reels-biblioteca-impl.md @@ -0,0 +1,102 @@ +# Impl: Biblioteca de reels na vertical Comunicação + +Status: aprovado +Atualizado em: 2026-09-18 +Issue: #1153 +Intenção: docs/plans/reels-biblioteca.md +Appetite restante: herdado (~1–2 dias eng; lista + detalhe + kill switch verificáveis com fixtures) + +## Leitura da intenção + +- **Outcome:** `/campanha/comunicacao/reels` lista os reels **publicados** (capa 9:16 + título), o detalhe abre o reel em 9:16 e oferece os arquivos disponíveis (vídeo sem áudio primário, vídeo com áudio, mp3, `.srt`, transcrição) para a assessoria trabalhar fora do site; despublicar tira da lista sem apagar e republicar reativa; acesso só a `communicator`/`coordinator`/`candidate`, fail-closed. +- **O que NÃO negociar:** arquivos privados (rota C193 é a única porta; `Media.read` intocado); nada de publicação/edição de vídeo na UI; nenhum reel some por acidente (kill switch reversível); sem busca/filtros no MVP (`-publishedAt`); sem `Consent` novo; sem migração (C193 fechou o modelo). +- **O que reavaliar:** a recomendação A da intenção para o link direto do despublicado **conflita com o C193 (decisão B, mergeada)** — vale B: `draft`/`unpublished` não servem mídia; o detalhe interno continua abrindo, mas sem player/downloads. Verifiquei que o regex `/acervo/[^/]+` do chrome (`campaignPageChrome.ts:297`) **não** engole `/reels` (só falta a rule da lista). O conflito C184 (#1106) **não foi mergeado** (commit docs-only) — prosseguir. Os defers do C193 (`reelMediaPath`/`isReelStatus`) têm gatilho explícito neste item. + +## Abordagem recomendada + +```mermaid +flowchart TD + L["Lista /campanha/comunicacao/reels"] -->|"loadReelLibraryPageData · status=published · sort -publishedAt"| DB[("reel + reelMedia (depth 1)")] + D["Detalhe /campanha/comunicacao/reels/:id"] -->|"loadReelDetailPageData · qualquer status"| DB + D --> P["Player 9:16 + painel de downloads"] + P -->|"video-audio ?? video · ?download=1"| M["GET .../media/kind — rota C193: só published"] + D --> K["ReelPublicationPanel"] + K -->|"POST .../publicacao"| A["setReelPublishedForActor: gate fresco + update único"] + A --> DB +``` + +**D1 — Dados da página. Opções: A | B | C — Recomendação: A.** Loader em `src/utilities/reels/reelPageData.ts` (`server-only`, `overrideAccess: false, user`, select enxuto), view models puros no dono do vocabulário `src/lib/reel.ts` (como `lib/speechCut.ts` faz) e URL curta em `src/utilities/reels/reelListUrl.ts` (só `page`, reusando `campaignListUrl`). Rejeitadas: **B** query inline nos `page.tsx` (espalha o where do kill switch e mata o int sem HTTP); **C** top-level `src/utilities/reelPageData.ts` (top-level é pinado por `codebaseConventions.unit.spec.ts`; a subpasta `utilities/reels/` já é o dono criado no C193). + +**D2 — Render da lista. Opções: A | B | C — Recomendação: A.** Grid RSC de capas 9:16, todo o card é um `` (sem ilha cliente), com os shells de lista (`CampaignPageShell`, `CampaignListPendingBoundary/Results`, `CampaignListEmptyState`, `CampaignListFooter`). Rejeitadas: **B** `CampaignTable` (o sistema de listas é de tabela; o design é capa-led e o job é varrer por capa/título); **C** busca/filtro/sort toggle no MVP (produto recomenda A; ordem fixa `-publishedAt`). + +**D3 — Transporte do kill switch. Opções: A | B | C — Recomendação: A.** `POST .../reels/[id]/publicacao` com `campaignJsonMutationRoute` + `setReelPublishedForActor` em `src/app/(campaign)/campanha/actions/reels.ts` (gate fresco `canReadCommunicationCatalog`, find ator-escopado, **um** `payload.update`); painel cliente com `useState` pending + `postCampaignJson` + `router.refresh()` (precedente `SpeechCutPublicationPanel.tsx:42-65`, regra `campanha-action-feedback`). Rejeitadas: **B** server action + `
` (a superfície é botão com AlertDialog, não form; o wrapper JSON é convenção estrutural — `codebaseConventions` recusa `POST` fora dele); **C** REST direto `/api/reel/:id` (pula o gate fresco do ator e a mensagem de domínio; wire divergente). + +**D4 — Detalhe de reel não publicado. Opções: A | B | C — Recomendação: A.** Detalhe abre para `draft`/`unpublished` (leitura permitida), **sem** player/downloads e sem nenhum href de mídia; aviso "fora da lista" com copy adaptada (arquivos guardados, sem acesso até republicar) e painel com "Publicar" (draft) / "Republicar" (unpublished). Rejeitadas: **B** detalhe 404 para não publicado (mataria o kill switch reversível da própria tela, contra o aceite); **C** player mesmo despublicado (contraria o C193 B mergeado — tocar prometeria arquivo que o servidor nega; link morto). + +### Componentes / mudanças + +- **`src/lib/reel.ts`** (editar): `ReelLibraryItemViewModel`/`ReelDetailViewModel` + `toReelLibraryItemViewModel`/`toReelDetailViewModel` (labels de `reelStatusLabels`/`reelFeatureLabels`, `publishedAtLabel`, disponibilidade por artefato, `coverAlt`); passa a consumir `reelMediaPath` (player/capa/downloads). **Cleanup do defer C193:** se ao merge `isReelStatus` seguir sem call site de produção, apagá-lo + o pino em `tests/unit/reel.unit.spec.ts`. +- **`src/lib/campaignPaths.ts`** (editar): `CAMPAIGN_COMMUNICATION_REELS`, `campaignReelDetailHref(id)`, `campaignReelPublicationHref(id)`. +- **`src/lib/schemas/reel.ts`** (novo): `reelPublicationRequestSchema` (`reelId: positiveRelationshipId`, `published: z.boolean()`) e `REEL_FORBIDDEN_MESSAGE` ('Você não tem acesso à biblioteca de reels.' — literal próprio do domínio; NÃO reusar o "acervo de falas"), `REEL_NOT_FOUND_MESSAGE`, `REEL_GENERIC_ERROR_MESSAGE`. +- **`src/utilities/reels/reelListUrl.ts`** (novo): `parse/serialize/resolve` só de `page` (canônico via `resolveListUrl`), `buildReelListHref`, `REEL_PAGE_SIZE = 24`. +- **`src/utilities/reels/reelPageData.ts`** (novo): `loadReelLibraryPageData` (where fixo `{ status: { equals: 'published' } }`, `sort: '-publishedAt'`, depth 1, select título/feature/status/cover/publishedAt) e `loadReelDetailPageData` (qualquer status; `ReelNotFoundError` → `notFound()` na página; depth 1). +- **`src/utilities/campaignPageActor.ts`** (editar): rename mecânico do gate `'speechCatalog'` → `'communicationCatalog'` (tipo + doc + condição). **Verificado:** 7 chamadas em 6 páginas (`comunicacao/page.tsx:12`, `acervo/page.tsx:34`, `acervo/[id]/page.tsx:36,52`, `cortes/page.tsx:35`, `cortes/[id]/page.tsx:37,57`) + comentários (`actions/speech.ts:265`, `tests/e2e/fixtures/campaignHttpTest.ts:125`). +- **`src/app/(campaign)/campanha/actions/reels.ts`** (novo): `setReelPublishedForActor` — schema parse, `getCampaignActionContext`, gate fresco por role, `payload.find` ator-escopado (não encontrado → `REEL_NOT_FOUND_MESSAGE`), `payload.update({ status: published ? 'published' : 'unpublished' })`. **Sem transação** (uma coleção/um documento; o hook `stampReelPublishedAt` re-carimba `publishedAt` — `Reel.ts:51-59`); mesmo precedente `speech.ts:297-320`. +- **Rotas novas** em `src/app/(campaign)/campanha/(app)/comunicacao/reels/`: `page.tsx` (lista; `campaignPageMetadataFromCatalog('reels')`; `requireCampaignPageActor({ gate: 'communicationCatalog' })`), `[id]/page.tsx` (detalhe: chrome próprio, `ReelStatusBadge`, `ReelPlayer`, `ReelDownloadPanel`, `ReelTranscriptCard`, `ReelPublicationPanel`), `[id]/publicacao/route.ts` (`POST` via `campaignJsonMutationRoute` + `safeMessages`), `[id]/types.ts` (`ReelPublicationResponse`). +- **`src/components/campaign/reels/`** (novos): `ReelLibraryList.tsx`, `ReelLibraryCard.tsx` (capa via `` apontando à rota C193 — **não** usar `next/image` otimizado: o otimizador busca a fonte server-side sem o cookie `campaign-token` e receberia 404), `ReelStatusBadge.tsx`, `ReelPlayer.tsx` (`