ANALYTICS — Sistema integral de producto, adquisición, campañas y conversión

[nicoechaniz]

Problema

Hoy Harmonic Beacon no tiene una vista canónica y confiable del recorrido completo: llegada al Home, entrada a Account, Listen o Live, creación y verificación de cuenta, escucha, participación en eventos, membresía, pago, recurrencia y retorno. Los datos existen fragmentados entre aplicaciones, bases operativas y proveedores; la duración de sesiones Live además no es todavía una métrica confiable cuando falta el cierre de presencia.

Outcome

Construir un sistema integral de analítica de producto, adquisición, eventos y comercio que permita responder con datos actuales:

• cuántas personas llegan, desde dónde y mediante qué campaña;
• qué hacen en Home, Account, Listen y Live;
• cuántas crean y verifican cuenta;
• cuántas escuchan, cuánto tiempo y con qué recurrencia;
• cuántas entran a cada evento, cuánto permanecen y dónde abandonan;
• cuántas membresías reales, internas y de prueba existen;
• conversión, ingreso recurrente, cancelación, retención y cohortes;
• qué campañas están configuradas, activas y realmente entregando;
• qué embudos y superficies requieren decisiones de producto.

Arquitectura acordada

1. Captura first-party de comportamiento web mediante Umami self-hosted o equivalente aprobado, desplegado bajo control de Harmonic Beacon.
2. Eventos server-side canónicos para cuenta, correo verificado, membresía, pago, escucha y asistencia.
3. Mart analítico en PostgreSQL con dimensiones y hechos versionados, deduplicación, backfills y controles de calidad.
4. Dashboard interno en Metabase o una superficie Admin equivalente, con acceso por rol.
5. Ingestores read-only para plataformas de campañas, comenzando por Meta Marketing API.
6. Los datos de navegador sirven para comportamiento; los estados operativos y comerciales del servidor son la autoridad de verdad.

Métricas mínimas

• visitantes, sesiones, páginas, referrer, landing, UTM, identificadores de clic publicitario, dispositivo, navegador, país/región cuando sea legal;
• funnel Home → Account → verificación → Listen/Live → reproducción/evento → membresía → pago confirmado;
• usuarios anónimos, cuentas, cuentas verificadas, usuarios activos, oyentes y horas de escucha;
• eventos: visitas, asistentes únicos, ingreso, salida, permanencia, reconexión y retorno;
• membresías por estado, proveedor, entorno y clasificación real/interna/prueba;
• MRR, altas, cancelaciones, churn y paid-through, sin inferir ingresos desde clics o return URLs;
• campañas: estado configurado, effective status, entrega real, inversión, impresiones, alcance, clics y conversiones atribuidas;
• frescura de cada fuente, fallas de ingesta y discrepancias entre navegador, backend y proveedor.

Reglas

• Se puede conservar información detallada útil para alcance y producto, con acceso controlado, trazabilidad, seguridad y cumplimiento legal aplicable.
• Tokens, secretos, credenciales, URLs firmadas y contenido audiovisual/chat no pertenecen al dataset analítico.
• Identidad personal, identificadores técnicos y métricas agregadas se separan para permitir análisis sin ampliar innecesariamente el acceso.
• Datos internos y pruebas deben poder excluirse del negocio real mediante una clasificación explícita y auditable.
• La medición no puede alterar audio, sesiones, eventos, cuotas, membresías ni pagos.
• El Meta Pixel queda expresamente fuera de alcance: no modificar su código, presencia, consentimiento ni configuración dejados por Sai y Mariano.
• La integración con Meta de esta epic es read-only mediante Marketing API y no depende del Pixel.

Criterios de cierre de la epic

• Todas las superficies productivas emiten el contrato mínimo con deduplicación y continuidad cross-domain.
• Existe un dashboard interno con funnels, cohortes, campañas, Listener, Live, cuentas y comercio.
• Los números comerciales concilian con las autoridades canónicas.
• La permanencia en eventos deja de depender de filas stale o cierres ausentes.
• Meta muestra campañas activas y realmente entregando con última sincronización visible.
• Hay pruebas de esquema, integración, navegador, backfill, zona horaria, duplicados y fallas parciales.
• Backups, restore, retención, control de acceso, observabilidad y rollback están documentados y probados.
• LISTENER-PROGRESSION — Track live and lifetime Beacon listening time #308 se reutiliza como base de medición de escucha, sin crear un segundo cronómetro de navegador.

Fuera de alcance

• Modificar o activar/desactivar el Meta Pixel.
• Usar una plataforma publicitaria como autoridad de cuentas, membresías, pagos o escucha.
• Guardar contenido de audio, video o chat para analítica.
• Realizar cambios funcionales al player, LiveKit o checkout dentro de esta epic.

[nicoechaniz]

Estado productivo de la epic al 2026-08-29:

