teqo-backup/docs/changelog/2026-09-23-c213.md
Francisco Solla f47c2645ac feat(C213): contadores anônimos de circulação por peça na Central de Conteúdos (Closes #1258)
Collection contentEvent (hidden, sem hooks, sem PII) + beacon público
POST /api/content-events fail-soft, download contado no servidor na rota
de mídia, agregação em uma query group-by e a coluna "Circulação" na lista
interna + painel na ficha (port classe-a-classe do artefato estendido,
crítica final do designer certificada).
2026-09-23 15:29:43 -03:00

3.6 KiB
Raw Blame History

C213 — Analytics da Central de Conteúdos: contadores anônimos de circulação por peça (2026-09-23): a lista interna do C211 (e a ficha) passa a mostrar, por peça, quatro contadores absolutos e anônimos — Aberturas · Downloads · WhatsApp · Link — sem dashboard, serviço novo ou PII. O mecanismo é uma collection nova contentEvent (hidden, sem hooks — um write de evento nunca busta a tag pública contentPieces) com type (abertura|download|compartilhar_whatsapp|compartilhar_link) + subjectType (peca|card, o S32 entra como mais um assunto) + subjectId (id interno da peça), índice composto único (subjectType, subjectId, type), create/update negados por access e escrita só via Local API com bypass documentado. A escrita pública é o POST /api/content-events (beacon): zod (type + slug público), isSameOriginRequest, teto rígido de 4 KB lido no stream, limitador in-memory por IP hasheado com salt de processo (nunca persistido, fail-open, teto de 10k chaves) e resolução da peça publicada pelo slug — slug desconhecido ou despublicado responde 204 silencioso sem gravar. O download é contado no servidor, na rota pública de mídia (?download=1 sem Range, via after(), só com 200 — cobre de graça o fallback "A mídia"); abertura/WhatsApp/link saem do cliente (sendBeacon com fallback fetch keepalive, guarda useRef contra o double-effect do StrictMode; CopyLinkButton ganhou onCopied aditivo e useCopyFeedback.copy passou a devolver Promise<boolean>, cortes C166/C167/C168 intactos). A agregação é UMA query group-by por página (loadContentEventCountsBySubject + o helper compartilhado getPayloadDrizzle em drizzleBulk.ts, dono único do acesso ao drizzle para o qual o supporterListOverviewAggregate também migrou), com falha degradando para o estado "—"/"contagem indisponível" sem derrubar a lista. A UI porta o artefato aprovado classe-a-classe: coluna "Circulação" na CampaignTable (picker conteudos, visível por default) com os estados dados/tudo-zero (0 abertura · 0 download · 0 WhatsApp · 0 link)/rascunho nunca publicada (Sem dados — ainda não publicada)/despublicada com histórico (Histórico de quando esteve publicada · peça fora do ar)/indisponível; grid 2×2 no card mobile; painel na ficha com o strip responsivo, a nota "Leitura:" (só quando há contadores) e a linha de privacidade — e xl:[&_table]:table-fixed com larguras por coluna para os cinco cabeçalhos caberem em 1280 sem cortar "Próxima ação" (ajuste da crítica final do designer, certificada em tier primário; artefato estendido com as cenas 05–07 + CONTRATO DE PORT). Privacidade fail-closed: sem IP/cookie/user-agent/sessão em lugar nenhum (o evento guarda só tipo + assunto), sem Consent novo e nenhum rastreio entre peças. Migration aditiva 20260923_172437_add_content_events (tabela + enums + índice + rel de locked documents). Verificação: unit (contentPieceCirculation com precedência/mapeamento/literais, contentEvents com o contrato da collection sem PII e sem hooks + transporte do beacon, contentEventRateLimit com janela/reset/chaves), int (contentEvents: rota publicada/desconhecida/tipo inválido/oversized/cross-origin/throttle, agregação por assunto sem vazar card em peca, falha → ok:false, loaders data/empty/neverPublished/unavailable, mídia com download/range/leitura simples, access fechado), e2e (frontendConteudos com os quatro beacons + a linha anônima por REST, campaignSpeechAcervo com os contadores na lista e na ficha), pnpm gate:fast, pnpm test:int (927), build e os e2e afetados locais.