diff --git a/docs/CHECKPOINT_DELTA.md b/docs/CHECKPOINT_DELTA.md index 5ac23d46..f9643b47 100644 --- a/docs/CHECKPOINT_DELTA.md +++ b/docs/CHECKPOINT_DELTA.md @@ -1,5 +1,13 @@ # Checkpoint Delta — CD06 +## DIF-V2-WO-020 — Laboratório de retenção (2026-11-20) — PROPOSED + +- **Status:** **PROPOSED — NOT PROMOTED**; PgTAP 229/229, policy 34/37, unit 318+3, E2E local PASS; CI `44694433465` PASS em `02d9cae`; auditoria delta final pendente. Sem merge/deploy. +- **Base:** `main` `59ec14c` (checkpoint WO-019 promovido); branch `feat/dif-v2-wo-020`. +- **Delivered:** posts versionados, variantes ligadas a hook/capa/final, snapshots idempotentes imutáveis, import CSV com NULL, experimentos A/B observacionais, dashboard/export/delete owner-only. +- **Limits:** sem API/scraping; comparação descritiva sem significância; CSV exporta último snapshot; sem UI de edição de variante/poda; sem dados de espectadores. +- **Gate:** CI + auditoria independente + autorização contínua do owner; WO-021 (#38) é a próxima. + ## DIF-V2-WO-019 — Finais A/B e CTA cinematográfica (2026-11-20) — PROMOTED - **Status:** **PROMOTED**; code/test head `ff00957`; CI `44676921244` PASS (307+3 unit, PgTAP 210/210, E2E 17/17, Sonar PASS), docs-only `1c914ea` CI `44678149983` PASS, policy 33/31; auditoria final **APPROVED WITH RESIDUALS**; squash-merged em `3b0f3b7` (PR #66); issue #36 fechada. diff --git a/docs/CONTEXT_LOCK.md b/docs/CONTEXT_LOCK.md index de0a704c..25c22ccd 100644 --- a/docs/CONTEXT_LOCK.md +++ b/docs/CONTEXT_LOCK.md @@ -210,6 +210,14 @@ Revalidate before any external action if `main` changes; the feature branch is r - **Tests:** PgTAP **108/108**, policy **25 invariants/22 tables**, unit **116 + 2 skipped**, typecheck/lint/build PASS, real FFmpeg mux integration PASS, real Piper TTS opt-in PASS, 232-word synthetic TTS **94.552 s / −2,8 dBFS / −19,5 LUFS / 8,7 MB**; ARM64 **81 s de áudio em 8,86 s, RTF 0,109, 282 MB RSS**, hosted CI `43590151067` **SUCCESS** with E2E **12/12** (timeline narrada READY em 31,3s), owner-boundary narration 401 and responsive layout PASS. - **Gate:** owner authorized merge/promotion on 2026-11-14; PR #55 squash-merged at `326c576`; issue #24 closed; checkpoint **PROMOTED**. WO-008 (#25) is next. +## V2 Context Lock — WO-020 (#37) + +- **Base revalidated:** `main` `59ec14c` (checkpoint WO-019 promoted). Branch: `feat/dif-v2-wo-020`. +- **Issue inventory:** WO-001–019 **MERGED/CLOSED/PROMOTED**; WO-020/#37 em execução; WO-021 e OPS bloqueiam WO-014. +- **Scope:** métricas agregadas fornecidas manualmente/CSV; posts, variantes, snapshots, A/B observacional, export/delete, sem API social. +- **Delivered locally:** 6 tabelas owner-read/service-write; `/app/retention`; CSV/JSON export; stale/idempotência/immutabilidade; PgTAP 229; policy 34/37. +- **Gate:** CI, auditoria independente e autorização contínua do owner; checkpoint **PROPOSED**. WO-021 (#38) é a próxima. + ## V2 Context Lock — WO-019 (#36) - **Base revalidated:** `main` `c94409d` (checkpoint WO-018 promoted). Branch: `feat/dif-v2-wo-019`. diff --git a/docs/EVIDENCE_BUNDLE.md b/docs/EVIDENCE_BUNDLE.md index 7a78e6b0..2f4dd2fa 100644 --- a/docs/EVIDENCE_BUNDLE.md +++ b/docs/EVIDENCE_BUNDLE.md @@ -1,5 +1,24 @@ # DIF Studio — Evidence Bundle +## V2 WO-020 — Laboratório de retenção (2026-11-20) — PROPOSED + +- **Work Order:** `DIF-V2-WO-020` · issue #37 · epic #17 +- **Base:** `main` `59ec14c` (checkpoint WO-019 promovido); branch `feat/dif-v2-wo-020` +- **Status:** implementação + provas locais; unit **318+3**, PgTAP **229/229**, policy 34/37, build e E2E local PASS; CI `44694433465` PASS em `02d9cae` (318+3 unit, PgTAP 229/229, E2E 18/18, Sonar PASS); auditoria delta pendente. Checkpoint **PROPOSED**. + +| Check | Result | Evidence | +| ------- | ---------- | ------------------------------------------------------------------------------------ | +| Model | PASS local | posts versionados, variantes, snapshots imutáveis, imports e experimentos owner-only | +| Metrics | PASS local | fórmulas v1 com numerador/denominador; NULL ≠ zero; watch > duração rejeitado | +| Compare | PASS local | mesma plataforma, janelas ±20%, views ≥1000; senão NOT_COMPARABLE/INSUFFICIENT | +| UI | PASS local | `/app/retention` cadastra, importa CSV, mostra origem/denominador, compara e remove | +| Privacy | PASS local | owner-read/service-write; URLs nunca fetched; sem dados de espectadores | +| Export | PASS local | CSV/JSON owner-only, no-store, proteção de fórmula CSV | +| PgTAP | PASS local | 229/229 RLS, idempotência, supersedes, imutabilidade, experimento e cascata | +| Policy | PASS local | 34 invariantes / 37 tabelas; backup/restore incluem as 6 tabelas | +| CI | PENDENTE | quality/Sonar/E2E no head do PR | +| Limites | — | sem API/scraping; descritivo, não causal; sem significância; CSV = último snapshot | + ## V2 WO-019 — Finais A/B e CTA cinematográfica (2026-11-20) — PROMOTED - **Work Order:** `DIF-V2-WO-019` · issue #36 · epic #17 diff --git a/docs/V2_EXECUTION_PLAN.md b/docs/V2_EXECUTION_PLAN.md index 8bcc449a..59fbe382 100644 --- a/docs/V2_EXECUTION_PLAN.md +++ b/docs/V2_EXECUTION_PLAN.md @@ -2,7 +2,7 @@ - **Work Order:** `DIF-V2-WO-001` · issue #18 - **Epic:** #17 · issues #18–#45 -- **Base atual:** `main` `3b0f3b7` (checkpoint WO-019 promovido); WO-020 em execução; plano original em `13467ab009e0eaaee1be6ba2e35678228cfbdf32`. +- **Base atual:** `main` `59ec14c` (checkpoint WO-019 promovido); WO-020 em execução; plano original em `13467ab009e0eaaee1be6ba2e35678228cfbdf32`. - **Status:** **PROMOTED** — WO-001/002 **APPROVED/merged**; ADR-V2-002 **ACCEPTED**; WO-003/004/005 **APPROVED/merged** (`ac55d27`, `c6be101`, `dc405d8`); checkpoint V2 **PROMOTED**; WO-006 **APPROVED/merged** (`239f3ba`); WO-007 **APPROVED/merged** (`326c576`); WO-008 **APPROVED/merged** (`a633c3a`); WO-009 **APPROVED/merged** (`0b60321`); WO-010 **APPROVED/merged** (`1824061`); WO-011 **APPROVED WITH RESIDUALS/merged** (`d4a6a80`); WO-012 **APPROVED WITH RESIDUALS/merged** (`3edec2b`); WO-013 **APPROVED WITH RESIDUALS/merged (núcleo)** (`b1a1eaf`); WO-015 **APPROVED WITH RESIDUALS/merged** (`7c2ac4b`); WO-016 **APPROVED WITH RESIDUALS/merged** (`25089c3`); WO-017 **APPROVED WITH RESIDUALS/merged** (`ddaf0d2`); WO-018 **APPROVED WITH RESIDUALS/merged** (`62c30eb`); WO-019 **APPROVED WITH RESIDUALS/merged** (`3b0f3b7`); WO-020 em execução. - **Fonte viva:** os corpos atuais das issues #18–#45 prevalecem sobre este plano. @@ -29,7 +29,7 @@ | WO-017 | #34 | Continuidade visual + Character Identity Kit | ELEVATED | WO-003; WO-004; WO-011; WO-016 (quando disponível) | APPROVED WITH RESIDUALS / MERGED | | WO-018 | #35 | Capas, posters e cards | STANDARD | WO-003; WO-004; WO-011; WO-012; WO-016 | PROMOTED (`62c30eb`) | | WO-019 | #36 | Finais A/B cinematográficos e CTA canônica | STANDARD | WO-004; WO-010; WO-012 (proposta); V1 canon/choices | PROMOTED (`3b0f3b7`) | -| WO-020 | #37 | Laboratório de retenção, métricas manuais | STANDARD | WO-012; WO-015; WO-018; WO-019; WO-001; métricas V1 manuais | PLANNED | +| WO-020 | #37 | Laboratório de retenção, métricas manuais | STANDARD | WO-012; WO-015; WO-018; WO-019; WO-001; métricas V1 manuais | IN PROGRESS | | WO-021 | #38 | Bíblia audiovisual, presets e herança | STANDARD | WO-004; WO-009; WO-011; WO-016; WO-018 | PLANNED | | WO-022 | #39 | Smart Cutdowns 30/45/60 s | STANDARD | WO-004; WO-008; WO-012; WO-015; WO-019 | PLANNED | | WO-023 | #40 | Clip Rescue reversível | ELEVATED | WO-003; WO-006; WO-012; WO-016; retenção mínima WO-001/003 | PLANNED | diff --git a/docs/V2_RETENTION_WO020.md b/docs/V2_RETENTION_WO020.md new file mode 100644 index 00000000..e1dc5314 --- /dev/null +++ b/docs/V2_RETENTION_WO020.md @@ -0,0 +1,71 @@ +# DIF-V2-WO-020 — Laboratório de retenção e métricas manuais + +**Status:** implementação em `feat/dif-v2-wo-020`; CI `44694433465` PASS em `02d9cae` (318+3 unit, PgTAP 229/229, E2E 18/18, Sonar PASS), policy 34/37; auditoria delta final **PENDENTE**. Sem merge/deploy; checkpoint **PROPOSED**. +**Base:** `main` `59ec14c` (checkpoint WO-019 promovido). +**Escopo:** WO-020 (#37), dependente de WO-012/015/018/019 e do fluxo manual V1. + +## Entregue + +- Modelo privado owner-only: `published_posts`, `published_post_versions`, `creative_variants`, `analytics_snapshots`, `retention_imports` e `retention_experiments`. +- Posts com plataforma, URL validada (texto, nunca fetched), data de publicação e vínculo opcional a hook/capa/final aprovados do mesmo episódio. +- Snapshots append-only com revisão, `snapshot_hash`, `supersedes_snapshot_id`, origem MANUAL/CSV, período e métricas agregadas nuláveis (ausente ≠ zero). +- Fórmulas versionadas com numerador/denominador explícitos: engajamento por views, conclusão, watch time relativo e interações por 1000 views. +- Comparação A/B somente com mesma plataforma, janelas equivalentes e amostra ≥1000 views; caso contrário `NOT_COMPARABLE`/`INSUFFICIENT`. Texto sempre “observado/associação”, nunca causalidade. +- Import CSV com validação por linha, campos vazios → NULL, idempotência por hash, limites de tamanho e erros por linha. +- `/app/retention`: cadastro de posts/variantes, snapshots manuais, importação CSV, dashboard com origem/denominador, experimentos A/B observacionais, export CSV/JSON e remoção owner-only. +- Export CSV com proteção de fórmula (`= + - @`) e JSON com definições/versão; nada de dados de espectadores. +- Backup/restore e policy incluem as seis tabelas; 37 tabelas e 34 invariantes. + +## Capacidade real versus planejada + +- Nenhuma API social, scraping, login automatizado, leitura de dashboard ou coleta de comentários; todos os números são fornecidos manualmente/CSV. +- Métricas são agregadas; não há dados por espectador, segmentação de público ou atribuição de tráfego. +- A comparação A/B é descritiva: não estima significância, não controla confundidores e não prevê viralidade. +- O período é comparável quando mesma plataforma, duração da janela ±20% e views ≥1000 nas duas variantes; janelas diferentes geram aviso. +- Histórico de post é versionado; snapshots nunca são sobrescritos (retificação cria nova revisão com `supersedes`). +- Export CSV/JSON é owner-only; remoção apaga post, versões, variantes, snapshots e experimentos vinculados. + +## Critérios de aceitação + +| Critério | Estado | Evidência | +| ----------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | +| 2 vídeos/fixtures, plataformas distintas, períodos e A/B; dashboard mostra origem e denominador | PASS | E2E cria TikTok+Reels com snapshots, A/C TikTok para A/B, CSV, comparação observacional e cross-platform NOT_COMPARABLE | +| Métrica ausente não vira zero/conclusão; períodos distintos mostram incomparabilidade | PASS | NULL/partial → warnings/`INSUFFICIENT`; CSV sem interações INDISPONÍVEL; cross-platform alerta | +| Gráficos/resumo factual sem “viral”, “garantia” ou ranking especulativo | PASS | barras SVG de views/engajamento, histórico por post, comparação observacional; teste proíbe termos | +| Entrada repetida idempotente com histórico; edição não sobrescreve evidência | PASS | hash único, revisão append-only, duração/métrica pinadas, `supersedes` e histórico na UI | +| Export/exclusão sem vazar dados owner ou de usuários | PASS | rotas owner-only, export agregado, delete RPC; E2E anônimo 401 e remoção | + +## Correções pós-auditoria independente + +- **Interações parciais:** `PARTIAL_INTERACTIONS` é emitido e a comparação com cobertura de campos diferente retorna `INSUFFICIENT`/`INTERACTION_COVERAGE_MISMATCH`; NULL nunca vira zero. +- **Limites por owner:** variantes e snapshots são buscados com `.in('post_id', postIds)` depois dos posts, sem limite global que esconda o episódio. +- **Números estritos:** formulário e CSV rejeitam `1.000`, `1,5`, `1.234,5` e texto; apenas dígitos (e ponto decimal na conclusão). Erro por linha é exibido. +- **CSV injection:** células perigosas são citadas e cada linha recebe apóstrofo; vírgulas/quebras não criam registros sem escape. +- **Snapshot/experimento pinados:** `episode_duration_ms` e `metric_version` ficam no snapshot; experimentos guardam os snapshots A/B usados e rejeitam variantes do mesmo post; a UI mostra revisão/origem/período pinados e não cai para o latest se o pinado faltar. +- **Gráficos sem NULL→0:** barras de engajamento só incluem taxas calculáveis; CSV B sem interações não ganha barra 0% (E2E verifica 4 barras para 5 posts). +- **Paginação PostgREST:** variantes/snapshots são lidos com `.range()` em páginas de 1000 até esgotar, em vez de um `.limit(5000)` clampado. +- **Hash com duração:** `episode_duration_ms` entra no `snapshot_hash`, permitindo retificar apenas o denominador. +- **Histórico/gráficos:** dashboard tem barras SVG de views/engajamento, histórico por post com revisões/supersedes e select de retificação; A/B mostra variante, post, views, unidade, revisão/origem/período. +- **Resiliência:** snapshot histórico inválido gera warning e não derruba a página/export; conflito de revisão concorrente usa advisory lock e 409, não falso duplicado; hooks DRAFT não aparecem no formulário. + +## Testes planejados/executados + +- Unit: 11 testes — fórmulas com NULL/zero/amostra baixa/discrepância, interações parciais vs completas, watch =105% rejeitado, comparabilidade por plataforma/período/amostra/métrica, linguagem não causal, CSV quoted/CRLF, linha malformada, número ambíguo, injeção de fórmula com vírgula/newline. +- PgTAP 229: RLS owner/nonowner, escrita direta negada, post/versão, variante A/B em posts distintos, snapshot idempotente com duração pinada e supersedes, imutabilidade, experimento, delete em cascata. +- E2E: login/nav, cria posts TikTok+Reels com snapshots, variantes, experimento observacional, cross-platform `NOT_COMPARABLE`, CSV com NULL (sem barra 0%), origem MANUAL, export CSV/JSON, anônimo negado, remoção e screenshots 360/768/1440. +- Policy: 34 invariantes / 37 tabelas; backup/restore incluem as tabelas de retenção. + +## Riscos e residuais + +- Sem APIs oficiais, scraping ou coleta automática; dados podem ser incompletos ou enviesados pelo owner. +- Sem significância estatística, controle de confundidores ou atribuição de tráfego; comparação é descritiva. +- Sem dados por espectador, demografia ou comentários; somente agregados fornecidos. +- CSV não valida duplicidade de URL entre episódios diferentes (a chave é por owner+episódio+plataforma+URL). +- Sem UI de edição de post/variante; correções de post criam versão, variantes são imutáveis. +- Sem poda de snapshots/imports; limites de 5000 snapshots/post e 5000 linhas/CSV. +- Gráficos são barras SVG simples por último snapshot, não séries temporais completas; histórico aparece em lista por post. +- Export CSV inclui o último snapshot por post; JSON inclui as revisões carregadas (paginadas) e as 20 importações mais recentes. Não há export de `published_post_versions`. + +## Gate + +CI hosted, PgTAP, Evidence Bundle, Checkpoint Delta PROPOSED, auditoria independente e autorização contínua do owner antes de merge/promoção. **Sem deploy nesta etapa.** diff --git a/docs/evidence/wo-020/tests.txt b/docs/evidence/wo-020/tests.txt new file mode 100644 index 00000000..c9257e3d --- /dev/null +++ b/docs/evidence/wo-020/tests.txt @@ -0,0 +1,61 @@ +# WO-020 — evidence + +Date: 2026-11-20 (America/Sao_Paulo) +Branch: `feat/dif-v2-wo-020` (base `main` `59ec14c`) + +## Static + +- `npm run check`: 0 errors / 0 warnings +- `npm run lint`: PASS +- `npm run audit:policy`: **34 invariants / 37 tables** PASS +- `npm run build`: PASS (@sveltejs/adapter-node) +- `npm run test:db`: **229/229** PgTAP PASS + +## Unit / domain + +- `retention.test.ts`: 11/11 — formula denominators, NULL vs zero, partial interactions vs full + coverage, low sample, completion discrepancy, watch =105% rejected, platform/period/sample/metric + comparability, non-causal language, CSV quoted/CRLF, malformed rows, ambiguous thousands, + formula injection with commas/newlines. +- Post-fix: snapshots load per episode post ids; latest is highest revision; A/B pins the snapshots + used and rejects variants from the same post. +- Unit suite: **318 passed + 3 skipped** locally. + +## E2E + +- `e2e/retention.spec.ts` local PASS: login, nav “Retenção”, TikTok and Reels posts, three variants, + manual snapshots, A/B observational comparison, CSV import with NULL interactions, CSV/JSON export, + anonymous 401, delete, screenshots 360/768/1440. +- Dashboard shows origin/period/denominator, marks missing values as `INDISPONÍVEL`, renders SVG + views bars plus engagement bars only for calculable rates (CSV B with NULL interactions has no + 0% bar), and per-post snapshot history with supersedes/retification. +- Variants/snapshots are paginated with `.range()` (1000/page); experiments show the pinned + snapshot revision/source/period and fail closed when the pinned snapshot is absent. + +## Database / retention + +- `published_posts`, `published_post_versions`, `creative_variants`, `analytics_snapshots`, + `retention_imports`, `retention_experiments` are owner-read/service-write with forced RLS. +- Snapshots/versions/imports are immutable; snapshots are idempotent by `(post, snapshot_hash)` + that includes `episode_duration_ms`, pin `metric_version`, and retifications append a new revision + with `supersedes_snapshot_id`. +- Experiments pin `variant_a_snapshot_id`/`variant_b_snapshot_id` and reject variants from the same + post; concurrent snapshot revisions use an advisory lock. +- PgTAP: owner read, direct insert denied, second owner isolated, post version, variants A/B, + idempotent snapshot, supersedes, immutable update, experiment distinct variants, delete cascade. +- Quota: 5000 snapshots per post; 5000 CSV rows and 5 MB input. + +## Privacy / security + +- URLs are owner-provided text and never fetched; no scraping, login automation or social API. +- Only aggregate metrics are stored; no viewer-level, demographic or comment data. +- Export routes owner-only, `private, no-store`; CSV cells are quoted then prefixed per line + against formula injection. +- Deletion is owner-scoped and removes post, versions, variants, snapshots and linked experiments. + +## Limits verified + +- Comparisons are descriptive associations, not causal or significance tests. +- Different platforms or window lengths return `NOT_COMPARABLE`; low samples return `INSUFFICIENT`. +- CSV export contains the latest snapshot per post; full context and imports are in JSON. +- Post edits create a new version; variants are immutable and have no edit UI. diff --git a/e2e/retention.spec.ts b/e2e/retention.spec.ts new file mode 100644 index 00000000..bf7a2fd8 --- /dev/null +++ b/e2e/retention.spec.ts @@ -0,0 +1,194 @@ +import { expect, test } from '@playwright/test'; +import { insertEpisodeHierarchy, loginAsOwner } from './fixtures.js'; +import { captureResponsivePages } from './responsive.js'; +import { ownerAccessToken, ownerId, serviceKey, supabaseUrl } from './supabase.js'; + +test('owner records, imports, compares and deletes retention data', async ({ page, request }) => { + test.setTimeout(300_000); + test.skip(!process.env.E2E_OWNER_EMAIL, 'requires a synthetic owner in local Supabase'); + test.skip(!supabaseUrl || !serviceKey || !ownerId, 'requires local service role and owner id'); + page.setDefaultTimeout(60_000); + page.setDefaultNavigationTimeout(120_000); + page.on('dialog', (dialog) => void dialog.accept()); + + const suffix = crypto.randomUUID().slice(0, 8); + const token = await ownerAccessToken(request); + const { episodeId } = await insertEpisodeHierarchy(request, { + token, + suffix, + seriesTitle: `Retention E2E ${suffix}`, + premise: 'Fixture sintética de retenção.', + seasonTitle: 'Temporada retenção', + plannedEpisodeCount: 10, + episodeNumber: 2, + episodeTitle: `Episódio retenção ${suffix}`, + durationMs: 90_000, + }); + + await loginAsOwner(page); + await page.getByRole('link', { name: 'Retenção' }).click(); + await expect(page).toHaveURL(/\/app\/retention/); + await page.locator('select[name="episodeId"]').selectOption(episodeId); + await expect(page.getByRole('heading', { name: 'Laboratório de retenção' })).toBeVisible(); + + const postForm = page.locator('form[action="?/post"]'); + await postForm.locator('input[name="publishedAt"]').fill('2026-11-01T10:00'); + await postForm.locator('input[name="url"]').fill('https://www.tiktok.com/@dif/video/1001'); + await postForm.locator('input[name="label"]').fill('Abertura A'); + await postForm.getByRole('button', { name: 'Salvar publicação' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + await expect(page.locator('.post-card')).toHaveCount(1); + + async function addPost(url: string, label: string, platform = 'tiktok') { + await postForm.locator('input[name="publishedAt"]').fill('2026-11-01T10:00'); + await postForm.locator('select[name="platform"]').selectOption(platform); + await postForm.locator('input[name="url"]').fill(url); + await postForm.locator('input[name="label"]').fill(label); + await postForm.getByRole('button', { name: 'Salvar publicação' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + } + + await page + .locator('details') + .filter({ hasText: 'Registrar variante' }) + .locator('summary') + .click(); + const variantForm = page.locator('form[action="?/variant"]'); + await variantForm.locator('select[name="postId"]').selectOption({ label: 'tiktok · Abertura A' }); + await variantForm.locator('select[name="kind"]').selectOption('HOOK'); + await variantForm.locator('input[name="label"]').fill('H1'); + await variantForm.getByRole('button', { name: 'Salvar variante' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + + await addPost('https://www.instagram.com/reel/ABC123/', 'Abertura B', 'reels'); + await expect(page.locator('.post-card')).toHaveCount(2); + await page + .locator('details') + .filter({ hasText: 'Registrar variante' }) + .locator('summary') + .click(); + await variantForm.locator('select[name="postId"]').selectOption({ label: 'reels · Abertura B' }); + await variantForm.locator('select[name="kind"]').selectOption('BASELINE'); + await variantForm.locator('input[name="label"]').fill('B1'); + await variantForm.getByRole('button', { name: 'Salvar variante' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + + await addPost('https://www.tiktok.com/@dif/video/1005', 'Abertura C'); + await page + .locator('details') + .filter({ hasText: 'Registrar variante' }) + .locator('summary') + .click(); + await variantForm.locator('select[name="postId"]').selectOption({ label: 'tiktok · Abertura C' }); + await variantForm.locator('select[name="kind"]').selectOption('HOOK'); + await variantForm.locator('input[name="label"]').fill('C1'); + await variantForm.getByRole('button', { name: 'Salvar variante' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + + async function addSnapshot(postLabel: string, views: string, likes: string, completion: string) { + await page + .locator('details') + .filter({ hasText: 'Adicionar snapshot manual' }) + .locator('summary') + .click(); + const form = page.locator('form[action="?/snapshot"]'); + await form.locator('select[name="postId"]').selectOption({ label: postLabel }); + await form.locator('input[name="periodStart"]').fill('2026-11-01T00:00'); + await form.locator('input[name="periodEnd"]').fill('2026-11-08T00:00'); + await form.locator('input[name="capturedAt"]').fill('2026-11-09T00:00'); + await form.locator('input[name="views"]').fill(views); + await form.locator('input[name="likes"]').fill(likes); + await form.locator('input[name="comments"]').fill('50'); + await form.locator('input[name="shares"]').fill('30'); + await form.locator('input[name="saves"]').fill('20'); + await form.locator('input[name="followersGained"]').fill('10'); + await form.locator('input[name="avgWatchMs"]').fill('60000'); + await form.locator('input[name="completionPct"]').fill(completion); + await form.getByRole('button', { name: 'Salvar snapshot' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + } + + await addSnapshot('tiktok · Abertura A', '12000', '600', '50'); + await addSnapshot('tiktok · Abertura C', '10000', '300', '45'); + await addSnapshot('reels · Abertura B', '9000', '200', '40'); + await expect(page.locator('.post-card').first()).toContainText('12.000'); + await expect(page.locator('.post-card').first()).toContainText('5.83%'); + await expect(page.locator('.post-card').first()).toContainText('origem MANUAL'); + + const experimentForm = page.locator('form[action="?/experiment"]'); + await experimentForm.locator('input[name="name"]').fill('Hook vs baseline'); + await experimentForm + .locator('input[name="hypothesis"]') + .fill('Abertura curta observa mais engajamento.'); + await experimentForm + .locator('select[name="variantAId"]') + .selectOption({ label: 'tiktok · Abertura A · H1' }); + await experimentForm + .locator('select[name="variantBId"]') + .selectOption({ label: 'tiktok · Abertura C · C1' }); + await experimentForm.getByRole('button', { name: 'Registrar experimento' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + const observable = page.locator('.comparison').filter({ hasText: 'Hook vs baseline' }); + await expect(observable).toContainText('OBSERVATIONAL'); + await expect(observable).toContainText('maior valor observado'); + await expect(observable).not.toContainText('garantia'); + + await experimentForm.locator('input[name="name"]').fill('Cross-platform'); + await experimentForm + .locator('select[name="variantAId"]') + .selectOption({ label: 'tiktok · Abertura A · H1' }); + await experimentForm + .locator('select[name="variantBId"]') + .selectOption({ label: 'reels · Abertura B · B1' }); + await experimentForm.getByRole('button', { name: 'Registrar experimento' }).click(); + await expect(page.locator('.notice.success')).toContainText('Registro salvo'); + await expect(page.locator('.comparison').filter({ hasText: 'Cross-platform' })).toContainText( + 'NOT_COMPARABLE', + ); + + await page.locator('details').filter({ hasText: 'Importar CSV' }).locator('summary').click(); + const csv = [ + 'platform,url,published_at,label,period_start,period_end,captured_at,views,likes,comments,shares,saves,followers_gained,avg_watch_ms,completion_pct,note', + `tiktok,https://www.tiktok.com/@dif/video/1003,2026-11-02T00:00:00Z,CSV A,2026-11-02T00:00:00Z,2026-11-09T00:00:00Z,2026-11-10T00:00:00Z,20000,800,60,40,20,15,60000,55,Importado`, + `tiktok,https://www.tiktok.com/@dif/video/1004,2026-11-03T00:00:00Z,CSV B,2026-11-03T00:00:00Z,2026-11-10T00:00:00Z,2026-11-11T00:00:00Z,15000,,,,,8,,50,Sem interações`, + ].join('\n'); + await page.locator('form[action="?/import"] textarea[name="csv"]').fill(csv); + await page.locator('form[action="?/import"] button[type="submit"]').click(); + await expect(page.locator('.notice.success')).toContainText('2 novos'); + await expect(page.locator('.post-card')).toHaveCount(5); + await expect(page.locator('.post-card').filter({ hasText: 'CSV B' })).toContainText( + 'INDISPONÍVEL', + ); + await expect(page.locator('.bar.engagement')).toHaveCount(4); + await expect(page.locator('.charts')).toContainText('apenas taxas calculáveis'); + + const exported = await page.request.get( + `/api/retention/export?episodeId=${episodeId}&format=csv`, + ); + expect(exported.status()).toBe(200); + const exportedCsv = await exported.text(); + expect(exportedCsv).toContain('https://www.tiktok.com/@dif/video/1001'); + expect(exportedCsv).toContain('engagement_rate'); + const exportedJson = await page.request.get( + `/api/retention/export?episodeId=${episodeId}&format=json`, + ); + expect(exportedJson.status()).toBe(200); + expect((await exportedJson.json()) as { format: string }).toMatchObject({ + format: 'dif-studio-retention/v1', + }); + const anonymous = await request.get(`/api/retention/export?episodeId=${episodeId}&format=csv`); + expect([401, 403, 404]).toContain(anonymous.status()); + + await page + .locator('.post-card') + .first() + .getByRole('button', { name: 'Remover publicação' }) + .click(); + await expect(page.locator('.post-card')).toHaveCount(4); + + await captureResponsivePages(page, { + url: `/app/retention?episodeId=${episodeId}`, + heading: 'Laboratório de retenção', + prefix: 'retention', + }); +}); diff --git a/scripts/audit-policy.mjs b/scripts/audit-policy.mjs index 3919687d..67fed274 100644 --- a/scripts/audit-policy.mjs +++ b/scripts/audit-policy.mjs @@ -82,6 +82,10 @@ const endCardMigration = await readFile( 'supabase/migrations/20261120090000_v2_wo019_choice_end_cards.sql', 'utf8', ); +const retentionLabMigration = await readFile( + 'supabase/migrations/20261120110000_v2_wo020_retention_lab.sql', + 'utf8', +); const retentionScript = await readFile('scripts/retention.mjs', 'utf8'); const restoreScript = await readFile('scripts/restore-metadata.mjs', 'utf8'); const hook = await readFile('src/hooks.server.ts', 'utf8'); @@ -121,9 +125,10 @@ const tables = [ ...identityMigration.matchAll(/^create table public\.(\w+)\s*\(/gm), ...coverMigration.matchAll(/^create table public\.(\w+)\s*\(/gm), ...endCardMigration.matchAll(/^create table public\.(\w+)\s*\(/gm), + ...retentionLabMigration.matchAll(/^create table public\.(\w+)\s*\(/gm), ].map((match) => match[1]); const checks = [ - ['31 owner-scoped public tables', tables.length === 31], + ['37 owner-scoped public tables', tables.length === 37], [ 'every table has forced RLS', migration.includes('enable row level security') && @@ -414,6 +419,19 @@ const checks = [ endCardMigration.includes('prune_choice_end_cards') && endCardMigration.includes('dif.end_card_prune'), ], + [ + 'retention lab is owner-read, service-written and idempotent', + retentionLabMigration.includes('published_posts') && + retentionLabMigration.includes('analytics_snapshots') && + retentionLabMigration.includes('retention_history_is_immutable') && + retentionLabMigration.includes( + 'grant select on table public.analytics_snapshots to authenticated', + ) && + retentionLabMigration.includes('grant execute on function public.save_analytics_snapshot') && + retentionLabMigration.includes('grant execute on function public.delete_published_post') && + retentionLabMigration.includes('snapshot_hash') && + retentionLabMigration.includes('unique (owner_id, post_id, snapshot_hash)'), + ], [ 'render quotas, health and ops scripts are server-only and dry-run first', hardeningMigration.includes('render_daily_job_quota') && diff --git a/scripts/backup-metadata.mjs b/scripts/backup-metadata.mjs index 2189fc13..4c9a6708 100644 --- a/scripts/backup-metadata.mjs +++ b/scripts/backup-metadata.mjs @@ -91,6 +91,12 @@ const tableNames = [ 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards', + 'published_posts', + 'published_post_versions', + 'creative_variants', + 'retention_imports', + 'analytics_snapshots', + 'retention_experiments', ]; const counts = {}; for (const table of tableNames) { diff --git a/scripts/restore-metadata.mjs b/scripts/restore-metadata.mjs index dc24c8af..569ac12f 100644 --- a/scripts/restore-metadata.mjs +++ b/scripts/restore-metadata.mjs @@ -62,6 +62,12 @@ const allowedTables = new Set([ 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards', + 'published_posts', + 'published_post_versions', + 'creative_variants', + 'retention_imports', + 'analytics_snapshots', + 'retention_experiments', ]); for (const table of Object.keys(summary.counts)) { if (!allowedTables.has(table) || !/^[a-z][a-z0-9_]{0,63}$/.test(table)) diff --git a/src/lib/components/WorkspaceNav.svelte b/src/lib/components/WorkspaceNav.svelte index f940b1fa..159fd7c0 100644 --- a/src/lib/components/WorkspaceNav.svelte +++ b/src/lib/components/WorkspaceNav.svelte @@ -36,6 +36,12 @@ label: 'Final A/B', glyph: 'branch', }, + { + path: '/app/retention', + href: resolve('/app/retention'), + label: 'Retenção', + glyph: 'archive', + }, { path: '/app/library', href: resolve('/app/library'), diff --git a/src/lib/domain/retention.test.ts b/src/lib/domain/retention.test.ts new file mode 100644 index 00000000..0a1d784f --- /dev/null +++ b/src/lib/domain/retention.test.ts @@ -0,0 +1,201 @@ +import { describe, expect, it } from 'vitest'; +import { + compareVariantObservations, + computeRetentionMetrics, + LOW_SAMPLE_VIEWS, + parseCsvRows, + parseRetentionCsv, + RetentionError, + retentionCsv, + sanitizeCsvCell, + type VariantObservation, +} from './retention.js'; + +function metrics(overrides: Partial[0]> = {}) { + return { + views: 10_000, + likes: 400, + comments: 50, + shares: 30, + saves: 20, + followersGained: 10, + avgWatchMs: null, + completionPct: null, + ...overrides, + }; +} + +function observation(overrides: Partial = {}): VariantObservation { + return { + platform: 'tiktok', + label: 'Post', + variantLabel: 'A', + periodStart: '2026-11-01T00:00:00Z', + periodEnd: '2026-11-08T00:00:00Z', + views: 10_000, + metrics: computeRetentionMetrics(metrics(), 120_000), + ...overrides, + }; +} + +describe('retention formulas', () => { + it('computes explicit ratios with visible denominators', () => { + const result = computeRetentionMetrics(metrics({ avgWatchMs: 60_000 }), 120_000); + expect(result.totalInteractions).toBe(500); + expect(result.engagementRate).toBe(0.05); + expect(result.interactionsPer1000).toBe(50); + expect(result.completionPct).toBe(50); + expect(result.watchTimeRelative).toBe(0.5); + expect(result.metricVersion).toBe(1); + expect(result.missing).toEqual([]); + }); + + it('never turns missing metrics into zero and flags partial interactions', () => { + const result = computeRetentionMetrics( + metrics({ likes: null, comments: null, shares: null, saves: null }), + 120_000, + ); + expect(result.totalInteractions).toBeNull(); + expect(result.engagementRate).toBeNull(); + expect(result.interactionsPer1000).toBeNull(); + expect(result.missing).toContain('interactions'); + expect(result.interactionCoverage).toBe('NONE'); + + const partial = computeRetentionMetrics( + metrics({ likes: null, comments: 50, shares: 30, saves: 20 }), + 120_000, + ); + expect(partial.interactionCoverage).toBe('PARTIAL'); + expect(partial.warnings).toContain('PARTIAL_INTERACTIONS'); + const full = observation(); + const partialObservation = observation({ metrics: partial }); + expect(compareVariantObservations(full, partialObservation, 'engagement_rate')).toMatchObject({ + status: 'INSUFFICIENT', + warnings: expect.arrayContaining(['INTERACTION_COVERAGE_MISMATCH']), + }); + + const noViews = computeRetentionMetrics(metrics({ views: null }), 120_000); + expect(noViews.engagementRate).toBeNull(); + expect(noViews.missing).toContain('views'); + }); + + it('handles zero views, low samples and completion discrepancy', () => { + expect(computeRetentionMetrics(metrics({ views: 0 }), 120_000).warnings).toContain( + 'ZERO_VIEWS', + ); + const low = computeRetentionMetrics(metrics({ views: LOW_SAMPLE_VIEWS - 1 }), 120_000); + expect(low.warnings).toContain('LOW_SAMPLE'); + const discrepancy = computeRetentionMetrics( + metrics({ avgWatchMs: 30_000, completionPct: 80 }), + 120_000, + ); + expect(discrepancy.warnings).toContain('COMPLETION_DISCREPANCY'); + }); + + it('rejects watch time above the episode duration, including 105%', () => { + expect(() => computeRetentionMetrics(metrics({ avgWatchMs: 126_000 }), 120_000)).toThrow( + RetentionError, + ); + expect(() => computeRetentionMetrics(metrics({ avgWatchMs: 130_000 }), 120_000)).toThrow( + RetentionError, + ); + }); +}); + +describe('variant comparison', () => { + it('compares only same-platform, comparable windows', () => { + const base = observation(); + const platform = compareVariantObservations( + base, + observation({ platform: 'reels' }), + 'engagement_rate', + ); + expect(platform.status).toBe('NOT_COMPARABLE'); + + const period = compareVariantObservations( + base, + observation({ periodEnd: '2026-12-01T00:00:00Z' }), + 'engagement_rate', + ); + expect(period.status).toBe('NOT_COMPARABLE'); + expect(period.warnings).toContain('PERIOD_LENGTH_MISMATCH'); + }); + + it('returns insufficient for low samples or missing metrics', () => { + const base = observation(); + expect( + compareVariantObservations(base, observation({ views: 500 }), 'engagement_rate').status, + ).toBe('INSUFFICIENT'); + const missing = observation({ + metrics: computeRetentionMetrics( + metrics({ likes: null, comments: null, shares: null, saves: null }), + 120_000, + ), + }); + expect(compareVariantObservations(base, missing, 'engagement_rate').status).toBe( + 'INSUFFICIENT', + ); + }); + + it('reports an observational association without causal or viral language', () => { + const base = observation(); + const better = observation({ + views: 12_000, + metrics: computeRetentionMetrics(metrics({ views: 12_000, likes: 900 }), 120_000), + }); + const comparison = compareVariantObservations(base, better, 'engagement_rate'); + expect(comparison.status).toBe('OBSERVATIONAL'); + expect(comparison.summary).toContain('observado'); + expect(comparison.summary).toContain('não causalidade'); + for (const word of ['viral', 'garantia', 'causou']) + expect(comparison.summary.toLowerCase()).not.toContain(word); + }); +}); + +describe('CSV import and export', () => { + const header = + 'platform,url,published_at,label,period_start,period_end,captured_at,views,likes,comments,shares,saves,followers_gained,avg_watch_ms,completion_pct,note'; + + it('parses quoted fields, empty values as null and CRLF', () => { + const csv = `${header}\r\nTikTok,https://www.tiktok.com/@x/video/1,2026-11-01T00:00:00Z,"A, fita",2026-11-01T00:00:00Z,2026-11-08T00:00:00Z,2026-11-09T00:00:00Z,10000,,12,,,0,60000,50,"linha 1\nlinha 2"\r\n`; + const parsed = parseRetentionCsv(csv); + expect(parsed.errors).toEqual([]); + expect(parsed.rows).toHaveLength(1); + expect(parsed.rows[0]).toMatchObject({ + platform: 'tiktok', + label: 'A, fita', + likes: null, + comments: 12, + shares: null, + views: 10_000, + completion_pct: 50, + }); + }); + + it('rejects malformed rows without dropping valid ones', () => { + const csv = `${header}\nTikTok,https://www.tiktok.com/@x/video/1,2026-11-01T00:00:00Z,A,2026-11-08T00:00:00Z,2026-11-01T00:00:00Z,2026-11-09T00:00:00Z,100,1,1,1,1,0,30000,50,ok\nTikTok,not-a-url,2026-11-01T00:00:00Z,A,2026-11-01T00:00:00Z,2026-11-08T00:00:00Z,2026-11-09T00:00:00Z,100,1,1,1,1,0,30000,50,ok`; + const parsed = parseRetentionCsv(csv); + expect(parsed.rows).toHaveLength(0); + expect(parsed.errors).toHaveLength(2); + expect(() => parseRetentionCsv('a,b\n1,2')).toThrow(RetentionError); + }); + + it('guards formula injection including commas and newlines', () => { + expect(sanitizeCsvCell('=SUM(A1:A2)')).toBe(`"'=SUM(A1:A2)"`); + expect(sanitizeCsvCell('@user')).toBe(`"'@user"`); + expect(sanitizeCsvCell('a,b')).toBe('"a,b"'); + expect(sanitizeCsvCell('=1,2')).toBe(`"'=1,2"`); + const csv = retentionCsv([{ label: '=x\n=HYPERLINK("https://evil.example")', views: 10 }]); + const parsed = parseCsvRows(csv); + expect(parsed).toHaveLength(2); + expect(parsed[1]).toHaveLength(2); + expect(parsed[1]?.[0]).toContain(`'=HYPERLINK`); + }); + + it('rejects ambiguous thousands separators in CSV numbers', () => { + const csv = `${header}\nTikTok,https://www.tiktok.com/@x/video/1,2026-11-01T00:00:00Z,A,2026-11-01T00:00:00Z,2026-11-08T00:00:00Z,2026-11-09T00:00:00Z,1.000,1,1,1,1,0,30000,50,ok`; + const parsed = parseRetentionCsv(csv); + expect(parsed.rows).toHaveLength(0); + expect(parsed.errors[0]?.message).toContain('Número inteiro inválido'); + }); +}); diff --git a/src/lib/domain/retention.ts b/src/lib/domain/retention.ts new file mode 100644 index 00000000..a6197d49 --- /dev/null +++ b/src/lib/domain/retention.ts @@ -0,0 +1,459 @@ +import { + retentionImportRowSchema, + type AnalyticsMetrics, + type RetentionImportRow, +} from '#lib/schemas/retention.js'; + +export const RETENTION_METRIC_VERSION = 1; +export const LOW_SAMPLE_VIEWS = 1_000; + +export class RetentionError extends Error { + constructor( + readonly code: string, + message: string, + ) { + super(message); + this.name = 'RetentionError'; + } +} + +export interface MetricDefinition { + id: 'engagement_rate' | 'completion_pct' | 'watch_time_relative' | 'interactions_per_1000'; + label: string; + numerator: string; + denominator: string; + unit: 'ratio' | 'percent' | 'per_1000_views'; +} + +export const RETENTION_METRIC_DEFINITIONS: MetricDefinition[] = [ + { + id: 'engagement_rate', + label: 'Taxa de engajamento', + numerator: 'likes + comentários + shares + saves disponíveis', + denominator: 'views', + unit: 'ratio', + }, + { + id: 'completion_pct', + label: 'Taxa de conclusão', + numerator: 'conclusão informada pela plataforma ou avg_watch_ms', + denominator: 'duração do episódio', + unit: 'percent', + }, + { + id: 'watch_time_relative', + label: 'Tempo assistido relativo', + numerator: 'avg_watch_ms', + denominator: 'duração do episódio em ms', + unit: 'ratio', + }, + { + id: 'interactions_per_1000', + label: 'Interações por 1000 views', + numerator: 'interações disponíveis', + denominator: 'views / 1000', + unit: 'per_1000_views', + }, +]; + +export const RETENTION_PLATFORM_NOTES: Record = { + tiktok: 'Views/plays e interações conforme o painel do TikTok; campos ausentes são NULL.', + reels: 'Views/plays e interações conforme o painel do Instagram; completion pode não existir.', + youtube_shorts: + 'Views e interações conforme o YouTube Studio; retenção média pode vir em % ou tempo.', + other: 'Plataforma não especificada: não é usada em comparação A/B.', +}; + +export interface ComputedRetentionMetrics { + metricVersion: number; + totalInteractions: number | null; + engagementRate: number | null; + completionPct: number | null; + watchTimeRelative: number | null; + interactionsPer1000: number | null; + interactionFields: string[]; + interactionCoverage: 'NONE' | 'PARTIAL' | 'FULL'; + missing: string[]; + warnings: string[]; +} + +function sumAvailable(values: Array): number | null { + const available = values.filter((value): value is number => value !== null); + return available.length ? available.reduce((sum, value) => sum + value, 0) : null; +} + +function round(value: number, digits = 4): number { + const factor = 10 ** digits; + return Math.round(value * factor) / factor; +} + +export function computeRetentionMetrics( + metrics: AnalyticsMetrics, + durationMs: number, +): ComputedRetentionMetrics { + if (!Number.isFinite(durationMs) || durationMs <= 0) + throw new RetentionError('RETENTION_DURATION_INVALID', 'Duração do episódio inválida.'); + if (metrics.avgWatchMs !== null && metrics.avgWatchMs > durationMs) + throw new RetentionError( + 'RETENTION_WATCH_EXCEEDS_DURATION', + 'Tempo médio assistido excede a duração do episódio.', + ); + const missing: string[] = []; + const warnings: string[] = []; + const interactionPairs = [ + ['likes', metrics.likes], + ['comments', metrics.comments], + ['shares', metrics.shares], + ['saves', metrics.saves], + ] as const; + const interactionFields = interactionPairs + .filter(([, value]) => value !== null) + .map(([field]) => field); + const interactionCoverage = + interactionFields.length === 0 + ? 'NONE' + : interactionFields.length === interactionPairs.length + ? 'FULL' + : 'PARTIAL'; + const totalInteractions = sumAvailable([ + metrics.likes, + metrics.comments, + metrics.shares, + metrics.saves, + ]); + if (totalInteractions === null) missing.push('interactions'); + else if (interactionCoverage === 'PARTIAL') warnings.push('PARTIAL_INTERACTIONS'); + if (metrics.views === null) missing.push('views'); + if (metrics.avgWatchMs === null) missing.push('avg_watch_ms'); + if (metrics.completionPct === null && metrics.avgWatchMs === null) missing.push('completion'); + + let engagementRate: number | null = null; + let interactionsPer1000: number | null = null; + if (metrics.views === null || metrics.views === 0) { + if (metrics.views === 0) warnings.push('ZERO_VIEWS'); + } else if (totalInteractions !== null) { + engagementRate = round(totalInteractions / metrics.views); + interactionsPer1000 = round((totalInteractions / metrics.views) * 1_000, 2); + } + + let watchTimeRelative: number | null = null; + if (metrics.avgWatchMs !== null) watchTimeRelative = round(metrics.avgWatchMs / durationMs); + + let completionPct = metrics.completionPct; + if (completionPct === null && metrics.avgWatchMs !== null) + completionPct = round((metrics.avgWatchMs / durationMs) * 100, 2); + else if (completionPct !== null) completionPct = round(completionPct, 2); + if ( + metrics.completionPct !== null && + metrics.avgWatchMs !== null && + Math.abs(metrics.completionPct - (metrics.avgWatchMs / durationMs) * 100) > 5 + ) + warnings.push('COMPLETION_DISCREPANCY'); + + if (metrics.views !== null && metrics.views < LOW_SAMPLE_VIEWS) warnings.push('LOW_SAMPLE'); + if (metrics.views !== null && metrics.views < (totalInteractions ?? 0)) + warnings.push('INTERACTIONS_EXCEED_VIEWS'); + return { + metricVersion: RETENTION_METRIC_VERSION, + totalInteractions, + engagementRate, + completionPct, + watchTimeRelative, + interactionsPer1000, + interactionFields, + interactionCoverage, + missing, + warnings, + }; +} + +export interface VariantObservation { + platform: string; + label: string; + variantLabel: string; + periodStart: string; + periodEnd: string; + views: number | null; + metrics: ComputedRetentionMetrics; +} + +export interface VariantComparison { + status: 'OBSERVATIONAL' | 'INSUFFICIENT' | 'NOT_COMPARABLE'; + metric: MetricDefinition['id']; + valueA: number | null; + valueB: number | null; + summary: string; + warnings: string[]; +} + +function metricValue(observation: VariantObservation, metric: MetricDefinition['id']) { + if (metric === 'engagement_rate') return observation.metrics.engagementRate; + if (metric === 'completion_pct') return observation.metrics.completionPct; + if (metric === 'watch_time_relative') return observation.metrics.watchTimeRelative; + return observation.metrics.interactionsPer1000; +} + +export function compareVariantObservations( + left: VariantObservation, + right: VariantObservation, + metric: MetricDefinition['id'] = 'engagement_rate', +): VariantComparison { + const warnings: string[] = []; + if (left.platform !== right.platform || left.platform === 'other') + return { + status: 'NOT_COMPARABLE', + metric, + valueA: null, + valueB: null, + summary: + left.platform === 'other' + ? 'Plataforma “other” não permite confirmar comparabilidade.' + : 'Plataformas diferentes: não há comparação válida.', + warnings: [left.platform === 'other' ? 'PLATFORM_UNSPECIFIED' : 'PLATFORM_MISMATCH'], + }; + const startA = Date.parse(left.periodStart); + const startB = Date.parse(right.periodStart); + const endA = Date.parse(left.periodEnd); + const endB = Date.parse(right.periodEnd); + const durationA = endA - startA; + const durationB = endB - startB; + if ( + !Number.isFinite(durationA) || + !Number.isFinite(durationB) || + durationA <= 0 || + durationB <= 0 + ) + return { + status: 'NOT_COMPARABLE', + metric, + valueA: null, + valueB: null, + summary: 'Períodos de coleta inválidos.', + warnings: ['PERIOD_INVALID'], + }; + if (Math.max(durationA, durationB) / Math.min(durationA, durationB) > 1.2) + return { + status: 'NOT_COMPARABLE', + metric, + valueA: null, + valueB: null, + summary: 'Períodos com durações diferentes: colete janelas equivalentes para comparar.', + warnings: ['PERIOD_LENGTH_MISMATCH'], + }; + if (startA !== startB || endA !== endB) warnings.push('DIFFERENT_WINDOWS'); + if (Math.abs(startA - startB) > 7 * 24 * 60 * 60 * 1000) warnings.push('DISTANT_WINDOWS'); + if ( + (metric === 'engagement_rate' || metric === 'interactions_per_1000') && + left.metrics.interactionFields.join(',') !== right.metrics.interactionFields.join(',') + ) + return { + status: 'INSUFFICIENT', + metric, + valueA: null, + valueB: null, + summary: + 'As variantes não têm os mesmos campos de interação disponíveis: insuficiente para conclusão.', + warnings: [...warnings, 'INTERACTION_COVERAGE_MISMATCH'], + }; + const valueA = metricValue(left, metric); + const valueB = metricValue(right, metric); + if (left.views === null || right.views === null) + return { + status: 'INSUFFICIENT', + metric, + valueA, + valueB, + summary: 'Views ausentes: insuficiente para qualquer conclusão.', + warnings: [...warnings, 'VIEWS_MISSING'], + }; + if (left.views < LOW_SAMPLE_VIEWS || right.views < LOW_SAMPLE_VIEWS) + return { + status: 'INSUFFICIENT', + metric, + valueA, + valueB, + summary: 'Amostra baixa (<1000 views): insuficiente para conclusão.', + warnings: [...warnings, 'LOW_SAMPLE'], + }; + if (Math.min(left.views, right.views) / Math.max(left.views, right.views) < 0.5) + warnings.push('SAMPLE_IMBALANCE'); + if (valueA === null || valueB === null) + return { + status: 'INSUFFICIENT', + metric, + valueA, + valueB, + summary: 'Métrica ausente em uma das variantes: insuficiente para conclusão.', + warnings: [...warnings, 'METRIC_MISSING'], + }; + const definition = RETENTION_METRIC_DEFINITIONS.find((entry) => entry.id === metric)!; + const higher = valueA === valueB ? null : valueA > valueB ? 'A' : 'B'; + return { + status: 'OBSERVATIONAL', + metric, + valueA, + valueB, + summary: + higher === null + ? `${definition.label}: valores observados iguais.` + : `${definition.label}: a variante ${higher} teve maior valor observado (${higher === 'A' ? valueA : valueB} vs ${higher === 'A' ? valueB : valueA}). Associação descritiva, não causalidade.`, + warnings, + }; +} + +export function parseCsvRows(input: string): string[][] { + if (input.length > 5_000_000) + throw new RetentionError('RETENTION_CSV_TOO_LARGE', 'CSV excede 5 MB.'); + const rows: string[][] = []; + let row: string[] = []; + let cell = ''; + let quoted = false; + for (let index = 0; index < input.length; index += 1) { + const character = input[index]; + if (quoted) { + if (character === '"') { + if (input[index + 1] === '"') { + cell += '"'; + index += 1; + } else quoted = false; + } else cell += character; + continue; + } + if (character === '"') quoted = true; + else if (character === ',') { + row.push(cell); + cell = ''; + } else if (character === '\n') { + row.push(cell.replace(/\r$/, '')); + rows.push(row); + row = []; + cell = ''; + } else cell += character; + } + if (cell.length || row.length) { + row.push(cell.replace(/\r$/, '')); + rows.push(row); + } + if (rows.length > 5_001) + throw new RetentionError('RETENTION_CSV_TOO_MANY_ROWS', 'CSV excede 5000 linhas.'); + return rows.filter((entry) => entry.some((value) => value.trim().length > 0)); +} + +function nullableInteger(value: string | undefined): number | null { + if (value === undefined || value.trim() === '' || value.trim().toLowerCase() === 'null') + return null; + const trimmed = value.trim(); + if (!/^\d+$/.test(trimmed)) + throw new RetentionError( + 'RETENTION_CSV_NUMBER', + `Número inteiro inválido: "${trimmed}". Use apenas dígitos, sem separador de milhar.`, + ); + return Number(trimmed); +} + +function nullableDecimal(value: string | undefined): number | null { + if (value === undefined || value.trim() === '' || value.trim().toLowerCase() === 'null') + return null; + const trimmed = value.trim(); + if (!/^\d+(\.\d+)?$/.test(trimmed)) + throw new RetentionError( + 'RETENTION_CSV_NUMBER', + `Decimal inválido: "${trimmed}". Use ponto como separador decimal.`, + ); + return Number(trimmed); +} + +export function parseRetentionCsv(input: string): { + rows: RetentionImportRow[]; + errors: Array<{ line: number; message: string }>; +} { + const table = parseCsvRows(input); + if (!table.length) throw new RetentionError('RETENTION_CSV_EMPTY', 'CSV vazio.'); + const header = table[0]!.map((value) => value.trim().toLowerCase()); + const required = [ + 'platform', + 'url', + 'published_at', + 'label', + 'period_start', + 'period_end', + 'captured_at', + 'views', + 'likes', + 'comments', + 'shares', + 'saves', + 'followers_gained', + 'avg_watch_ms', + 'completion_pct', + 'note', + ]; + const missing = required.filter((column) => !header.includes(column)); + if (missing.length) + throw new RetentionError( + 'RETENTION_CSV_HEADER', + `CSV sem colunas obrigatórias: ${missing.join(', ')}.`, + ); + const rows: RetentionImportRow[] = []; + const errors: Array<{ line: number; message: string }> = []; + for (const [offset, values] of table.slice(1).entries()) { + const record = Object.fromEntries(header.map((column, index) => [column, values[index] ?? ''])); + try { + rows.push( + retentionImportRowSchema.parse({ + platform: String(record.platform ?? '') + .trim() + .toLowerCase(), + url: record.url, + published_at: record.published_at, + label: record.label, + period_start: record.period_start, + period_end: record.period_end, + captured_at: record.captured_at, + views: nullableInteger(record.views), + likes: nullableInteger(record.likes), + comments: nullableInteger(record.comments), + shares: nullableInteger(record.shares), + saves: nullableInteger(record.saves), + followers_gained: nullableInteger(record.followers_gained), + avg_watch_ms: nullableInteger(record.avg_watch_ms), + completion_pct: nullableDecimal(record.completion_pct), + note: record.note, + }), + ); + } catch (cause) { + const message = + cause instanceof RetentionError + ? cause.message + : cause && typeof cause === 'object' && 'issues' in cause + ? (cause as { issues: Array<{ message: string }> }).issues[0]?.message + : 'Linha inválida.'; + errors.push({ line: offset + 2, message: message ?? 'Linha inválida.' }); + } + } + return { rows, errors }; +} + +/** Spreadsheet formula injection guard for owner-provided text. */ +export function sanitizeCsvCell(value: string | number | null): string { + if (value === null) return ''; + const text = String(value); + const dangerous = /^[=+\-@\t\r]/.test(text); + let escaped = text.replaceAll('"', '""'); + if (dangerous) + escaped = escaped + .split(/\r?\n/) + .map((line) => `'${line}`) + .join('\n'); + if (dangerous || /[",\n\r]/.test(text)) return `"${escaped}"`; + return escaped; +} + +export function retentionCsv(rows: Array>): string { + if (!rows.length) return ''; + const header = Object.keys(rows[0]!); + return [ + header.map(sanitizeCsvCell).join(','), + ...rows.map((row) => header.map((column) => sanitizeCsvCell(row[column] ?? null)).join(',')), + ].join('\r\n'); +} diff --git a/src/lib/schemas/retention.ts b/src/lib/schemas/retention.ts new file mode 100644 index 00000000..877f1446 --- /dev/null +++ b/src/lib/schemas/retention.ts @@ -0,0 +1,162 @@ +import { z } from 'zod'; + +const uuid = z.string().uuid(); +const count = z.number().int().min(0).max(1_000_000_000_000); +const nullableCount = count.nullable().default(null); + +export const RETENTION_PLATFORMS = ['tiktok', 'reels', 'youtube_shorts', 'other'] as const; +export const RETENTION_VARIANT_KINDS = ['HOOK', 'COVER', 'CTA', 'BASELINE'] as const; +export const RETENTION_SOURCES = ['MANUAL', 'CSV'] as const; +export const RETENTION_EXPERIMENT_STATUSES = ['DRAFT', 'ACTIVE', 'CLOSED'] as const; + +export type RetentionPlatform = (typeof RETENTION_PLATFORMS)[number]; +export type RetentionVariantKind = (typeof RETENTION_VARIANT_KINDS)[number]; +export type RetentionSource = (typeof RETENTION_SOURCES)[number]; +export type RetentionExperimentStatus = (typeof RETENTION_EXPERIMENT_STATUSES)[number]; + +const text = (minimum: number, maximum: number) => + z + .string() + .trim() + .min(minimum) + .max(maximum) + .refine((value) => !/\p{Cc}/u.test(value.replaceAll(/[\n\r\t]/g, '')), 'Texto inválido.'); + +export const retentionUrlSchema = z + .string() + .trim() + .min(8) + .max(500) + .refine((value) => { + try { + const url = new URL(value); + return ( + ['http:', 'https:'].includes(url.protocol) && + !url.username && + !url.password && + url.hostname.length > 3 + ); + } catch { + return false; + } + }, 'Informe uma URL http(s) pública fornecida pela plataforma.'); + +export const publishedPostInputSchema = z.object({ + episodeId: uuid, + platform: z.enum(RETENTION_PLATFORMS), + url: retentionUrlSchema, + publishedAt: z.string().datetime({ offset: true }), + label: text(0, 120).default(''), + notes: text(0, 1_000).default(''), + changeNote: text(0, 300).default(''), +}); + +export const creativeVariantInputSchema = z.object({ + postId: uuid, + kind: z.enum(RETENTION_VARIANT_KINDS), + label: text(1, 80), + hookVariantId: uuid.nullable().default(null), + coverRevisionId: uuid.nullable().default(null), + endCardId: uuid.nullable().default(null), +}); + +export const analyticsMetricsSchema = z + .object({ + views: nullableCount, + likes: nullableCount, + comments: nullableCount, + shares: nullableCount, + saves: nullableCount, + followersGained: count.nullable().default(null), + avgWatchMs: z.number().int().min(0).max(600_000).nullable().default(null), + completionPct: z.number().min(0).max(100).nullable().default(null), + }) + .superRefine((metrics, context) => { + if (metrics.completionPct !== null && Number.isNaN(metrics.completionPct)) + context.addIssue({ + code: 'custom', + path: ['completionPct'], + message: 'Percentual inválido.', + }); + }); + +export const analyticsSnapshotInputSchema = z + .object({ + postId: uuid, + capturedAt: z.string().datetime({ offset: true }), + periodStart: z.string().datetime({ offset: true }), + periodEnd: z.string().datetime({ offset: true }), + source: z.enum(RETENTION_SOURCES).default('MANUAL'), + note: text(0, 1_000).default(''), + supersedesSnapshotId: uuid.nullable().default(null), + metrics: analyticsMetricsSchema, + }) + .superRefine((snapshot, context) => { + const start = Date.parse(snapshot.periodStart); + const end = Date.parse(snapshot.periodEnd); + const captured = Date.parse(snapshot.capturedAt); + if (!(start < end)) + context.addIssue({ + code: 'custom', + path: ['periodEnd'], + message: 'O período precisa terminar depois do início.', + }); + if (captured < end) + context.addIssue({ + code: 'custom', + path: ['capturedAt'], + message: 'A coleta não pode ser anterior ao fim do período.', + }); + }); + +export const experimentInputSchema = z.object({ + episodeId: uuid, + name: text(1, 80), + variantAId: uuid, + variantBId: uuid, + hypothesis: text(0, 500).default(''), +}); + +export const retentionImportRowSchema = z + .object({ + platform: z.enum(RETENTION_PLATFORMS), + url: retentionUrlSchema, + published_at: z.string().datetime({ offset: true }), + label: text(0, 120).default(''), + period_start: z.string().datetime({ offset: true }), + period_end: z.string().datetime({ offset: true }), + captured_at: z.string().datetime({ offset: true }), + views: nullableCount, + likes: nullableCount, + comments: nullableCount, + shares: nullableCount, + saves: nullableCount, + followers_gained: count.nullable().default(null), + avg_watch_ms: z.number().int().min(0).max(600_000).nullable().default(null), + completion_pct: z.number().min(0).max(100).nullable().default(null), + note: text(0, 1_000).default(''), + }) + .superRefine((row, context) => { + const start = Date.parse(row.period_start); + const end = Date.parse(row.period_end); + const captured = Date.parse(row.captured_at); + if (!(start < end)) + context.addIssue({ + code: 'custom', + path: ['period_end'], + message: 'Período termina antes do início.', + }); + if (!(captured >= end)) + context.addIssue({ + code: 'custom', + path: ['captured_at'], + message: 'Coleta anterior ao fim do período.', + }); + }); + +export type PublishedPostInput = z.infer; +export type CreativeVariantInput = z.infer; +export type AnalyticsSnapshotInput = z.infer; +export type AnalyticsMetrics = z.infer; +export type RetentionImportRow = z.infer; +export type ExperimentInput = z.infer; diff --git a/src/lib/server/retention.ts b/src/lib/server/retention.ts new file mode 100644 index 00000000..276dad84 --- /dev/null +++ b/src/lib/server/retention.ts @@ -0,0 +1,783 @@ +import { createHash } from 'node:crypto'; +import type { SupabaseClient, User } from '@supabase/supabase-js'; +import { canonicalJson } from '#lib/domain/canonical-json.js'; +import { + compareVariantObservations, + computeRetentionMetrics, + parseRetentionCsv, + RetentionError, + type ComputedRetentionMetrics, + type VariantObservation, +} from '#lib/domain/retention.js'; +import { + analyticsSnapshotInputSchema, + creativeVariantInputSchema, + experimentInputSchema, + publishedPostInputSchema, + type AnalyticsSnapshotInput, + type CreativeVariantInput, + type ExperimentInput, + type PublishedPostInput, + type RetentionPlatform, + type RetentionVariantKind, +} from '#lib/schemas/retention.js'; +import { firstRelation } from './relations.js'; + +export class RetentionServiceError extends Error { + constructor( + readonly status: number, + readonly code: string, + message: string, + ) { + super(message); + this.name = 'RetentionServiceError'; + } +} + +interface PostRow { + id: string; + episode_id: string; + platform: string; + url: string; + published_at: string; + label: string; + notes: string; + created_at: string; + updated_at: string; +} + +interface VariantRow { + id: string; + post_id: string; + kind: string; + label: string; + hook_variant_id: string | null; + cover_revision_id: string | null; + end_card_id: string | null; + created_at: string; +} + +interface SnapshotRow { + id: string; + post_id: string; + revision_number: number; + supersedes_snapshot_id: string | null; + captured_at: string; + period_start: string; + period_end: string; + source: string; + note: string; + views: number | string | null; + likes: number | string | null; + comments: number | string | null; + shares: number | string | null; + saves: number | string | null; + followers_gained: number | string | null; + avg_watch_ms: number | null; + completion_pct: number | string | null; + metric_version: number; + episode_duration_ms: number; + snapshot_hash: string; + created_at: string; +} + +export interface RetentionSnapshot { + id: string; + postId: string; + revision: number; + supersedesSnapshotId: string | null; + capturedAt: string; + periodStart: string; + periodEnd: string; + source: string; + note: string; + metrics: { + views: number | null; + likes: number | null; + comments: number | null; + shares: number | null; + saves: number | null; + followersGained: number | null; + avgWatchMs: number | null; + completionPct: number | null; + }; + computed: ComputedRetentionMetrics; + snapshotHash: string; + createdAt: string; +} + +export interface RetentionPost { + id: string; + episodeId: string; + platform: RetentionPlatform; + url: string; + publishedAt: string; + label: string; + notes: string; + variants: Array<{ + id: string; + kind: RetentionVariantKind; + label: string; + hookVariantId: string | null; + coverRevisionId: string | null; + endCardId: string | null; + }>; + latestSnapshot: RetentionSnapshot | null; + snapshots: RetentionSnapshot[]; + snapshotCount: number; +} + +export interface RetentionContext { + episode: { + id: string; + title: string; + number: number; + durationMs: number; + seriesTitle: string; + }; + posts: RetentionPost[]; + experiments: Array<{ + id: string; + name: string; + hypothesis: string; + status: string; + variantAId: string; + variantBId: string; + snapshotAId: string | null; + snapshotBId: string | null; + }>; + imports: Array<{ + id: string; + filename: string; + rowCount: number; + importedCount: number; + skippedCount: number; + errorCount: number; + createdAt: string; + }>; +} + +function mapRpcError(error: { code?: string; message?: string }): RetentionServiceError { + if (error.code === 'P0002') + return new RetentionServiceError(404, 'RETENTION_NOT_FOUND', 'Registro não encontrado.'); + if (error.code === '42501') + return new RetentionServiceError(403, 'RETENTION_FORBIDDEN', 'Acesso não autorizado.'); + if (error.code === '55000') + return new RetentionServiceError( + 409, + 'RETENTION_IMMUTABLE', + 'O histórico de retenção é imutável; retifique criando um novo snapshot.', + ); + if (error.code === '23505') + return new RetentionServiceError( + 409, + 'RETENTION_DUPLICATE', + 'Já existe um registro com estes dados.', + ); + if (error.code === '23514') { + const message = error.message ?? ''; + if (message.includes('retention_hook_variant_invalid')) + return new RetentionServiceError( + 409, + 'RETENTION_HOOK_INVALID', + 'A variação de hook não pertence a este episódio.', + ); + if (message.includes('retention_cover_invalid')) + return new RetentionServiceError( + 409, + 'RETENTION_COVER_INVALID', + 'A capa não pertence a este episódio.', + ); + if (message.includes('retention_end_card_invalid')) + return new RetentionServiceError( + 409, + 'RETENTION_END_CARD_INVALID', + 'O final A/B não pertence a este episódio.', + ); + if (message.includes('retention_snapshot_quota')) + return new RetentionServiceError( + 409, + 'RETENTION_QUOTA', + 'Limite de 5000 snapshots por publicação atingido.', + ); + return new RetentionServiceError(400, 'RETENTION_INVALID', 'Dados de retenção inválidos.'); + } + return new RetentionServiceError( + 503, + 'RETENTION_FAILED', + 'Não foi possível processar o laboratório de retenção.', + ); +} + +function numberOrNull(value: number | string | null): number | null { + if (value === null) return null; + const parsed = Number(value); + return Number.isFinite(parsed) ? parsed : null; +} + +function invalidComputed(warnings: string[]): ComputedRetentionMetrics { + return { + metricVersion: 0, + totalInteractions: null, + engagementRate: null, + completionPct: null, + watchTimeRelative: null, + interactionsPer1000: null, + interactionFields: [], + interactionCoverage: 'NONE', + missing: ['computed'], + warnings, + }; +} + +function parseSnapshot(row: SnapshotRow, fallbackDurationMs: number): RetentionSnapshot { + const metrics = { + views: numberOrNull(row.views), + likes: numberOrNull(row.likes), + comments: numberOrNull(row.comments), + shares: numberOrNull(row.shares), + saves: numberOrNull(row.saves), + followersGained: numberOrNull(row.followers_gained), + avgWatchMs: row.avg_watch_ms, + completionPct: numberOrNull(row.completion_pct), + }; + const durationMs = Number(row.episode_duration_ms) || fallbackDurationMs; + let computed: ComputedRetentionMetrics; + try { + computed = computeRetentionMetrics(metrics, durationMs); + if (Number(row.metric_version) !== 1) + computed = { + ...computed, + warnings: [...computed.warnings, 'METRIC_VERSION_UNSUPPORTED'], + }; + } catch (cause) { + computed = invalidComputed([cause instanceof RetentionError ? cause.code : 'INVALID_METRICS']); + } + return { + id: row.id, + postId: row.post_id, + revision: Number(row.revision_number), + supersedesSnapshotId: row.supersedes_snapshot_id, + capturedAt: row.captured_at, + periodStart: row.period_start, + periodEnd: row.period_end, + source: row.source, + note: row.note, + metrics, + computed, + snapshotHash: row.snapshot_hash, + createdAt: row.created_at, + }; +} + +const RETENTION_PAGE_SIZE = 1_000; + +async function loadPagedRows( + db: SupabaseClient, + table: 'creative_variants' | 'analytics_snapshots', + ownerId: string, + postIds: string[], + orderColumn: string, + ascending: boolean, +): Promise { + const rows: T[] = []; + for (let from = 0; from < 50_000; from += RETENTION_PAGE_SIZE) { + const { data, error } = await db + .from(table) + .select('*') + .eq('owner_id', ownerId) + .in('post_id', postIds) + .order(orderColumn, { ascending }) + .order('created_at', { ascending: false }) + .range(from, from + RETENTION_PAGE_SIZE - 1); + if (error) + throw new RetentionServiceError( + 503, + 'RETENTION_LOAD_FAILED', + 'Não foi possível carregar a retenção.', + ); + const page = (data ?? []) as T[]; + rows.push(...page); + if (page.length < RETENTION_PAGE_SIZE) break; + } + return rows; +} + +export async function loadRetentionContext( + db: SupabaseClient, + owner: User, + episodeId: string, +): Promise { + const [episodeResult, postsResult, experimentsResult, importsResult] = await Promise.all([ + db + .from('episodes') + .select('id,title,episode_number,duration_ms,seasons(series(title))') + .eq('owner_id', owner.id) + .eq('id', episodeId) + .maybeSingle(), + db + .from('published_posts') + .select('*') + .eq('owner_id', owner.id) + .eq('episode_id', episodeId) + .order('published_at', { ascending: false }) + .limit(100), + db + .from('retention_experiments') + .select('*') + .eq('owner_id', owner.id) + .eq('episode_id', episodeId) + .order('created_at', { ascending: false }) + .limit(50), + db + .from('retention_imports') + .select('*') + .eq('owner_id', owner.id) + .order('created_at', { ascending: false }) + .limit(20), + ]); + if (episodeResult.error) + throw new RetentionServiceError( + 503, + 'RETENTION_LOAD_FAILED', + 'Não foi possível carregar o episódio.', + ); + if (!episodeResult.data) return null; + if (postsResult.error || experimentsResult.error || importsResult.error) + throw new RetentionServiceError( + 503, + 'RETENTION_LOAD_FAILED', + 'Não foi possível carregar a retenção.', + ); + const season = firstRelation(episodeResult.data.seasons); + const durationMs = Number(episodeResult.data.duration_ms); + const posts = (postsResult.data ?? []) as PostRow[]; + const postIds = posts.map((post) => post.id); + let variants: VariantRow[] = []; + let snapshots: SnapshotRow[] = []; + if (postIds.length) { + [variants, snapshots] = await Promise.all([ + loadPagedRows(db, 'creative_variants', owner.id, postIds, 'created_at', true), + loadPagedRows( + db, + 'analytics_snapshots', + owner.id, + postIds, + 'revision_number', + false, + ), + ]); + } + const historyByPost = new Map(); + const latestByPost = new Map(); + for (const row of snapshots) { + const parsed = parseSnapshot(row, durationMs); + const history = historyByPost.get(row.post_id) ?? []; + history.push(parsed); + historyByPost.set(row.post_id, history); + if (!latestByPost.has(row.post_id)) latestByPost.set(row.post_id, parsed); + } + return { + episode: { + id: episodeResult.data.id as string, + title: episodeResult.data.title as string, + number: Number(episodeResult.data.episode_number), + durationMs, + seriesTitle: + ((season as { series?: unknown } | null)?.series as { title?: string } | null)?.title ?? + 'Série', + }, + posts: posts.map((post) => ({ + id: post.id, + episodeId: post.episode_id, + platform: post.platform as RetentionPlatform, + url: post.url, + publishedAt: post.published_at, + label: post.label, + notes: post.notes, + variants: variants + .filter((variant) => variant.post_id === post.id) + .map((variant) => ({ + id: variant.id, + kind: variant.kind as RetentionVariantKind, + label: variant.label, + hookVariantId: variant.hook_variant_id, + coverRevisionId: variant.cover_revision_id, + endCardId: variant.end_card_id, + })), + latestSnapshot: latestByPost.get(post.id) ?? null, + snapshots: historyByPost.get(post.id) ?? [], + snapshotCount: historyByPost.get(post.id)?.length ?? 0, + })), + experiments: ((experimentsResult.data ?? []) as Array>).map((row) => ({ + id: row.id as string, + name: row.name as string, + hypothesis: row.hypothesis as string, + status: row.status as string, + variantAId: row.variant_a_id as string, + variantBId: row.variant_b_id as string, + snapshotAId: (row.variant_a_snapshot_id as string | null) ?? null, + snapshotBId: (row.variant_b_snapshot_id as string | null) ?? null, + })), + imports: ((importsResult.data ?? []) as Array>).map((row) => ({ + id: row.id as string, + filename: row.filename as string, + rowCount: Number(row.row_count), + importedCount: Number(row.imported_count), + skippedCount: Number(row.skipped_count), + errorCount: Number(row.error_count), + createdAt: row.created_at as string, + })), + }; +} + +export async function savePublishedPost(input: { + db: SupabaseClient; + adminDb: SupabaseClient | null; + owner: User; + postId?: string | null; + values: PublishedPostInput; +}): Promise { + const parsed = publishedPostInputSchema.safeParse(input.values); + if (!parsed.success) + throw new RetentionServiceError(400, 'RETENTION_POST_INVALID', 'Publicação inválida.'); + if (!input.adminDb) + throw new RetentionServiceError( + 503, + 'RETENTION_WRITE_UNAVAILABLE', + 'O writer de retenção não está configurado.', + ); + const { data, error } = await input.adminDb.rpc('save_published_post', { + p_owner_id: input.owner.id, + p_post_id: input.postId ?? null, + p_episode_id: parsed.data.episodeId, + p_platform: parsed.data.platform, + p_url: parsed.data.url, + p_published_at: parsed.data.publishedAt, + p_label: parsed.data.label, + p_notes: parsed.data.notes, + p_change_note: parsed.data.changeNote, + }); + if (error) throw mapRpcError(error); + if (typeof data !== 'string') + throw new RetentionServiceError( + 503, + 'RETENTION_SAVE_FAILED', + 'O servidor não retornou a publicação.', + ); + return data; +} + +export async function saveCreativeVariant(input: { + adminDb: SupabaseClient | null; + owner: User; + values: CreativeVariantInput; +}): Promise { + const parsed = creativeVariantInputSchema.safeParse(input.values); + if (!parsed.success) + throw new RetentionServiceError(400, 'RETENTION_VARIANT_INVALID', 'Variante inválida.'); + if (!input.adminDb) + throw new RetentionServiceError( + 503, + 'RETENTION_WRITE_UNAVAILABLE', + 'O writer de retenção não está configurado.', + ); + const { data, error } = await input.adminDb.rpc('save_creative_variant', { + p_owner_id: input.owner.id, + p_post_id: parsed.data.postId, + p_kind: parsed.data.kind, + p_label: parsed.data.label, + p_hook_variant_id: parsed.data.hookVariantId, + p_cover_revision_id: parsed.data.coverRevisionId, + p_end_card_id: parsed.data.endCardId, + }); + if (error) throw mapRpcError(error); + if (typeof data !== 'string') + throw new RetentionServiceError( + 503, + 'RETENTION_SAVE_FAILED', + 'O servidor não retornou a variante.', + ); + return data; +} + +export function snapshotHash(input: AnalyticsSnapshotInput, durationMs: number): string { + return createHash('sha256') + .update( + canonicalJson({ + postId: input.postId, + periodStart: input.periodStart, + periodEnd: input.periodEnd, + source: input.source, + metrics: input.metrics, + episodeDurationMs: durationMs, + }), + ) + .digest('hex'); +} + +export async function saveAnalyticsSnapshot(input: { + db: SupabaseClient; + adminDb: SupabaseClient | null; + owner: User; + values: AnalyticsSnapshotInput; + durationMs: number; +}): Promise<{ revision: number; duplicate: boolean }> { + const parsed = analyticsSnapshotInputSchema.safeParse(input.values); + if (!parsed.success) + throw new RetentionServiceError(400, 'RETENTION_SNAPSHOT_INVALID', 'Snapshot inválido.'); + try { + computeRetentionMetrics(parsed.data.metrics, input.durationMs); + } catch (cause) { + if (cause instanceof RetentionError) + throw new RetentionServiceError(400, cause.code, cause.message); + throw cause; + } + if (!input.adminDb) + throw new RetentionServiceError( + 503, + 'RETENTION_WRITE_UNAVAILABLE', + 'O writer de retenção não está configurado.', + ); + const hash = snapshotHash(parsed.data, input.durationMs); + const { data: existing } = await input.db + .from('analytics_snapshots') + .select('revision_number') + .eq('owner_id', input.owner.id) + .eq('post_id', parsed.data.postId) + .eq('snapshot_hash', hash) + .maybeSingle(); + if (existing) return { revision: Number(existing.revision_number), duplicate: true }; + const metrics = parsed.data.metrics; + const { data, error } = await input.adminDb.rpc('save_analytics_snapshot', { + p_owner_id: input.owner.id, + p_post_id: parsed.data.postId, + p_captured_at: parsed.data.capturedAt, + p_period_start: parsed.data.periodStart, + p_period_end: parsed.data.periodEnd, + p_source: parsed.data.source, + p_note: parsed.data.note, + p_views: metrics.views, + p_likes: metrics.likes, + p_comments: metrics.comments, + p_shares: metrics.shares, + p_saves: metrics.saves, + p_followers_gained: metrics.followersGained, + p_avg_watch_ms: metrics.avgWatchMs, + p_completion_pct: metrics.completionPct, + p_episode_duration_ms: input.durationMs, + p_snapshot_hash: hash, + p_supersedes_snapshot_id: parsed.data.supersedesSnapshotId, + p_import_id: null, + }); + if (error?.code === '23505') { + const { data: raced } = await input.db + .from('analytics_snapshots') + .select('revision_number') + .eq('owner_id', input.owner.id) + .eq('post_id', parsed.data.postId) + .eq('snapshot_hash', hash) + .maybeSingle(); + if (raced) return { revision: Number(raced.revision_number), duplicate: true }; + throw new RetentionServiceError( + 409, + 'RETENTION_CONFLICT', + 'Outra coleta foi gravada ao mesmo tempo. Recarregue e tente novamente.', + ); + } + if (error) throw mapRpcError(error); + if (typeof data !== 'number') + throw new RetentionServiceError( + 503, + 'RETENTION_SAVE_FAILED', + 'O servidor não retornou a revisão.', + ); + return { revision: data, duplicate: false }; +} + +export async function importRetentionCsv(input: { + db: SupabaseClient; + adminDb: SupabaseClient | null; + owner: User; + episodeId: string; + filename: string; + csv: string; + durationMs: number; +}): Promise<{ + imported: number; + skipped: number; + errors: Array<{ line: number; message: string }>; +}> { + const parsed = parseRetentionCsv(input.csv); + let imported = 0; + let skipped = 0; + for (const [rowIndex, row] of parsed.rows.entries()) { + try { + const postId = await savePublishedPost({ + db: input.db, + adminDb: input.adminDb, + owner: input.owner, + values: { + episodeId: input.episodeId, + platform: row.platform, + url: row.url, + publishedAt: row.published_at, + label: row.label, + notes: '', + changeNote: `CSV ${input.filename}`, + }, + }); + const result = await saveAnalyticsSnapshot({ + db: input.db, + adminDb: input.adminDb, + owner: input.owner, + durationMs: input.durationMs, + values: { + postId, + capturedAt: row.captured_at, + periodStart: row.period_start, + periodEnd: row.period_end, + source: 'CSV', + note: row.note, + supersedesSnapshotId: null, + metrics: { + views: row.views, + likes: row.likes, + comments: row.comments, + shares: row.shares, + saves: row.saves, + followersGained: row.followers_gained, + avgWatchMs: row.avg_watch_ms, + completionPct: row.completion_pct, + }, + }, + }); + if (result.duplicate) skipped += 1; + else imported += 1; + } catch (cause) { + parsed.errors.push({ + line: rowIndex + 2, + message: cause instanceof Error ? cause.message : 'Falha ao importar linha.', + }); + } + } + if (input.adminDb) { + const sha256 = createHash('sha256').update(input.csv).digest('hex'); + await input.adminDb.rpc('save_retention_import', { + p_owner_id: input.owner.id, + p_filename: input.filename.slice(0, 120), + p_sha256: sha256, + p_row_count: parsed.rows.length + parsed.errors.length, + p_imported_count: imported, + p_skipped_count: skipped, + p_error_count: parsed.errors.length, + }); + } + return { imported, skipped, errors: parsed.errors }; +} + +export async function saveRetentionExperiment(input: { + adminDb: SupabaseClient | null; + owner: User; + values: ExperimentInput; +}): Promise { + const parsed = experimentInputSchema.safeParse(input.values); + if (!parsed.success) + throw new RetentionServiceError(400, 'RETENTION_EXPERIMENT_INVALID', 'Experimento inválido.'); + if (!input.adminDb) + throw new RetentionServiceError( + 503, + 'RETENTION_WRITE_UNAVAILABLE', + 'O writer de retenção não está configurado.', + ); + const { data, error } = await input.adminDb.rpc('save_retention_experiment', { + p_owner_id: input.owner.id, + p_episode_id: parsed.data.episodeId, + p_name: parsed.data.name, + p_variant_a_id: parsed.data.variantAId, + p_variant_b_id: parsed.data.variantBId, + p_hypothesis: parsed.data.hypothesis, + }); + if (error) throw mapRpcError(error); + if (typeof data !== 'string') + throw new RetentionServiceError( + 503, + 'RETENTION_SAVE_FAILED', + 'O servidor não retornou o experimento.', + ); + return data; +} + +export async function deletePublishedPost(input: { + adminDb: SupabaseClient | null; + owner: User; + postId: string; +}): Promise { + if (!input.adminDb) + throw new RetentionServiceError( + 503, + 'RETENTION_WRITE_UNAVAILABLE', + 'O writer de retenção não está configurado.', + ); + const { error } = await input.adminDb.rpc('delete_published_post', { + p_owner_id: input.owner.id, + p_post_id: input.postId, + }); + if (error) throw mapRpcError(error); +} + +export function variantObservation( + post: RetentionPost, + variant: RetentionPost['variants'][number], + snapshotId?: string | null, +): VariantObservation | null { + const snapshot = snapshotId + ? post.snapshots.find((candidate) => candidate.id === snapshotId) + : post.latestSnapshot; + if (!snapshot) return null; + return { + platform: post.platform, + label: post.label || post.url, + variantLabel: variant.label, + periodStart: snapshot.periodStart, + periodEnd: snapshot.periodEnd, + views: snapshot.metrics.views, + metrics: snapshot.computed, + }; +} + +export function comparePostVariants( + context: RetentionContext, + experiment: RetentionContext['experiments'][number], + metric: Parameters[2], +) { + const variants = new Map< + string, + { post: RetentionPost; variant: RetentionPost['variants'][number] } + >(); + for (const post of context.posts) + for (const variant of post.variants) variants.set(variant.id, { post, variant }); + const left = variants.get(experiment.variantAId); + const right = variants.get(experiment.variantBId); + if (!left || !right) + return { + status: 'NOT_COMPARABLE' as const, + metric, + valueA: null, + valueB: null, + summary: 'Variantes do experimento não estão mais disponíveis.', + warnings: ['VARIANT_MISSING'], + }; + const leftObservation = variantObservation(left.post, left.variant, experiment.snapshotAId); + const rightObservation = variantObservation(right.post, right.variant, experiment.snapshotBId); + if (!leftObservation || !rightObservation) + return { + status: 'INSUFFICIENT' as const, + metric, + valueA: null, + valueB: null, + summary: 'Falta snapshot em uma das variantes.', + warnings: ['SNAPSHOT_MISSING'], + }; + return compareVariantObservations(leftObservation, rightObservation, metric); +} diff --git a/src/routes/api/backup/manifest/+server.ts b/src/routes/api/backup/manifest/+server.ts index 82831687..f2c7b592 100644 --- a/src/routes/api/backup/manifest/+server.ts +++ b/src/routes/api/backup/manifest/+server.ts @@ -34,6 +34,12 @@ const TABLES = [ 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards', + 'published_posts', + 'published_post_versions', + 'creative_variants', + 'retention_imports', + 'analytics_snapshots', + 'retention_experiments', ] as const; export const GET: RequestHandler = async (event) => { diff --git a/src/routes/api/retention/export/+server.ts b/src/routes/api/retention/export/+server.ts new file mode 100644 index 00000000..471c5578 --- /dev/null +++ b/src/routes/api/retention/export/+server.ts @@ -0,0 +1,112 @@ +import { error } from '@sveltejs/kit'; +import type { RequestHandler } from './$types'; +import { ownerDatabase } from '#lib/server/authorized.js'; +import { loadRetentionContext } from '#lib/server/retention.js'; +import { RETENTION_METRIC_DEFINITIONS, retentionCsv } from '#lib/domain/retention.js'; + +export const GET: RequestHandler = async (event) => { + const { db, owner } = ownerDatabase(event); + const episodeId = event.url.searchParams.get('episodeId') ?? ''; + if (!/^[0-9a-f-]{36}$/i.test(episodeId)) error(400, 'Episódio inválido.'); + const format = event.url.searchParams.get('format') === 'json' ? 'json' : 'csv'; + const context = await loadRetentionContext(db, owner, episodeId); + if (!context) error(404, 'Episódio não encontrado.'); + const rows = context.posts.flatMap((post) => { + const variantLabels = post.variants + .map((variant) => `${variant.kind}:${variant.label}`) + .join('|'); + if (!post.latestSnapshot) + return [ + { + episode: context.episode.title, + platform: post.platform, + url: post.url, + label: post.label, + published_at: post.publishedAt, + variants: variantLabels, + period_start: '', + period_end: '', + captured_at: '', + source: '', + views: null, + likes: null, + comments: null, + shares: null, + saves: null, + followers_gained: null, + avg_watch_ms: null, + completion_pct: null, + engagement_rate: null, + watch_time_relative: null, + interactions_per_1000: null, + missing: 'snapshot', + warnings: 'NO_SNAPSHOT', + note: post.notes, + }, + ]; + const snapshot = post.latestSnapshot; + return [ + { + episode: context.episode.title, + platform: post.platform, + url: post.url, + label: post.label, + published_at: post.publishedAt, + variants: variantLabels, + period_start: snapshot.periodStart, + period_end: snapshot.periodEnd, + captured_at: snapshot.capturedAt, + source: snapshot.source, + views: snapshot.metrics.views, + likes: snapshot.metrics.likes, + comments: snapshot.metrics.comments, + shares: snapshot.metrics.shares, + saves: snapshot.metrics.saves, + followers_gained: snapshot.metrics.followersGained, + avg_watch_ms: snapshot.metrics.avgWatchMs, + completion_pct: snapshot.metrics.completionPct, + engagement_rate: snapshot.computed.engagementRate, + watch_time_relative: snapshot.computed.watchTimeRelative, + interactions_per_1000: snapshot.computed.interactionsPer1000, + missing: snapshot.computed.missing.join('|'), + warnings: snapshot.computed.warnings.join('|'), + note: snapshot.note, + }, + ]; + }); + const filename = `retention-${context.episode.number}-${episodeId.slice(0, 8)}.${format}`; + if (format === 'json') + return new Response( + JSON.stringify( + { + format: 'dif-studio-retention/v1', + episode: context.episode, + metricVersion: 1, + definitions: RETENTION_METRIC_DEFINITIONS, + caveat: + 'Métricas agregadas fornecidas manualmente; associações descritivas, não causalidade.', + posts: context.posts, + experiments: context.experiments, + imports: context.imports, + }, + null, + 2, + ), + { + headers: { + 'content-type': 'application/json; charset=utf-8', + 'cache-control': 'private, no-store', + 'content-disposition': `attachment; filename="${filename}"`, + 'x-content-type-options': 'nosniff', + }, + }, + ); + return new Response(retentionCsv(rows), { + headers: { + 'content-type': 'text/csv; charset=utf-8', + 'cache-control': 'private, no-store', + 'content-disposition': `attachment; filename="${filename}"`, + 'x-content-type-options': 'nosniff', + }, + }); +}; diff --git a/src/routes/app/retention/+page.server.ts b/src/routes/app/retention/+page.server.ts new file mode 100644 index 00000000..8da06427 --- /dev/null +++ b/src/routes/app/retention/+page.server.ts @@ -0,0 +1,336 @@ +import { fail, redirect } from '@sveltejs/kit'; +import type { Actions, PageServerLoad } from './$types'; +import { ownerDatabase, readFormText } from '#lib/server/authorized.js'; +import { createSupabaseAdminClient } from '#lib/server/supabase.js'; +import { loadOwnerEpisodeSelection } from '#lib/server/episode-options.js'; +import { + comparePostVariants, + deletePublishedPost, + importRetentionCsv, + loadRetentionContext, + RetentionServiceError, + saveAnalyticsSnapshot, + saveCreativeVariant, + savePublishedPost, + saveRetentionExperiment, +} from '#lib/server/retention.js'; +import { RETENTION_METRIC_DEFINITIONS, RetentionError } from '#lib/domain/retention.js'; + +function messageFor(cause: unknown): { status: number; message: string } { + if (cause instanceof RetentionServiceError) + return { status: cause.status, message: cause.message }; + if (cause instanceof RetentionError) return { status: 400, message: cause.message }; + return { status: 503, message: 'Não foi possível processar a retenção.' }; +} + +function rethrowRedirect(cause: unknown): void { + if (cause && typeof cause === 'object' && 'location' in cause) throw cause; +} + +function utcDate(value: string): string { + return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(value) ? `${value}:00Z` : value; +} + +function nullableMetric(value: string, integer = true): number | null { + if (!value.trim()) return null; + const trimmed = value.trim(); + const pattern = integer ? /^\d+$/ : /^\d+(\.\d+)?$/; + if (!pattern.test(trimmed)) + throw new RetentionError( + 'RETENTION_NUMBER_INVALID', + `Valor inválido: "${trimmed}". Use dígitos${integer ? '' : ' e ponto decimal'}, sem separador de milhar.`, + ); + return Number(trimmed); +} + +export const load: PageServerLoad = async (event) => { + const { db, owner } = ownerDatabase(event); + const { episodes, selectedEpisode } = await loadOwnerEpisodeSelection( + db, + owner, + event.url.searchParams.get('episodeId'), + ); + if (!selectedEpisode) + return { + episodes, + selectedEpisode: null, + context: null, + metrics: RETENTION_METRIC_DEFINITIONS, + comparisons: [], + refs: { hooks: [], covers: [], endCards: [] }, + loadError: 'Crie um episódio antes de registrar publicações.', + notice: null, + }; + let context; + try { + context = await loadRetentionContext(db, owner, selectedEpisode.id); + } catch (cause) { + const info = messageFor(cause); + return { + episodes, + selectedEpisode, + context: null, + metrics: RETENTION_METRIC_DEFINITIONS, + comparisons: [], + refs: { hooks: [], covers: [], endCards: [] }, + loadError: info.message, + notice: null, + }; + } + if (!context) + return { + episodes, + selectedEpisode, + context: null, + metrics: RETENTION_METRIC_DEFINITIONS, + comparisons: [], + refs: { hooks: [], covers: [], endCards: [] }, + loadError: 'Episódio não encontrado.', + notice: null, + }; + const [hooks, covers, endCards] = await Promise.all([ + db + .from('hook_variants') + .select('id,label,variant_key') + .eq('owner_id', owner.id) + .eq('episode_id', selectedEpisode.id) + .eq('status', 'APPLIED') + .order('created_at', { ascending: false }) + .limit(20), + db + .from('cover_revisions') + .select('id,revision_number,template_id,format') + .eq('owner_id', owner.id) + .eq('episode_id', selectedEpisode.id) + .eq('status', 'APPROVED') + .order('revision_number', { ascending: false }) + .limit(10), + db + .from('choice_end_cards') + .select('id,revision_number,template_id,layout') + .eq('owner_id', owner.id) + .eq('episode_id', selectedEpisode.id) + .eq('status', 'APPROVED') + .order('revision_number', { ascending: false }) + .limit(10), + ]); + const metric = RETENTION_METRIC_DEFINITIONS.some( + (definition) => definition.id === event.url.searchParams.get('metric'), + ) + ? (event.url.searchParams.get('metric') as (typeof RETENTION_METRIC_DEFINITIONS)[number]['id']) + : 'engagement_rate'; + const comparisons = context.experiments.map((experiment) => ({ + experiment, + comparison: comparePostVariants(context, experiment, metric), + })); + const imported = Number(event.url.searchParams.get('imported') ?? ''); + const skipped = Number(event.url.searchParams.get('skipped') ?? ''); + const errors = Number(event.url.searchParams.get('errors') ?? ''); + const notice = + Number.isSafeInteger(imported) && (imported > 0 || skipped > 0 || errors > 0) + ? { + mode: 'imported' as const, + imported, + skipped, + errors, + detail: (event.url.searchParams.get('detail') ?? '').slice(0, 300), + } + : event.url.searchParams.get('saved') + ? { mode: 'saved' as const, imported: 0, skipped: 0, errors: 0, detail: '' } + : null; + return { + episodes, + selectedEpisode, + context, + metrics: RETENTION_METRIC_DEFINITIONS, + comparisons, + metric, + refs: { + hooks: hooks.data ?? [], + covers: covers.data ?? [], + endCards: endCards.data ?? [], + }, + loadError: null, + notice, + }; +}; + +export const actions: Actions = { + post: async (event) => { + const { db, owner } = ownerDatabase(event); + const form = await event.request.formData(); + const episodeId = readFormText(form, 'episodeId'); + if (!episodeId) return fail(400, { message: 'Episódio inválido.' }); + try { + await savePublishedPost({ + db, + adminDb: createSupabaseAdminClient(), + owner, + postId: readFormText(form, 'postId') || null, + values: { + episodeId, + platform: readFormText(form, 'platform') as never, + url: readFormText(form, 'url'), + publishedAt: utcDate(readFormText(form, 'publishedAt')), + label: readFormText(form, 'label'), + notes: readFormText(form, 'notes'), + changeNote: readFormText(form, 'changeNote') || 'Cadastro manual', + }, + }); + redirect(303, `/app/retention?episodeId=${episodeId}&saved=post`); + } catch (cause) { + rethrowRedirect(cause); + if (cause instanceof Error && cause.name === 'ZodError') + return fail(400, { message: 'Plataforma, URL ou data inválidas.' }); + const info = messageFor(cause); + return fail(info.status, { message: info.message }); + } + }, + variant: async (event) => { + const { owner } = ownerDatabase(event); + const form = await event.request.formData(); + const episodeId = readFormText(form, 'episodeId'); + if (!episodeId) return fail(400, { message: 'Episódio inválido.' }); + try { + await saveCreativeVariant({ + adminDb: createSupabaseAdminClient(), + owner, + values: { + postId: readFormText(form, 'postId'), + kind: readFormText(form, 'kind') as never, + label: readFormText(form, 'label'), + hookVariantId: readFormText(form, 'hookVariantId') || null, + coverRevisionId: readFormText(form, 'coverRevisionId') || null, + endCardId: readFormText(form, 'endCardId') || null, + }, + }); + redirect(303, `/app/retention?episodeId=${episodeId}&saved=variant`); + } catch (cause) { + rethrowRedirect(cause); + if (cause instanceof Error && cause.name === 'ZodError') + return fail(400, { message: 'Variante inválida.' }); + const info = messageFor(cause); + return fail(info.status, { message: info.message }); + } + }, + snapshot: async (event) => { + const { db, owner } = ownerDatabase(event); + const form = await event.request.formData(); + const episodeId = readFormText(form, 'episodeId'); + const postId = readFormText(form, 'postId'); + if (!episodeId || !postId) return fail(400, { message: 'Episódio ou publicação inválidos.' }); + try { + const context = await loadRetentionContext(db, owner, episodeId); + if (!context) return fail(404, { message: 'Episódio não encontrado.' }); + await saveAnalyticsSnapshot({ + db, + adminDb: createSupabaseAdminClient(), + owner, + durationMs: context.episode.durationMs, + values: { + postId, + capturedAt: utcDate(readFormText(form, 'capturedAt')), + periodStart: utcDate(readFormText(form, 'periodStart')), + periodEnd: utcDate(readFormText(form, 'periodEnd')), + source: 'MANUAL', + note: readFormText(form, 'note'), + supersedesSnapshotId: readFormText(form, 'supersedesSnapshotId') || null, + metrics: { + views: nullableMetric(readFormText(form, 'views')), + likes: nullableMetric(readFormText(form, 'likes')), + comments: nullableMetric(readFormText(form, 'comments')), + shares: nullableMetric(readFormText(form, 'shares')), + saves: nullableMetric(readFormText(form, 'saves')), + followersGained: nullableMetric(readFormText(form, 'followersGained')), + avgWatchMs: nullableMetric(readFormText(form, 'avgWatchMs')), + completionPct: nullableMetric(readFormText(form, 'completionPct'), false), + }, + }, + }); + redirect(303, `/app/retention?episodeId=${episodeId}&saved=snapshot`); + } catch (cause) { + rethrowRedirect(cause); + if (cause instanceof Error && cause.name === 'ZodError') + return fail(400, { message: 'Métricas ou datas inválidas.' }); + const info = messageFor(cause); + return fail(info.status, { message: info.message }); + } + }, + import: async (event) => { + const { db, owner } = ownerDatabase(event); + const form = await event.request.formData(); + const episodeId = readFormText(form, 'episodeId'); + const csv = readFormText(form, 'csv'); + const filename = readFormText(form, 'filename') || 'import.csv'; + if (!episodeId || !csv.trim()) return fail(400, { message: 'Cole um CSV para importar.' }); + try { + const context = await loadRetentionContext(db, owner, episodeId); + if (!context) return fail(404, { message: 'Episódio não encontrado.' }); + const result = await importRetentionCsv({ + db, + adminDb: createSupabaseAdminClient(), + owner, + episodeId, + filename, + csv, + durationMs: context.episode.durationMs, + }); + const detail = result.errors + .slice(0, 2) + .map((entry) => `L${entry.line}: ${entry.message}`) + .join(' | ') + .slice(0, 300); + redirect( + 303, + `/app/retention?episodeId=${episodeId}&imported=${result.imported}&skipped=${result.skipped}&errors=${result.errors.length}${ + detail ? `&detail=${encodeURIComponent(detail)}` : '' + }`, + ); + } catch (cause) { + rethrowRedirect(cause); + const info = messageFor(cause); + return fail(info.status, { message: info.message }); + } + }, + experiment: async (event) => { + const { owner } = ownerDatabase(event); + const form = await event.request.formData(); + const episodeId = readFormText(form, 'episodeId'); + if (!episodeId) return fail(400, { message: 'Episódio inválido.' }); + try { + await saveRetentionExperiment({ + adminDb: createSupabaseAdminClient(), + owner, + values: { + episodeId, + name: readFormText(form, 'name'), + variantAId: readFormText(form, 'variantAId'), + variantBId: readFormText(form, 'variantBId'), + hypothesis: readFormText(form, 'hypothesis'), + }, + }); + redirect(303, `/app/retention?episodeId=${episodeId}&saved=experiment`); + } catch (cause) { + rethrowRedirect(cause); + if (cause instanceof Error && cause.name === 'ZodError') + return fail(400, { message: 'Experimento inválido.' }); + const info = messageFor(cause); + return fail(info.status, { message: info.message }); + } + }, + delete: async (event) => { + const { owner } = ownerDatabase(event); + const form = await event.request.formData(); + const episodeId = readFormText(form, 'episodeId'); + const postId = readFormText(form, 'postId'); + if (!episodeId || !postId) return fail(400, { message: 'Publicação inválida.' }); + try { + await deletePublishedPost({ adminDb: createSupabaseAdminClient(), owner, postId }); + redirect(303, `/app/retention?episodeId=${episodeId}&saved=deleted`); + } catch (cause) { + rethrowRedirect(cause); + const info = messageFor(cause); + return fail(info.status, { message: info.message }); + } + }, +}; diff --git a/src/routes/app/retention/+page.svelte b/src/routes/app/retention/+page.svelte new file mode 100644 index 00000000..c6dcc70c --- /dev/null +++ b/src/routes/app/retention/+page.svelte @@ -0,0 +1,809 @@ + + +Retenção · DIF Studio + + +
+ + +
+ +{#if form?.message}{/if} +{#if data.notice?.mode === 'imported'} +

+ Importação: {data.notice.imported} novos, {data.notice.skipped} duplicados, {data.notice.errors} + erros. + {#if data.notice.detail}
{data.notice.detail}{/if} +

+{:else if data.notice} +

Registro salvo.

+{/if} +{#if data.loadError}{/if} + +{#if data.context} +
+ Exportar CSV + Exportar JSON + Duração do episódio: {durationSeconds.toFixed(0)}s +
+ +
+

Publicações e métricas observadas

+ {#if chartPosts.length} +
+
+
Views por publicação (último snapshot)
+ + + {#each chartPosts as post, index (post.id)} + {@const value = post.latestSnapshot?.metrics.views ?? 0} + {@const width = Math.max(8, Math.round(300 / chartPosts.length) - 6)} + + {post.platform} · {post.label || post.url}: {formatNumber(value)} views + + {/each} + 0 + {formatNumber(maxViews)} + +
+
+
+ Engajamento observado por publicação (%) — apenas taxas calculáveis +
+ {#if engagementPosts.length} + + + {#each engagementPosts as post, index (post.id)} + {@const value = post.latestSnapshot?.computed.engagementRate ?? 0} + {@const width = Math.max(8, Math.round(300 / engagementPosts.length) - 6)} + + {/each} + {formatRate(maxEngagement)} + + {:else} +

Nenhuma taxa calculável; valores ausentes não viram zero.

+ {/if} +
+
+ {/if} + {#if data.context.posts.length} +
+ {#each data.context.posts as post (post.id)} +
+
+ {post.platform} + {post.label || post.url} +
+ {post.url} + publicado em {formatDate(post.publishedAt)} · {post.snapshotCount} snapshot(s) + {#if post.variants.length} +

+ {#each post.variants as variant (variant.id)} + {variant.kind}: {variant.label} + {/each} +

+ {:else} +

Sem variante registrada.

+ {/if} + {#if post.latestSnapshot} + {@const snapshot = post.latestSnapshot} +
+
Views{formatNumber(snapshot.metrics.views)}
+
+ Engajamento{formatRate(snapshot.computed.engagementRate)} +
+
+ Conclusão{formatPercent(snapshot.computed.completionPct)} +
+
+ Watch relativo{formatRate(snapshot.computed.watchTimeRelative)} +
+
+ Interações/1000{snapshot.computed.interactionsPer1000 === null + ? 'INDISPONÍVEL' + : snapshot.computed.interactionsPer1000.toFixed(1)} +
+
+ Followers{formatNumber(snapshot.metrics.followersGained)} +
+
+ + origem {snapshot.source} · {formatDate(snapshot.periodStart)} a {formatDate( + snapshot.periodEnd, + )} · capturado em {formatDate(snapshot.capturedAt)} + + {#if snapshot.note}

{snapshot.note}

{/if} + {#if snapshot.computed.missing.length} +

Ausentes: {snapshot.computed.missing.join(', ')}.

+ {/if} + {#each snapshot.computed.warnings as warning (warning)} + {warningLabel(warning)} + {/each} + {:else} +

Sem snapshot: métricas INDISPONÍVEIS.

+ {/if} + {#if post.snapshots.length} +
+ Histórico de snapshots ({post.snapshotCount}) +
    + {#each post.snapshots.slice(0, 20) as entry (entry.id)} +
  • + v{entry.revision} · {entry.source} · {formatDate( + entry.periodStart, + )}–{formatDate(entry.periodEnd)} · views {formatNumber(entry.metrics.views)} + {#if entry.supersedesSnapshotId}retifica{/if} +
  • + {/each} +
+ {#if post.snapshotCount > 20} +

Mostrando as 20 revisões mais recentes.

+ {/if} +
+ {/if} +
+ + + +
+
+ {/each} +
+ {:else} +

Nenhuma publicação registrada neste episódio.

+ {/if} +
+ +
+

Experimentos A/B observacionais

+
+ + +
+ {#if data.comparisons.length} +
+ {#each data.comparisons as entry (entry.experiment.id)} +
+
+ {entry.experiment.name}{entry.comparison.status} +
+ {#if entry.experiment.hypothesis}{entry.experiment.hypothesis}{/if} +

{entry.comparison.summary}

+ A: {variantLabel(entry.experiment.variantAId)} · views {experimentViews( + entry.experiment, + 'A', + )} · {experimentPinned(entry.experiment, 'A')} + B: {variantLabel(entry.experiment.variantBId)} · views {experimentViews( + entry.experiment, + 'B', + )} · {experimentPinned(entry.experiment, 'B')} + + {metricLabel}: A {formatMetric(entry.comparison.valueA, data.metric)} · B {formatMetric( + entry.comparison.valueB, + data.metric, + )} + + {#each entry.comparison.warnings as warning (warning)} + {warningLabel(warning)} + {/each} +
+ {/each} +
+ {:else} +

+ Nenhum experimento registrado. A/B exige duas variantes e snapshots comparáveis. +

+ {/if} +
+ +
+ + +
+
+ + +
+ +
+
+ +
+
+ Registrar publicação +
+ +
+ + +
+ + + + + +
+
+ +
+ Registrar variante +
+ + +
+ + +
+ + + + +
+
+ +
+ Adicionar snapshot manual +
+ + +
+ + +
+ +
+ + + + + + + + +
+ + +

+ Deixe em branco o que a plataforma não informou. Ausente ≠ zero. Datas são UTC. +

+ +
+
+ +
+ Importar CSV +
+ + + +

+ Datas ISO 8601. Campos vazios viram NULL. Importação repetida do mesmo snapshot é + ignorada. +

+ +
+
+
+ +
+ Definições e limites +
    + {#each data.metrics as metric (metric.id)} +
  • + {metric.label}: {metric.numerator} ÷ {metric.denominator}. +
  • + {/each} + {#each Object.entries(RETENTION_PLATFORM_NOTES) as [platform, note] (platform)} +
  • {platform}: {note}
  • + {/each} +
+

+ Versão das métricas: 1. Amostra baixa abaixo de 1000 views. Ausente é INDISPONÍVEL, nunca + zero. Comparações A/B são descritivas e não estabelecem causalidade. +

+
+{/if} + + diff --git a/supabase/migrations/20261120110000_v2_wo020_retention_lab.sql b/supabase/migrations/20261120110000_v2_wo020_retention_lab.sql new file mode 100644 index 00000000..29672c52 --- /dev/null +++ b/supabase/migrations/20261120110000_v2_wo020_retention_lab.sql @@ -0,0 +1,567 @@ +-- V2 WO-020: private retention lab. Owners register manually published posts, +-- creative variants and aggregate analytics snapshots; nothing is fetched from +-- social platforms and no viewer-level data is stored. + +alter table public.hook_variants + add constraint hook_variants_owner_id_id_key unique (owner_id, id); + +create table public.published_posts ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + episode_id uuid not null, + platform text not null check (platform in ('tiktok', 'reels', 'youtube_shorts', 'other')), + url text not null check (char_length(url) between 8 and 500 and url ~ '^https?://'), + published_at timestamptz not null, + label text not null default '' check (char_length(label) <= 120), + notes text not null default '' check (char_length(notes) <= 1000), + created_at timestamptz not null default now(), + updated_at timestamptz not null default now(), + unique (owner_id, id), + unique (owner_id, episode_id, platform, url), + foreign key (owner_id, episode_id) references public.episodes (owner_id, id) on delete restrict +); + +create table public.published_post_versions ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + post_id uuid not null, + revision_number integer not null check (revision_number between 1 and 100000), + snapshot jsonb not null check (jsonb_typeof(snapshot) = 'object'), + change_note text not null default '' check (char_length(change_note) <= 300), + created_at timestamptz not null default now(), + unique (owner_id, post_id, revision_number), + unique (owner_id, id), + foreign key (owner_id, post_id) references public.published_posts (owner_id, id) on delete restrict +); + +create table public.creative_variants ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + post_id uuid not null, + kind text not null check (kind in ('HOOK', 'COVER', 'CTA', 'BASELINE')), + label text not null check (char_length(btrim(label)) between 1 and 80), + hook_variant_id uuid, + cover_revision_id uuid, + end_card_id uuid, + created_at timestamptz not null default now(), + unique (owner_id, id), + unique (owner_id, post_id, kind, label), + foreign key (owner_id, post_id) references public.published_posts (owner_id, id) on delete restrict, + foreign key (owner_id, hook_variant_id) references public.hook_variants (owner_id, id) on delete restrict, + foreign key (owner_id, cover_revision_id) references public.cover_revisions (owner_id, id) on delete restrict, + foreign key (owner_id, end_card_id) references public.choice_end_cards (owner_id, id) on delete restrict +); + +create table public.retention_imports ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + filename text not null check (char_length(filename) between 1 and 120), + sha256 text not null check (sha256 ~ '^[0-9a-f]{64}$'), + row_count integer not null check (row_count between 0 and 5000), + imported_count integer not null check (imported_count between 0 and 5000), + skipped_count integer not null check (skipped_count between 0 and 5000), + error_count integer not null check (error_count between 0 and 5000), + created_at timestamptz not null default now(), + unique (owner_id, id), + unique (owner_id, sha256) +); + +create table public.analytics_snapshots ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + post_id uuid not null, + revision_number integer not null check (revision_number between 1 and 100000), + supersedes_snapshot_id uuid, + import_id uuid, + captured_at timestamptz not null, + period_start timestamptz not null, + period_end timestamptz not null, + source text not null check (source in ('MANUAL', 'CSV')), + note text not null default '' check (char_length(note) <= 1000), + views bigint check (views >= 0), + likes bigint check (likes >= 0), + comments bigint check (comments >= 0), + shares bigint check (shares >= 0), + saves bigint check (saves >= 0), + followers_gained integer check (followers_gained >= 0), + avg_watch_ms integer check (avg_watch_ms between 0 and 600000), + completion_pct numeric(5, 2) check (completion_pct between 0 and 100), + metric_version integer not null default 1 check (metric_version = 1), + episode_duration_ms integer not null check (episode_duration_ms between 1000 and 600000), + snapshot_hash text not null check (snapshot_hash ~ '^[0-9a-f]{64}$'), + created_at timestamptz not null default now(), + check (period_start < period_end), + check (captured_at >= period_end), + unique (owner_id, post_id, revision_number), + unique (owner_id, post_id, snapshot_hash), + unique (owner_id, id), + foreign key (owner_id, post_id) references public.published_posts (owner_id, id) on delete restrict, + foreign key (owner_id, supersedes_snapshot_id) references public.analytics_snapshots (owner_id, id) + on delete restrict deferrable initially deferred, + foreign key (owner_id, import_id) references public.retention_imports (owner_id, id) on delete restrict +); + +create table public.retention_experiments ( + id uuid primary key default gen_random_uuid(), + owner_id uuid not null, + episode_id uuid not null, + name text not null check (char_length(btrim(name)) between 1 and 80), + variant_a_id uuid not null, + variant_b_id uuid not null, + variant_a_snapshot_id uuid, + variant_b_snapshot_id uuid, + hypothesis text not null default '' check (char_length(hypothesis) <= 500), + status text not null default 'ACTIVE' check (status in ('DRAFT', 'ACTIVE', 'CLOSED')), + created_at timestamptz not null default now(), + updated_at timestamptz not null default now(), + check (variant_a_id <> variant_b_id), + unique (owner_id, id), + unique (owner_id, episode_id, name), + foreign key (owner_id, episode_id) references public.episodes (owner_id, id) on delete restrict, + foreign key (owner_id, variant_a_id) references public.creative_variants (owner_id, id) on delete restrict, + foreign key (owner_id, variant_b_id) references public.creative_variants (owner_id, id) on delete restrict, + foreign key (owner_id, variant_a_snapshot_id) references public.analytics_snapshots (owner_id, id) on delete restrict, + foreign key (owner_id, variant_b_snapshot_id) references public.analytics_snapshots (owner_id, id) on delete restrict +); + +create index published_posts_by_episode on public.published_posts (owner_id, episode_id, published_at desc); +create index analytics_snapshots_by_post on public.analytics_snapshots (owner_id, post_id, period_end desc); + +alter table public.published_posts enable row level security; +alter table public.published_posts force row level security; +alter table public.published_post_versions enable row level security; +alter table public.published_post_versions force row level security; +alter table public.creative_variants enable row level security; +alter table public.creative_variants force row level security; +alter table public.retention_imports enable row level security; +alter table public.retention_imports force row level security; +alter table public.analytics_snapshots enable row level security; +alter table public.analytics_snapshots force row level security; +alter table public.retention_experiments enable row level security; +alter table public.retention_experiments force row level security; + +revoke all on table public.published_posts from public, anon, authenticated; +revoke all on table public.published_post_versions from public, anon, authenticated; +revoke all on table public.creative_variants from public, anon, authenticated; +revoke all on table public.retention_imports from public, anon, authenticated; +revoke all on table public.analytics_snapshots from public, anon, authenticated; +revoke all on table public.retention_experiments from public, anon, authenticated; + +grant select on table public.published_posts to authenticated; +grant select on table public.published_post_versions to authenticated; +grant select on table public.creative_variants to authenticated; +grant select on table public.retention_imports to authenticated; +grant select on table public.analytics_snapshots to authenticated; +grant select on table public.retention_experiments to authenticated; +grant select, insert, update, delete on table public.published_posts to service_role; +grant select, insert, update, delete on table public.published_post_versions to service_role; +grant select, insert, update, delete on table public.creative_variants to service_role; +grant select, insert, update, delete on table public.retention_imports to service_role; +grant select, insert, update, delete on table public.analytics_snapshots to service_role; +grant select, insert, update, delete on table public.retention_experiments to service_role; + +create policy owner_select on public.published_posts for select to authenticated + using (owner_id = (select auth.uid()) and (select auth.jwt() -> 'app_metadata' ->> 'dif_studio_owner') = 'true'); +create policy owner_select on public.published_post_versions for select to authenticated + using (owner_id = (select auth.uid()) and (select auth.jwt() -> 'app_metadata' ->> 'dif_studio_owner') = 'true'); +create policy owner_select on public.creative_variants for select to authenticated + using (owner_id = (select auth.uid()) and (select auth.jwt() -> 'app_metadata' ->> 'dif_studio_owner') = 'true'); +create policy owner_select on public.retention_imports for select to authenticated + using (owner_id = (select auth.uid()) and (select auth.jwt() -> 'app_metadata' ->> 'dif_studio_owner') = 'true'); +create policy owner_select on public.analytics_snapshots for select to authenticated + using (owner_id = (select auth.uid()) and (select auth.jwt() -> 'app_metadata' ->> 'dif_studio_owner') = 'true'); +create policy owner_select on public.retention_experiments for select to authenticated + using (owner_id = (select auth.uid()) and (select auth.jwt() -> 'app_metadata' ->> 'dif_studio_owner') = 'true'); + +create or replace function public.reject_retention_history_mutation() +returns trigger language plpgsql set search_path = pg_catalog, public +as $$ +begin + if current_setting('dif.retention_delete', true) = 'on' and tg_op = 'DELETE' then + return old; + end if; + raise exception 'retention_history_is_immutable' using errcode = '55000'; +end; +$$; + +create trigger published_post_versions_immutable + before update or delete on public.published_post_versions + for each row execute function public.reject_retention_history_mutation(); +create trigger retention_imports_immutable + before update or delete on public.retention_imports + for each row execute function public.reject_retention_history_mutation(); +create trigger analytics_snapshots_immutable + before update or delete on public.analytics_snapshots + for each row execute function public.reject_retention_history_mutation(); + +create or replace function public.save_published_post( + p_owner_id uuid, + p_post_id uuid, + p_episode_id uuid, + p_platform text, + p_url text, + p_published_at timestamptz, + p_label text, + p_notes text, + p_change_note text default '' +) +returns uuid +language plpgsql security definer set search_path = pg_catalog, public +as $$ +declare + v_post public.published_posts; + v_revision integer; +begin + if p_owner_id is null or p_episode_id is null then + raise exception 'owner_auth_required' using errcode = '42501'; + end if; + if p_platform not in ('tiktok', 'reels', 'youtube_shorts', 'other') + or p_url !~ '^https?://' or char_length(p_url) > 500 + or char_length(coalesce(p_label, '')) > 120 + or char_length(coalesce(p_notes, '')) > 1000 then + raise exception 'retention_post_invalid' using errcode = '23514'; + end if; + if not exists (select 1 from public.episodes e where e.owner_id = p_owner_id and e.id = p_episode_id) then + raise exception 'episode_not_found' using errcode = 'P0002'; + end if; + if p_post_id is null then + insert into public.published_posts ( + owner_id, episode_id, platform, url, published_at, label, notes + ) values ( + p_owner_id, p_episode_id, p_platform, btrim(p_url), p_published_at, + btrim(coalesce(p_label, '')), btrim(coalesce(p_notes, '')) + ) + on conflict (owner_id, episode_id, platform, url) do update + set published_at = excluded.published_at, + label = excluded.label, + notes = excluded.notes, + updated_at = now() + returning * into v_post; + else + update public.published_posts + set platform = p_platform, + url = btrim(p_url), + published_at = p_published_at, + label = btrim(coalesce(p_label, '')), + notes = btrim(coalesce(p_notes, '')), + updated_at = now() + where owner_id = p_owner_id and id = p_post_id and episode_id = p_episode_id + returning * into v_post; + if not found then + raise exception 'published_post_not_found' using errcode = 'P0002'; + end if; + end if; + select coalesce(max(v.revision_number), 0) + 1 into v_revision + from public.published_post_versions v + where v.owner_id = p_owner_id and v.post_id = v_post.id; + insert into public.published_post_versions ( + owner_id, post_id, revision_number, snapshot, change_note + ) values ( + p_owner_id, v_post.id, v_revision, jsonb_build_object('post', to_jsonb(v_post)), + btrim(coalesce(p_change_note, '')) + ); + return v_post.id; +end; +$$; + +create or replace function public.save_creative_variant( + p_owner_id uuid, + p_post_id uuid, + p_kind text, + p_label text, + p_hook_variant_id uuid default null, + p_cover_revision_id uuid default null, + p_end_card_id uuid default null +) +returns uuid +language plpgsql security definer set search_path = pg_catalog, public +as $$ +declare + v_post public.published_posts; + v_variant_id uuid; +begin + if p_owner_id is null or p_post_id is null then + raise exception 'owner_auth_required' using errcode = '42501'; + end if; + if p_kind not in ('HOOK', 'COVER', 'CTA', 'BASELINE') + or char_length(btrim(coalesce(p_label, ''))) not between 1 and 80 then + raise exception 'retention_variant_invalid' using errcode = '23514'; + end if; + select * into v_post from public.published_posts + where owner_id = p_owner_id and id = p_post_id; + if not found then + raise exception 'published_post_not_found' using errcode = 'P0002'; + end if; + if p_hook_variant_id is not null and not exists ( + select 1 from public.hook_variants h + where h.owner_id = p_owner_id and h.id = p_hook_variant_id + and h.episode_id = v_post.episode_id and h.status = 'APPLIED' + ) then + raise exception 'retention_hook_variant_invalid' using errcode = '23514'; + end if; + if p_cover_revision_id is not null and not exists ( + select 1 from public.cover_revisions c + where c.owner_id = p_owner_id and c.id = p_cover_revision_id + and c.episode_id = v_post.episode_id and c.status = 'APPROVED' + ) then + raise exception 'retention_cover_invalid' using errcode = '23514'; + end if; + if p_end_card_id is not null and not exists ( + select 1 from public.choice_end_cards c + where c.owner_id = p_owner_id and c.id = p_end_card_id + and c.episode_id = v_post.episode_id and c.status = 'APPROVED' + ) then + raise exception 'retention_end_card_invalid' using errcode = '23514'; + end if; + insert into public.creative_variants ( + owner_id, post_id, kind, label, hook_variant_id, cover_revision_id, end_card_id + ) values ( + p_owner_id, p_post_id, p_kind, btrim(p_label), p_hook_variant_id, + p_cover_revision_id, p_end_card_id + ) returning id into v_variant_id; + return v_variant_id; +end; +$$; + +create or replace function public.save_analytics_snapshot( + p_owner_id uuid, + p_post_id uuid, + p_captured_at timestamptz, + p_period_start timestamptz, + p_period_end timestamptz, + p_source text, + p_note text, + p_views bigint, + p_likes bigint, + p_comments bigint, + p_shares bigint, + p_saves bigint, + p_followers_gained integer, + p_avg_watch_ms integer, + p_completion_pct numeric, + p_episode_duration_ms integer, + p_snapshot_hash text, + p_supersedes_snapshot_id uuid default null, + p_import_id uuid default null +) +returns integer +language plpgsql security definer set search_path = pg_catalog, public +as $$ +declare + v_revision integer; + v_existing integer; +begin + if p_owner_id is null or p_post_id is null then + raise exception 'owner_auth_required' using errcode = '42501'; + end if; + if p_source not in ('MANUAL', 'CSV') or p_snapshot_hash !~ '^[0-9a-f]{64}$' then + raise exception 'retention_snapshot_invalid' using errcode = '23514'; + end if; + if not (p_period_start < p_period_end) or p_captured_at < p_period_end then + raise exception 'retention_period_invalid' using errcode = '23514'; + end if; + if coalesce(p_views, 0) < 0 or coalesce(p_likes, 0) < 0 or coalesce(p_comments, 0) < 0 + or coalesce(p_shares, 0) < 0 or coalesce(p_saves, 0) < 0 + or coalesce(p_followers_gained, 0) < 0 or coalesce(p_avg_watch_ms, 0) < 0 + or coalesce(p_completion_pct, 0) < 0 or coalesce(p_completion_pct, 0) > 100 + or coalesce(p_avg_watch_ms, 0) > coalesce(p_episode_duration_ms, 0) + or coalesce(p_episode_duration_ms, 0) not between 1000 and 600000 then + raise exception 'retention_metric_invalid' using errcode = '23514'; + end if; + if not exists ( + select 1 from public.published_posts p + where p.owner_id = p_owner_id and p.id = p_post_id + ) then + raise exception 'published_post_not_found' using errcode = 'P0002'; + end if; + if p_supersedes_snapshot_id is not null and not exists ( + select 1 from public.analytics_snapshots s + where s.owner_id = p_owner_id and s.id = p_supersedes_snapshot_id and s.post_id = p_post_id + ) then + raise exception 'retention_supersedes_invalid' using errcode = '23514'; + end if; + if p_import_id is not null and not exists ( + select 1 from public.retention_imports i where i.owner_id = p_owner_id and i.id = p_import_id + ) then + raise exception 'retention_import_invalid' using errcode = '23514'; + end if; + perform pg_advisory_xact_lock(hashtextextended(p_post_id::text, 0)); + select s.revision_number into v_existing + from public.analytics_snapshots s + where s.owner_id = p_owner_id and s.post_id = p_post_id and s.snapshot_hash = p_snapshot_hash; + if found then + return v_existing; + end if; + select coalesce(max(s.revision_number), 0) + 1 into v_revision + from public.analytics_snapshots s + where s.owner_id = p_owner_id and s.post_id = p_post_id; + if v_revision > 5000 then + raise exception 'retention_snapshot_quota' using errcode = '23514'; + end if; + insert into public.analytics_snapshots ( + owner_id, post_id, revision_number, supersedes_snapshot_id, import_id, + captured_at, period_start, period_end, source, note, + views, likes, comments, shares, saves, followers_gained, avg_watch_ms, + completion_pct, episode_duration_ms, snapshot_hash + ) values ( + p_owner_id, p_post_id, v_revision, p_supersedes_snapshot_id, p_import_id, + p_captured_at, p_period_start, p_period_end, p_source, btrim(coalesce(p_note, '')), + p_views, p_likes, p_comments, p_shares, p_saves, p_followers_gained, p_avg_watch_ms, + p_completion_pct, p_episode_duration_ms, p_snapshot_hash + ); + return v_revision; +end; +$$; + +create or replace function public.save_retention_import( + p_owner_id uuid, + p_filename text, + p_sha256 text, + p_row_count integer, + p_imported_count integer, + p_skipped_count integer, + p_error_count integer +) +returns uuid +language plpgsql security definer set search_path = pg_catalog, public +as $$ +declare + v_id uuid; +begin + if p_owner_id is null then + raise exception 'owner_auth_required' using errcode = '42501'; + end if; + if char_length(btrim(coalesce(p_filename, ''))) not between 1 and 120 + or p_sha256 !~ '^[0-9a-f]{64}$' then + raise exception 'retention_import_invalid' using errcode = '23514'; + end if; + insert into public.retention_imports ( + owner_id, filename, sha256, row_count, imported_count, skipped_count, error_count + ) values ( + p_owner_id, btrim(p_filename), p_sha256, p_row_count, p_imported_count, p_skipped_count, p_error_count + ) + on conflict (owner_id, sha256) do nothing + returning id into v_id; + if v_id is null then + select i.id into v_id from public.retention_imports i + where i.owner_id = p_owner_id and i.sha256 = p_sha256; + end if; + return v_id; +end; +$$; + +create or replace function public.save_retention_experiment( + p_owner_id uuid, + p_episode_id uuid, + p_name text, + p_variant_a_id uuid, + p_variant_b_id uuid, + p_hypothesis text default '' +) +returns uuid +language plpgsql security definer set search_path = pg_catalog, public +as $$ +declare + v_id uuid; + v_post_a uuid; + v_post_b uuid; + v_snap_a uuid; + v_snap_b uuid; +begin + if p_owner_id is null or p_episode_id is null then + raise exception 'owner_auth_required' using errcode = '42501'; + end if; + if p_variant_a_id = p_variant_b_id + or char_length(btrim(coalesce(p_name, ''))) not between 1 and 80 then + raise exception 'retention_experiment_invalid' using errcode = '23514'; + end if; + select va.post_id into v_post_a + from public.creative_variants va + join public.published_posts pa on pa.owner_id = va.owner_id and pa.id = va.post_id + where va.owner_id = p_owner_id and va.id = p_variant_a_id and pa.episode_id = p_episode_id; + select vb.post_id into v_post_b + from public.creative_variants vb + join public.published_posts pb on pb.owner_id = vb.owner_id and pb.id = vb.post_id + where vb.owner_id = p_owner_id and vb.id = p_variant_b_id and pb.episode_id = p_episode_id; + if v_post_a is null or v_post_b is null then + raise exception 'retention_experiment_variant_invalid' using errcode = '23514'; + end if; + if v_post_a = v_post_b then + raise exception 'retention_experiment_same_post' using errcode = '23514'; + end if; + select s.id into v_snap_a + from public.analytics_snapshots s + where s.owner_id = p_owner_id and s.post_id = v_post_a + order by s.revision_number desc limit 1; + select s.id into v_snap_b + from public.analytics_snapshots s + where s.owner_id = p_owner_id and s.post_id = v_post_b + order by s.revision_number desc limit 1; + insert into public.retention_experiments ( + owner_id, episode_id, name, variant_a_id, variant_b_id, + variant_a_snapshot_id, variant_b_snapshot_id, hypothesis + ) values ( + p_owner_id, p_episode_id, btrim(p_name), p_variant_a_id, p_variant_b_id, + v_snap_a, v_snap_b, btrim(coalesce(p_hypothesis, '')) + ) + on conflict (owner_id, episode_id, name) do update + set variant_a_id = excluded.variant_a_id, + variant_b_id = excluded.variant_b_id, + variant_a_snapshot_id = excluded.variant_a_snapshot_id, + variant_b_snapshot_id = excluded.variant_b_snapshot_id, + hypothesis = excluded.hypothesis, + updated_at = now() + returning id into v_id; + return v_id; +end; +$$; + +create or replace function public.delete_published_post( + p_owner_id uuid, + p_post_id uuid +) +returns boolean +language plpgsql security definer set search_path = pg_catalog, public +as $$ +begin + if p_owner_id is null or p_post_id is null then + raise exception 'owner_auth_required' using errcode = '42501'; + end if; + if not exists ( + select 1 from public.published_posts p where p.owner_id = p_owner_id and p.id = p_post_id + ) then + raise exception 'published_post_not_found' using errcode = 'P0002'; + end if; + perform set_config('dif.retention_delete', 'on', true); + delete from public.retention_experiments e + where e.owner_id = p_owner_id + and (e.variant_a_id in (select id from public.creative_variants where owner_id = p_owner_id and post_id = p_post_id) + or e.variant_b_id in (select id from public.creative_variants where owner_id = p_owner_id and post_id = p_post_id)); + delete from public.analytics_snapshots s where s.owner_id = p_owner_id and s.post_id = p_post_id; + delete from public.creative_variants v where v.owner_id = p_owner_id and v.post_id = p_post_id; + delete from public.published_post_versions v where v.owner_id = p_owner_id and v.post_id = p_post_id; + delete from public.published_posts p where p.owner_id = p_owner_id and p.id = p_post_id; + perform set_config('dif.retention_delete', 'off', true); + return true; +end; +$$; + +revoke all on function public.save_published_post(uuid, uuid, uuid, text, text, timestamptz, text, text, text) from public, anon, authenticated; +revoke all on function public.save_creative_variant(uuid, uuid, text, text, uuid, uuid, uuid) from public, anon, authenticated; +revoke all on function public.save_analytics_snapshot(uuid, uuid, timestamptz, timestamptz, timestamptz, text, text, bigint, bigint, bigint, bigint, bigint, integer, integer, numeric, integer, text, uuid, uuid) from public, anon, authenticated; +revoke all on function public.save_retention_import(uuid, text, text, integer, integer, integer, integer) from public, anon, authenticated; +revoke all on function public.save_retention_experiment(uuid, uuid, text, uuid, uuid, text) from public, anon, authenticated; +revoke all on function public.delete_published_post(uuid, uuid) from public, anon, authenticated; +revoke all on function public.reject_retention_history_mutation() from public, anon, authenticated; + +grant execute on function public.save_published_post(uuid, uuid, uuid, text, text, timestamptz, text, text, text) to service_role; +grant execute on function public.save_creative_variant(uuid, uuid, text, text, uuid, uuid, uuid) to service_role; +grant execute on function public.save_analytics_snapshot(uuid, uuid, timestamptz, timestamptz, timestamptz, text, text, bigint, bigint, bigint, bigint, bigint, integer, integer, numeric, integer, text, uuid, uuid) to service_role; +grant execute on function public.save_retention_import(uuid, text, text, integer, integer, integer, integer) to service_role; +grant execute on function public.save_retention_experiment(uuid, uuid, text, uuid, uuid, text) to service_role; +grant execute on function public.delete_published_post(uuid, uuid) to service_role; + +comment on table public.analytics_snapshots is + 'Owner-only aggregate snapshots supplied manually or by CSV; never fetched from platforms.'; +comment on function public.save_analytics_snapshot(uuid, uuid, timestamptz, timestamptz, timestamptz, text, text, bigint, bigint, bigint, bigint, bigint, integer, integer, numeric, integer, text, uuid, uuid) is + 'Server-only idempotent snapshot append with explicit NULL metrics and a supersedes chain.'; diff --git a/supabase/tests/rls_and_integrity.sql b/supabase/tests/rls_and_integrity.sql index 8a6d756b..ae3c2cda 100644 --- a/supabase/tests/rls_and_integrity.sql +++ b/supabase/tests/rls_and_integrity.sql @@ -2,7 +2,7 @@ -- The test uses synthetic JWT subjects and rolls back every inserted row. create extension if not exists pgtap with schema extensions; begin; -select plan(210); +select plan(229); do $$ declare @@ -16,7 +16,9 @@ declare 'voice_direction_plans', 'narration_takes', 'caption_tracks', 'audio_assets', 'render_quality_reports', 'hook_variants', 'character_identity_profiles', 'character_identity_profile_versions', - 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards' + 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards', + 'published_posts', 'published_post_versions', 'creative_variants', + 'retention_imports', 'analytics_snapshots', 'retention_experiments' ]; v_rls boolean; v_policy_count integer; @@ -64,7 +66,9 @@ begin 'voice_direction_plans', 'narration_takes', 'caption_tracks', 'audio_assets', 'render_quality_reports', 'hook_variants', 'character_identity_profiles', 'character_identity_profile_versions', - 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards' + 'visual_continuity_reports', 'cover_revisions', 'choice_end_cards', + 'published_posts', 'published_post_versions', 'creative_variants', + 'retention_imports', 'analytics_snapshots', 'retention_experiments' ) then if v_policy_count <> 1 then raise exception 'edit plan policies must be read-only'; end if; if has_table_privilege('authenticated', format('public.%I', v_table), 'INSERT') @@ -2539,6 +2543,170 @@ select throws_ok( ); reset role; +insert into public.episodes (id, owner_id, season_id, episode_number, title, duration_ms) +values ( + 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', '11111111-1111-4111-8111-111111111111', + 'f6f6f6f6-f6f6-46f6-86f6-f6f6f6f6f6f6', 9, 'Retention lab episode', 90000 +); + +set local role service_role; +select lives_ok( + $$select public.save_published_post( + '11111111-1111-4111-8111-111111111111', null, + 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', 'tiktok', + 'https://www.tiktok.com/@rls/video/1', '2026-11-01T00:00:00Z', + 'Post RLS', 'Fixture', 'Criação' + );$$, + 'service role stores a published post' +); +select throws_ok( + $$select public.save_published_post( + '11111111-1111-4111-8111-111111111111', null, + 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', 'tiktok', + 'not-a-url', '2026-11-01T00:00:00Z', 'X', '', '' + );$$, + '23514', 'retention_post_invalid', + 'invalid publication URLs are rejected' +); +select lives_ok( + $$select public.save_creative_variant( + '11111111-1111-4111-8111-111111111111', + (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/1'), + 'HOOK', 'A', null, null, null + );$$, + 'service role stores variant A' +); +select public.save_published_post( + '11111111-1111-4111-8111-111111111111', null, + 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', 'tiktok', + 'https://www.tiktok.com/@rls/video/2', '2026-11-01T00:00:00Z', + 'Post RLS B', 'Fixture B', 'Criação B' +); +select lives_ok( + $$select public.save_creative_variant( + '11111111-1111-4111-8111-111111111111', + (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/2'), + 'BASELINE', 'B', null, null, null + );$$, + 'service role stores variant B' +); +select lives_ok( + $$select public.save_analytics_snapshot( + '11111111-1111-4111-8111-111111111111', + (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/1'), + '2026-11-09T00:00:00Z', '2026-11-01T00:00:00Z', '2026-11-08T00:00:00Z', + 'MANUAL', 'Primeira coleta', 10000, 400, 50, 30, 20, 10, 60000, 50, 90000, + repeat('1', 64), null, null + );$$, + 'service role stores the first analytics snapshot' +); +select is( + public.save_analytics_snapshot( + '11111111-1111-4111-8111-111111111111', + (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/1'), + '2026-11-09T00:00:00Z', '2026-11-01T00:00:00Z', '2026-11-08T00:00:00Z', + 'MANUAL', 'Primeira coleta', 10000, 400, 50, 30, 20, 10, 60000, 50, 90000, + repeat('1', 64), null, null + ), 1, 'repeated snapshot hashes are idempotent' +); +select is( + public.save_analytics_snapshot( + '11111111-1111-4111-8111-111111111111', + (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/1'), + '2026-11-10T00:00:00Z', '2026-11-01T00:00:00Z', '2026-11-08T00:00:00Z', + 'MANUAL', 'Retificação', 12000, 500, 60, 40, 25, 12, 62000, 51, 90000, + repeat('2', 64), + (select id from public.analytics_snapshots + where post_id = (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/1') + and revision_number = 1), + null + ), 2, 'a retification appends a new revision and supersedes the old one' +); +set local role authenticated; +select set_config('request.jwt.claims', '{"sub":"11111111-1111-4111-8111-111111111111","app_metadata":{"dif_studio_owner":true}}', true); +select is( + (select count(*) from public.published_posts + where episode_id = 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7'), + 2::bigint, 'owner can read published posts' +); +select throws_ok( + $$insert into public.published_posts ( + owner_id, episode_id, platform, url, published_at + ) values ( + '11111111-1111-4111-8111-111111111111', 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', + 'tiktok', 'https://www.tiktok.com/@rls/video/3', now() + );$$, + '42501', 'permission denied for table published_posts', + 'owner cannot insert published posts directly' +); +select set_config('request.jwt.claims', '{"sub":"22222222-2222-4222-8222-222222222222","app_metadata":{"dif_studio_owner":true}}', true); +select is( + (select count(*) from public.published_posts + where episode_id = 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7'), + 0::bigint, 'second owner cannot read published posts' +); +reset role; +set local role service_role; +select throws_ok( + $$update public.analytics_snapshots set views = 1 where revision_number = 1;$$, + '55000', 'retention_history_is_immutable', + 'analytics snapshots are immutable' +); +select lives_ok( + $$select public.save_retention_experiment( + '11111111-1111-4111-8111-111111111111', + 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', + 'Hook A/B', + (select id from public.creative_variants where label = 'A' and kind = 'HOOK'), + (select id from public.creative_variants where label = 'B' and kind = 'BASELINE'), + 'Associação observada.' + );$$, + 'service role stores a retention experiment' +); +select throws_ok( + $$select public.save_retention_experiment( + '11111111-1111-4111-8111-111111111111', + 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7', 'Same variant', + (select id from public.creative_variants where label = 'A' and kind = 'HOOK'), + (select id from public.creative_variants where label = 'A' and kind = 'HOOK'), '' + );$$, + '23514', 'retention_experiment_invalid', + 'experiments require two distinct variants' +); +select is( + public.delete_published_post( + '11111111-1111-4111-8111-111111111111', + (select id from public.published_posts where url = 'https://www.tiktok.com/@rls/video/1') + ), true, 'service role deletes the publication' +); +select is( + (select count(*) from public.published_posts + where url = 'https://www.tiktok.com/@rls/video/1'), + 0::bigint, 'post deletion removes the publication' +); +select is( + (select count(*) from public.published_post_versions + where owner_id = '11111111-1111-4111-8111-111111111111' and post_id not in (select id from public.published_posts)), + 0::bigint, 'post deletion removes the version history' +); +select is( + (select count(*) from public.creative_variants + where owner_id = '11111111-1111-4111-8111-111111111111' and post_id not in (select id from public.published_posts)), + 0::bigint, 'post deletion removes the variants' +); +select is( + (select count(*) from public.analytics_snapshots + where owner_id = '11111111-1111-4111-8111-111111111111' and post_id not in (select id from public.published_posts)), + 0::bigint, 'post deletion removes the snapshots' +); +select is( + (select count(*) from public.retention_experiments + where owner_id = '11111111-1111-4111-8111-111111111111' + and episode_id = 'b7b7b7b7-b7b7-47b7-87b7-b7b7b7b7b7b7'), + 0::bigint, 'post deletion removes linked experiments' +); +reset role; + select lives_ok( $$insert into public.hook_variants ( owner_id, episode_id, plan_id, plan_version, variant_key, label, objective,