Completadas y cerradas: #475, #476, #477, #478, #480 y #481. PRs principales #484, #485, #488, #489 y #490 mergeados; Home en AlterMundi/harmonicbeacon.github.io#82. CI final completamente verde, incluida matriz Chromium/Android, Firefox y WebKit/iPhone.

Producción:

• Collector + worker canónicos 9fc2e35, saludables, cero reinicios.
• 92 cuentas, 12 intervalos Listener, 27 Live, 32 revisiones de membresía, 6 hechos históricos; cero dead letters.
• Dashboard real: 85 cuentas, 23 attendees históricos, cero pagos/subscribers/revenue real.
• Alertmanager sin alertas y todas las gauges pmp_listener_paid_jobs_failed_recent=0; el loop del checkout PayPal abandonado quedó corregido en SairaAsua/proyecciones-mito#108.
• Backups/restore analytics y Live verificados; timers fail-closed activos; root con 101 GB libres.

La epic queda abierta sólo por #479 (token System User + ad account ID de Meta) y #482 (identidad privada age para probar restore PMP). La captura visual también espera que la extensión Kimi WebBridge vuelva a conectarse; la API firmada y el control de acceso ya fueron probados.

[nicoechaniz]

Cierre de todo el trabajo autónomo de la epic (2026-08-29):

• PR feat(analytics): close observability and governance gaps #491 mergeado a main; PR release: analytics completion and governance #492 promovido a release; deploy productivo exacto 20745f305d1905cc2a99c482d90f4ca83a06b1f6 verde: https://github.com/AlterMundi/harmonic-beacon-webapp/actions/runs/33246007497
• Home PR fix(analytics): honor opt-out across Beacon subdomains harmonicbeacon.com#83 mergeado, CI/Pages verde y opt-out cross-domain visible en producción.
• Analytics backend productivo 351477475c9c30bb2085c5dc112cc5f57bc82ab1, migración 011 aplicada; collector/worker/PostgreSQL saludables.
• API firmada del dashboard responde 200 con 6 quality checks, 0 errores, historial de storage y todas las fuentes operativas ok; Meta queda explícitamente disabled.
• Pre-migration backup hb-analytics-20260829T090801Z.dump.age: checksum y restore real de 18 tablas aprobados. Monitor posterior: root 47%, disco de datos 13%, daily growth 0, cero dead letters y cero alertas.
• Smokes posteriores: Home 200, Account 200, Listen conserva su handoff 307, Live 200, readiness DB/Account ok; /ops/analytics sin sesión redirige a staff login. Audio boundary y matrices Chromium/Android, Firefox y WebKit/iPhone pasaron tanto en PR como en el release exacto; comercio también pasó.
• Se preservaron imágenes actuales y rollback inmediato. Se retiraron únicamente dos releases de seis días atrás, un candidato analítico sin uso y builder cache no referenciada; root volvió a 101 GB libres.
• Meta Pixel y DNSExit permanecieron intactos.

No queda trabajo técnico seguro pendiente dentro del acceso actual. La epic permanece abierta por dos pruebas que requieren material externo: (1) #479 necesita META_MARKETING_ACCESS_TOKEN de System User con ads_read y META_MARKETING_AD_ACCOUNT_ID para sincronizar y conciliar Ads Manager real; (2) #482 necesita la identidad privada age de PMP, o que su custodio ejecute el restore, para demostrar la restauración criptográfica de ese backup. Todo lo demás está desplegado y demostrado.

[nicoechaniz]

Reanudación y auditoría productiva del 2026-09-03, después de las operaciones del 2 de septiembre:

