---
type: ARQ
asset_id: ARQ-EL-PlatformOps-API-v01
version: v01
status: Activo · para implementación de Alex/Jesús
owner: Victor Heredia
sherpa_owner: Jay
ratificador: Victor Heredia
fecha_creacion: 2026-07-03
fecha_ultima_actualizacion: 2026-07-03
intellibank: IB-EL-EmpowerLabs
subbank: PB-EL-Plataforma
proyecto: Platform Intelligence (TP-EL-PlatformIntelligence-MPX-RClub-v01 · Módulo 3 · Fase 2)
audiencia: Alex (backend) · Jesús (frontend) — implementadores del endpoint
consumidor: BRD-EL-PlatformOps-Dashboard-v01.html (campos marcados API)
tags: [ARQ, api, metricas, plataforma, ops, spec, platform-intelligence, M3]
---

# ARQ · Platform Ops API — Spec del endpoint de métricas
## Para Alex y Jesús · lo que el dashboard necesita para pasar de mock a vivo

> **Tripleta WORX** — Owner: Victor Heredia · Sherpa: Jay · Ratificador: Victor Heredia
> **Contexto:** el dashboard `BRD-EL-PlatformOps-Dashboard-v01.html` está operando en Fase 1 (datos manuales). Esta spec define la Fase 2: un endpoint único de métricas que el dashboard consume vía fetch JS. Cada campo del payload mapea 1:1 a un slot del dashboard.

---

## §1 · Endpoint canónico

```
GET /api/v1/platform/metrics
Host: masterplaybooks.com (sirve ambas plataformas — ver §3 parámetro channel)
Headers:
  Authorization: Bearer {ADMIN_TOKEN}
  Accept: application/json
```

- **Auth:** token de administrador de larga vida (rotable), scope de solo-lectura de métricas. NO usar la sesión de usuario del navegador.
- **CORS:** permitir origin `file://` no es viable — ver §5 opciones de consumo.
- **Rate limit sugerido:** 60 req/hora por token (el dashboard refresca manualmente o cada 5 min).
- **Versionado:** prefijo `/v1/` — cambios breaking van a `/v2/`, nunca mutan `/v1/`.

## §2 · Response payload (contrato)

```json
{
  "timestamp": "2026-07-03T18:00:00Z",
  "channel": "all",
  "activity": {
    "active_users_now": 42,
    "dau": 387,
    "wau": 1250,
    "mau": 3900,
    "new_signups_24h": 12,
    "sessions_24h": { "mpx": 210, "rclub": 95 }
  },
  "content": {
    "top_playbooks_mpx": [
      { "id": "pb_123", "title": "Fuerza, velocidad y rendimiento", "views_24h": 40 }
    ],
    "top_modules_rclub": [
      { "module": "foros", "visits_24h": 60 }
    ],
    "sherpa_queries_24h": 130,
    "artifacts_generated_24h": 8
  },
  "conversion": {
    "free_to_member_24h": 2,
    "failed_payments_24h": 1,
    "cancellations_period": 0
  },
  "performance": {
    "page_load_ms": { "p50": 800, "p95": 2300, "p99": 4100 },
    "sherpa_first_response_ms": 2100,
    "error_rate_5xx_1h": 0.002,
    "uptime_pct": { "h24": 99.8, "d7": 99.5, "d30": 99.2 },
    "bookfactory_queue": 3
  }
}
```

**Reglas del contrato:**

1. Campo sin dato disponible → `null`, nunca omitir la llave (el dashboard distingue "sin dato" de "campo eliminado").
2. Todas las duraciones en **ms**, todos los porcentajes como número (99.8, no "99.8%"), timestamps **ISO-8601 UTC**.
3. `top_playbooks_mpx` y `top_modules_rclub`: máximo 5 elementos, ordenados desc.
4. Números redondeados a 1 decimal máximo (lección del bug MPX-STAT-04: "18.181818181818183%").

## §3 · Parámetros query

| Parámetro | Valores | Default | Uso |
|---|---|---|---|
| `channel` | `all` · `mpx` · `rclub` | `all` | Filtrar métricas por plataforma. **Debe respetar el aislamiento multi-tenant** — mismo principio que MT-01 |
| `window` | `1h` · `24h` · `7d` · `30d` | `24h` | Ventana para métricas de actividad |

