O validate de itemId em social-feed-settings lia data.platform (doc inteiro, sempre undefined) e nunca validava ID de vídeo em produção. Agora lê siblingData.platform via helper validateExcludedItemId. Stub YouTube ganha ids de 11 chars e o spec acompanha, destravando o e2e do describe 'Campaign home content section'. Sem migration.
10 KiB
Impl: S2-FOLLOWUP: validate do itemId (excludedItems) do YouTube e co
Status: rascunho Atualizado em: 2026-08-24 Issue: #775 Intenção: docs/plans/s2-followup-validate-itemid-excludeditems-youtube.md Appetite restante: herdado — item pequeno de follow-up, P2
Leitura da intenção
- Outcome: o
validatedo campoitemIddo arrayexcludedItemsemSocialFeedSettingsdeixa de ser código morto e passa a validar de verdade IDs de vídeo do YouTube (padrão[A-Za-z0-9_-]{11}), sem quebrar o e2e do S2 — ou, na alternativa licenciada pela própria intenção, é removido e o campo fica livre. - O que NÃO negociar: correção em dupla — (1) validar via
siblingData.platformOU remover o validate; (2) ids do stub de YouTube para 11 chars exatos +excludedItemsdo spec atualizados; (3) e2e do describe "Campaign home content section" verde. Fora de escopo: mexer no S2 entregue em produção. - O que reavaliar: hipótese de que "produção tem IDs inválidos salvos" — não verificável do worktree (guards proíbem tocar prod); tratada em Riscos com verificação pré-deploy.
Abordagem recomendada
flowchart LR
A[validate morto: data.platform undefined] --> B[Extrair helper puro em src/utilities/socialFeed/excludedItems.ts]
B --> C[validate usa siblingData.platform + unit test]
C --> D[Stub youtube: ids 11 chars e2evideo001-004]
D --> E[Spec: excludedItems/hrefs/share atualizados]
E --> F[e2e describe Campaign home + gate:fast]
Opções consideradas: A (consertar validate via siblingData.platform) | B (remover o validate) | C (validate "tolerante a legado" lendo o doc salvo via req.payload)
Recomendação: A — porque entrega o outcome primário da intenção (validação real de ID de vídeo, que hoje não existe), é mudança de ~1 linha com risco mitigado (ver Riscos) e o próprio guard nunca bloqueia o read nem corrompe dados; a alternativa B fica como fallback documentado com gatilho explícito (pré-check de prod), não como escolha primária — remover o validate joga fora a razão de ser do follow-up e deixa o erro de colar URL inteira continuar silencioso.
Rejeitadas: B como escolha primária — zera o risco, mas abdica do outcome primário da intenção e mantém o status quo de exclusões que falham silenciosamente com id mal colado (URL inteira, código curto); C — validate lendo o doc persistido (req.payload.findGlobal) para tolerar linhas legadas é over-engineering para um item P2, adiciona DB read dentro de validação e ciclo/recursão potencial; a permissão da intenção ("ou deixar o campo livre") já cobre o cenário de segurança máximo sem essa cerimônia.
Componentes / mudanças
validatedoitemId(src/globals/SocialFeedSettings.ts:204-212): troca{ data }/data.platformpor{ siblingData }/siblingData.platform; extrai a regra para helper purovalidateExcludedItemId(value, siblingData)+YOUTUBE_VIDEO_ID_PATTERNemsrc/utilities/socialFeed/excludedItems.ts(mesmo diretório doinstagramSync— o módulo que já é dono do concern "social feed"; a global já importa de@/utilities/socialFeed/). Mensagem de erro pt-BR existente fica: 'Informe o ID do vídeo (11 caracteres)'. Precedente do padrão siblingData:Post.ts:61,Tag.ts:65(beforeValidate),AllocationDecision.ts:136(condition).youtube-stub.mjs(tests/e2e/): os 4 ids de 20 chars viram 11 chars exatos —e2e-video-destaque-1→e2evideo001,e2e-video-caravana-2→e2evideo002,e2e-video-entrevista-3→e2evideo003,e2e-video-excluido-4→e2evideo004(todos[A-Za-z0-9_-]{11}, mantêm semântica de destaque/excluído). Thumbnails (/thumbs/<id>.jpg),statisticsResponseesearchResponsederivam das entradas deVIDEOS— consistência interna basta, nada mais muda.frontend.e2e.spec.ts:excludedItemsyoutube em :1030 e :1152 →itemId: 'e2evideo004'; hrefwatch?v=e2e-video-destaque-1em :1049 e na mensagem WhatsApp em :1584 →watch?v=e2evideo001. CanalUCe2eTestChannele IG (e2e-ig-grade-excluido-5,e2e-ig-muro-1) não mudam — IG éplatform: 'instagram', o guard não dispara (SocialFeedSettings.ts:208).- Unit test (
tests/unit/socialFeedExclusions.unit.spec.ts, padrão de nome*.unit.spec.ts): helper puro coberto — aceita 11 chars válidos (e2evideo001,dQw4w9WgXcQ), rejeita 20 chars/URLs/curtos; só falha quandosiblingData.platform === 'youtube'; retornatrueparainstagrame para valor vazio. - Migration: sem migration —
validateé validação de runtime no config Payload, não altera schema do DB (o array/select/text já existem desde o S2). - Access / Consent: não se aplica — global admin-only já existente (
payloadAdminOnly,SocialFeedSettings.ts:64-67). - UI: não há UI nova — o array já tem o admin panel; o erro inline do campo já existe.
Dados → forma (se aplicável)
- Não se aplica (nenhuma forma nova; copy de erro já existente em pt-BR).
Fases verificáveis
- Fix do validate + unit test — extrai helper (
src/utilities/socialFeed/excludedItems.ts) e usasiblingData.platformno validate;tests/unit/socialFeedExclusions.unit.spec.ts; valida compnpm test -- unitdo arquivo etsc --noEmit. (Se o implementador preferir manter o validate inline, a única perda é o unit test — decisão barata, registrada.) - Ids do stub + spec —
youtube-stub.mjs(4 ids) efrontend.e2e.spec.ts(:1030, :1049, :1152, :1584). IG eadmin.e2e.spec.tsintocados. - E2E + gates —
pnpm test:e2e --no-deps -- tests/e2e/frontend.e2e.spec.ts -g "Campaign home content section"(cobre os dois testes afetados: exclusões e "keeps the last snapshot"); rodar também o teste de save do admin do IG (admin.e2e.spec.ts— deve continuar verde, IG não é validado);pnpm gate:fast.
Rabbit holes / Não escopo (engenharia)
- Instagram não é afetado:
platform !== 'youtube'→ validate retornatrue(linhas IG eminstagram-stub.mjse specs não mudam). - Sem migração de dados:
excludedItemsem prod é dado de admin; ids inválidos já salvos não quebram o read (o board casa por id exato e apenas "não exclui"). - Não mexer no S2 entregue em produção (nada do board/read path muda; o stub só ganha ids realistas).
- Não criar validate "tolerante a legado" com leitura do banco (opção C rejeitada).
- Não adicionar warning-mode no Payload (não existe — validate retorna
trueou string de erro; sem meio-termo).
Riscos e mitigação
- Save-trap no admin/REST se prod tiver id youtube inválido pré-existente. O validate roda por row quando o doc inteiro é submetido: o admin form PUTa o global completo e o e2e
updateSocialFeedSettingsidem — linhas existentes re-validam. Como o validate está morto desde o S2, nada garantiu o que foi salvo (id digitado à mão, URL inteira colada). (a) O risco é estruturalmente real, mas de severidade baixa: o erro é inline por row no form, e a row pode ser corrigida ou DELETADA no próprio form antes do save — a recuperação nunca exige acesso ao banco; o único dano realista é um save não relacionado falhar uma vez e a assessoria ter que ajustar/apagar a linha. Probabilidade de existir row inválida em prod é desconhecida-moderada (campo manual, sem validação), mas mitigável: verificação pré-deploy read-only deexcludedItemscomplatform: 'youtube'fora do padrão (query única no homeserver, feita por quem dispara oworkflow_dispatch— deploy é manual). Se achar rows inválidas: corrigir/apagar pela UI antes de publicar; se não for possível limpar → fallback B (remover o validate), licenciado pela intenção e pré-comprometido neste plano. (b) Remover o validate é de fato mais seguro — por isso é o fallback; mas com o pré-check + recuperação 100% na UI, A não é fail-closed violado (sem corrupção, sem lockout, sem PII) e entrega o outcome primário. - Fix quebra o e2e existente (400 nos writes de exclusão). Não é risco, é a causa raiz — a troca dos ids do stub para 11 chars (fase 2, mandatória) resolve na mesma entrega; ordem importa: aplicar fase 1 e 2 juntas antes de rodar o e2e.
- Typing do validate:
{ data }hoje tipadata.platform; trocar o destructure parasiblingDataacompanha o tipo do row — semascasts. - Save do admin (IG) no
admin.e2e.spec.ts:92-97: submete o doc inteiro com row IG → validate retornatrueparainstagram; confirmado na fase 3.
Aceite de engenharia
- Aceite de produto da intenção ainda coberto (validação real via siblingData + ids do stub 11 chars + e2e do describe verde; fallback B explícito se o pré-check de prod falhar)
- Invariantes AGENTS/engineering-standards (sem schema → sem migration; sem escrita multi-collection; copy pt-BR / identificadores em inglês; nada de acesso/Consent novo)
- Testes de domínio previstos (unit do helper de validação na fase 1; e2e do describe + save admin IG na fase 3)
Decisões de engenharia
Opções: A (validate via siblingData.platform) | B (remover validate) | C (validate tolerante a legado lendo o doc salvo)
Recomendação: A — porque entrega o outcome primário da intenção (validação real de ID de vídeo), com risco de save-trap baixo (erro inline por row, row corrigível/deletável na própria UI, sem acesso a banco) e gatilho de fallback documentado (pré-check read-only de prod no deploy manual → B).
Alternativas rejeitadas: B como primária — zeraria o risco mas abdica do propósito do follow-up e mantém exclusões que falham silenciosamente com id mal colado; fica como fallback pré-comprometido. C — over-engineering para P2 (DB read dentro de validate, ciclo potencial), quando a intenção já licencia o caminho seguro máximo sem essa cerimônia.
Self-score decision-quality: 5/5 — (1) decisão cara (validate vivo vs morto em prod) tem rejeitadas A/B/C documentadas; (2) cabe no appetite P2 (2 fases de edição + gates, sem migration nem UI); (3) rabbit holes nomeados (IG, migração de dados, S2 em prod, warning-mode inexistente); (4) depth check reusa `src/utilities/socialFeed/` (mesmo dono do concern) e helpers de e2e existentes, sem módulo novo; (5) intenção preservada — correção em dupla e e2e do describe intactos.