• Se auditó el estado real antes de modificar: Home, Account, Listen, Live, Postgres, LiveKit y analytics saludables; cero alertas activas. No hubo un deploy de producto por las operaciones del día anterior.
• Se cerró feat(analytics): allow every staff role to view dashboard #498 sin mergear: otorgar analytics automáticamente a todo Staff violaba el contrato aprobado de ADMIN o grants analíticos explícitos. Los grants VIEWER puntuales existentes se conservaron; EXPORTER sigue separado.
• PR fix(analytics): restore release gates #499 corrigió dos gates que habían envejecido desde el deploy original: advisories transitivos de producción (fast-uri y mysql2) y fixtures PostgreSQL con timestamps fijos que empezaban a contaminar los chequeos reales de clock-skew/orphans. Los tests ahora limpian sus fixtures sin debilitar ningún quality check.
• CI de fix(analytics): restore release gates #499 completamente verde: analytics, frozen audio paths, lint/build, 1110 tests y E2E. El release exacto 4e4294b9e33c4b879f07ea5b163f24b2250666cf fue desplegado con E2E previo, rollback inmutable, migraciones aditivas y verificaciones posteriores: https://github.com/AlterMundi/harmonic-beacon-webapp/actions/runs/33711950735
• Producción posterior al rollout: /api/health y readiness ok, SHA público exacto, DB y Account ok; app, commerce reconciler y tapestry saludables. Home 200, Account 200, Listen conserva el handoff 307, Live 200 y /ops/analytics exige autenticación.
• Analytics actual: 258 eventos raw, 102 account facts, 39 intervalos Listener, 41 Live, 36 snapshots de membresía y 6 payment facts históricos; cero dead letters. Las seis pruebas de calidad están ok; todas las fuentes operativas están ok; Meta sigue aislado como disabled / credentials_missing.
• La presencia Live fue revalidada: heartbeat 20 s, grace 45 s, cierre explícito al salir/cerrar evento y límite analítico en last_heartbeat + 45s ante crash/pérdida de red. Las filas operativas viejas de la sala test no inflan la permanencia.
• Backups: checksums actuales de hb-analytics-20260902T220122Z.dump.age y pmp-myth-backup-20260902T233236Z.tar.zst.age correctos. El restore real de analytics del primero restauró 19 tablas a una DB temporal y la eliminó luego. Timers/monitor fail-closed activos; /mnt/beacon-data sigue siendo /dev/sdb ext4 con 81 GB libres. Root saludable con 85 GB libres durante la retención del nuevo build.
• Meta Pixel y DNSExit permanecieron intactos.

La epic sigue abierta sólo por la misma evidencia externa imposible de fabricar desde infraestructura: #479 necesita el token System User ads_read y ad account ID reales; #482 necesita la identidad privada age de PMP o un restore ejecutado por su custodio. Todo el trabajo técnico seguro disponible quedó nuevamente verde y probado en producción.

[nicoechaniz]

Production completion audit follow-up (2026-09-03): authenticated browser review found the dashboard's calendar contract was ending on tomorrow and could exclude/misclassify the selected final day outside UTC. PR #500 fixed it and is merged/deployed at exact release 207318aeb50fc8de8aed75810e92d13f2f5ffde6.

Evidence:

• dates are now inclusive calendar days in a selectable IANA timezone and translated to exact half-open instants;
• previous comparison has equal inclusive length and no overlap;
• 23-hour and 25-hour DST days are covered, including a real PostgreSQL boundary test;
• invalid, partial, reversed, impossible, >2-year and invalid-zone selections fail before mart access;
• retained UTC daily buckets are documented explicitly rather than presented as arbitrary-timezone unique-person facts;
• PR gates: analytics, full tests, lint/build, frozen audio and 14m17s cross-browser E2E all green;
• release deploy run 33716216564 completed green; app, collector and worker all run the exact release;
• authenticated production smoke showed 2026-08-05 through 2026-09-03 in America/Cordoba, then successfully applied America/New_York and returned to Cordoba.

The private screenshot remains off the public repository; SHA-256 cb7761b9646144df556557466be185b6a2e2c67f908c398c85a0caa72f624860. All six source-independent quality checks are ok, all configured operational sources are ok, Meta remains intentionally disabled/credentials_missing, and open dead letters are zero.

[nicoechaniz]

Final status after resuming the goal and auditing the runtime left by CompAII:

• ANALYTICS-01 — Contrato de eventos, identidad y atribución cross-domain #475, ANALYTICS-02 — Instrumentación first-party en Home, Account, Listen y Live #476, ANALYTICS-03 — Pipeline, mart analítico, backfills y calidad de datos #477, ANALYTICS-04 — Dashboard ejecutivo, funnels, cohortes y exploración #478, ANALYTICS-06 — Uso de Listener, Live y eventos con duración confiable #480, ANALYTICS-07 — Métricas canónicas de cuentas, membresías, pagos y revenue #481 and now ANALYTICS-08 — Acceso, cumplimiento legal, retención y operación #482 are closed with production evidence.
• The previously missing PMP restore proof is complete: current encrypted backup restored 36 tables, 10 projection sessions and files into an isolated target; cleanup left zero temporary DBs/directories.
• PR fix(analytics): honor inclusive zoned date ranges #500 and deploy run 33716216564 are green at exact SHA 207318a; all product/analytics containers are healthy, six quality checks are ok, five configured operational sources are ok, zero open dead letters and zero active Alertmanager alerts.
• The private test room created by CompAII remains LIVE / is_test=true / public_access=false; it was not mutated by the analytics rollout. CompAII had not changed the release branch before fix(analytics): honor inclusive zoned date ranges #500.
• Meta Pixel and DNSExit were not touched.

Only #479 remains open. The connector is fully deployed and fixture-tested, but production has no ads-read token/account ID. The only other Meta token on Mona is WhatsApp-scoped, lacks ads_read, and receives 403 from /me/adaccounts; it was deliberately not reused. The epic can close immediately after an authorized System User ads_read token plus the intended act_... ID are supplied and real Ads Manager reconciliation passes.