## §4 · Prioridad de implementación por campo

No hace falta el payload completo para arrancar. Orden sugerido (valor/esfuerzo):

| Fase | Campos | Por qué primero |
|---|---|---|
| 2a (mínimo útil) | `active_users_now`, `dau`, `new_signups_24h`, `sessions_24h` | Ya existen en Estadísticas de MPX — es exponer lo que la vista `/stats` ya calcula |
| 2b | `sherpa_queries_24h`, `bookfactory_queue`, `top_playbooks_mpx` | La cuota 0/999 de membresía implica que las consultas ya se cuentan |
| 2c | `performance.*` | Requiere instrumentación (timing middleware o APM externo — depende del RFI D4) |
| 2d | `conversion.*`, `uptime_pct` | Conversión requiere eventos de pago; uptime puede venir de Uptime Robot (gratuito) si D4 confirma que no hay nada activo |

## §5 · Consumo desde el dashboard (nota para Jesús/Jay)

El dashboard es un HTML local (vault), así que hay 3 opciones de conexión — decidir en la implementación:

1. **Proxy simple:** servir el dashboard desde la propia plataforma (`/dev/ops-dashboard`) — mismo origin, sin CORS. **Recomendada.**
2. **CORS abierto al token:** exponer el endpoint con `Access-Control-Allow-Origin: *` (es solo-lectura + Bearer) y que el HTML local haga fetch — el token se pega una vez y se guarda en localStorage.
3. **Snapshot job:** un cron escribe `metrics.json` al vault vía la app IntelliBanks y el dashboard lo lee — cero backend nuevo, latencia de minutos.

Una vez decidido, Jay conecta el fetch en `BRD-EL-PlatformOps-Dashboard-v01` (los slots ya están mapeados por `data-k`).

## §6 · Seguridad y gobernanza de datos

- El endpoint expone **solo métricas agregadas** — nunca emails, nombres ni actividad individual de usuarios (regla del TP §5).
- Token con scope `metrics:read` exclusivamente; rotación trimestral.
- Log de acceso al endpoint (quién consultó, cuándo) para auditoría.
- El parámetro `channel` debe validar contra el aislamiento multi-tenant: las métricas de un canal no deben computarse con datos de otro (mismo bug raíz que MT-01 — si el aislamiento de datos no está resuelto, las métricas por canal saldrán contaminadas).

## §7 · Criterios de aceptación

- [ ] `GET /api/v1/platform/metrics` responde 200 con el contrato §2 y auth Bearer válida; 401 sin token.
- [ ] Campos sin dato → `null` (no omitidos, no `0` falso).
- [ ] `channel=rclub` devuelve métricas SOLO de RClub (verificable contra el bug MT-01).
- [ ] El dashboard muestra datos reales en los slots API sin editar el HTML (solo configurar URL + token).
- [ ] Sin datos personales en ningún campo del payload.

## §8 · NEXTs

- [NEXT][Alex] Ratificar contrato §2 o proponer ajustes (campos que ya existen vs. los que requieren instrumentación) + responder RFI D4 (¿hay monitoreo externo activo?).
- [NEXT][Alex] Implementar Fase 2a (4 campos de actividad) — decidir opción de consumo §5.
- [NEXT][Jesús] Confirmar de dónde sale `sherpa_first_response_ms` (¿se loguea hoy la latencia del Sherpa?).
- [NEXT][Jay] Al existir el endpoint, conectar fetch en el dashboard (slots `data-k` ya mapeados).

## CHANGELOG

| Versión | Fecha | Cambio |
|---|---|---|
| v01 | 2026-07-03 | Spec inicial del endpoint de métricas (M3 Fase 2): contrato JSON, parámetros, prioridad de implementación en 4 sub-fases, opciones de consumo, seguridad y criterios de aceptación. |

---

*ARQ-EL-PlatformOps-API-v01 · EmpowerLabs · 2026-07-03 · Owner: Victor Heredia · Sherpa: Jay*