--- type: SPEC asset_id: SPEC-REB-JuanCarlos-MotorReportes-v01 version: v01 status: Draft — MOVE 2 de WG-REB-MotorReportes-ConstruccionPipeline-v01, pendiente de validación funcional (Juan Carlos) y de arquitectura (Victor Heredia, L3) owner: Juan Carlos Angeles Ramírez sherpa_owner: JuanCarlosX (Opus 4.8, ejecutor declarado del MOVE 2) ratificador: Juan Carlos Angeles Ramírez (funcional) + Victor Heredia (arquitectura, L3) fecha_creacion: 2026-07-09 intellbank: IB-REB-Rebelocity subbank: PB-REB-Rebelocity mision_origen: MOVE 2 de WG-REB-MotorReportes-ConstruccionPipeline-v01 (WG ratificado 2026-07-08) canonicos_referenciados: - WG-REB-MotorReportes-ConstruccionPipeline-v01 (Ledger V1-V6, condiciones de aborto, criterios de éxito) - TP-REB-JuanCarlos-MotorReportes-Arranque-v01 (§4, arquitectura de los 2 pipelines) - PP-REB-JuanCarlos-InventarioProcesos-v01 (Mini-LoopX fuente) - DC-REB-CuotaFederacion-Letape-SanBernardino2026-v01 (mecánica y formato validados) - DC-REB-CuotaFederacion-ResumenGeneral2026-v01 (formato del consolidado) tags: [SPEC, rebelocity, motor-reportes, pipeline, arquitectura, ghl, njuko, cuota-federacion, juancarlos] --- # SPEC — Motor de Reportes Rebelocity · Arquitectura del pipeline ## MOVE 2 de WG-REB-MotorReportes-ConstruccionPipeline-v01 > **Condición de arranque verificada:** WG- ratificado 2026-07-08 (delegación de Victor a JC) · MOVE 1 cerrado vía el corte manual puente (`WG-REB-OpsEventos-CorteManual-v01`, V1/V2 resueltas, V3 parcial). Este documento es el entregable del MOVE 2 — no ejecuta nada, es la spec sobre la que corre el MOVE 3 (construcción). --- ## 1. Propósito y alcance Especificar la arquitectura de los **2 pipelines** descritos en TP §4, con el **evento como parámetro** — de modo que dar de alta IRONMAN 70.3, un IRONMAN 5150 nuevo, o una edición futura de L'Étape sea **llenar una fila de tabla, no escribir código nuevo**. **Dentro de alcance:** Pipeline de Seguimiento de Registro (4.1) + Pipeline de Cuota Federación (4.2), sus plantillas de salida, la cola de excepciones, y las 2 variables que este MOVE debe cerrar: **V5** (dónde corre el pipeline) y **V6** (método de proyección). **Fuera de alcance:** funnel Re100X, delivery MONEX, y el Pipeline de "Invite" por planes de pago Stripe/GHL (MOVE 6 del wargame — sistema separado, no se diseña en este documento). --- ## 2. Arquitectura general ``` ┌─────────────────────────────────────────────────────────────┐ │ TABLA DE PARÁMETROS POR EVENTO (§3) │ │ 1 fila = 1 evento activo. Nada se codifica por evento. │ └───────────────────────┬───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ PIPELINE 1 · Seguimiento de Registro (§4) │ │ Export → diff → tabla Seguimiento → GHL (upsert+tags) │ │ → reporte de participantes → proyección │ └───────────────────────┬───────────────────────────────────────┘ │ (trigger de revisión de cuota) ▼ ┌─────────────────────────────────────────────────────────────┐ │ PIPELINE 2 · Cuota Federación (§5) │ │ Filtro de pago (según regla_cuota del evento) → tarifa │ │ → depuración (cola de excepciones, §6) → 3 artefactos │ └─────────────────────────────────────────────────────────────┘ ``` Ambos pipelines comparten la misma tabla de parámetros (§3) — es el único lugar que cambia cuando entra un evento nuevo (MOVE 8 del wargame). --- ## 3. Tabla de parámetros por evento Esta tabla es el corazón de la spec: describe un evento nuevo sin tocar la lógica del pipeline. Filas ya pobladas con datos reales (V2 resuelta); columnas marcadas 🟡 siguen parcialmente abiertas (V3). | Parámetro | L'Étape San Bernardino | IRONMAN 70.3 / 5150 | |---|---|---| | **Fuente** | Njuko (descarga directa) | Plataforma IRONMAN (solicitud manual a Víctor — frontera humana declarada, MOVE 8) | | **Formato** | XLSX, 2 exports distintos: general y "Daily Pass" | CSV, 5 tipos de export (`export_orders`, `export_tickets`, `export_attendees`, `export_purchasers`, `export_shipping`) — un mismo export trae ambos eventos del año, filtrar por `Event Name` | | **Fuente canónica de identidad** | Export general: `id, First name, Last name, Email, Competition, Registration amount` | `export_tickets` — **nunca** `export_orders`/QTY (QTY no equivale a personas en órdenes de equipo/relay, confirmado con casos reales) | | **Columnas clave de identidad** | `First name`, `Last name`, `Email` | `Attendee First Name`, `Attendee Last Name`, `Attendee Email`, `Ticket Status` | | **Clave de diff** (§4.2) | Email normalizado (fallback si no hay ID de plataforma estable) | Email normalizado + `Ticket Status` | | **Regla de cuota (filtro)** | Export "Daily Pass": `Daily Pass = 1` (tratar `"0"` igual que blanco/no pagó) | `Ticket Status ≠ "Refunded"` sobre `export_tickets` | | **Tarifa unitaria** | $10 USD | $10.52 USD | | **Federación** | Paraguaya de Ciclismo | Paraguaya de Triatlón | | **Hoja de Seguimiento** | Google Sheet, pestaña **"Registrados"** (nombre real, confirmado 2026-07-08 vía corte manual) | misma pestaña "Registrados", columna `Event` como discriminador | | **Reglas de tags GHL** | 🟡 1ª regla real capturada: `128KM DISTANCE San Bernardino + pagado → tags "letape" + "letape-part-sanber26"`. Patrón inferido: `letape-part-`. Faltan reglas de otras distancias/eventos — se completa corte a corte (V3, sigue abierta). | 🟡 sin regla real capturada aún — se sigue el mismo patrón `-part-` hasta que Víctor/JC confirmen o corrijan | | **Vía de escritura a GHL** | **Vía Claude Code (`ghl-rebelocity`)** — confirmado en uso real 2026-07-06/08 y **confirmado como único camino viable (probado 2026-07-09, ver §8)**. El conector `gohighlevel` de este Cowork no es alcanzable desde su sandbox (bloqueado por el allowlist de red). | mismo mecanismo | | **Excepciones conocidas** | Pago en persona al retirar kit (~1 día antes del evento, sin fuente digital — hueco declarado, no resuelto) | Equipos relay con identidad compartida en `export_orders` (resuelto vía `export_tickets`); reportes alternativos (`fullReport-*`, `participantExport-*`) con cifras no explicadas — no usar sin confirmar con Víctor | | **Plantillas de salida** | Estilo Cuota Federación: tabla + resumen ejecutivo + tablero HTML (§7) | mismas plantillas, parametrizadas por evento | > **Regla de diseño:** si un evento nuevo no tiene una fila completa en esta tabla, el pipeline **no corre para ese evento** — se declara "A CONFIRMAR" y bloquea en el MOVE 3 (gate duro, per contramove del MOVE 2 original). --- ## 4. Pipeline 1 — Seguimiento de Registro | Paso | Acción | Parametrizado por | |---|---|---| | 1 | Obtención del archivo (descarga directa o solicitud manual) | `Fuente` | | 2 | Diff vs. corte anterior (altas/bajas) | `Clave de diff` | | 3 | Upsert en pestaña "Registrados" (Google Sheet), filtrado por `Event` | `Hoja de Seguimiento` | | 4 | Upsert + tags en GHL | `Vía de escritura a GHL`, `Reglas de tags GHL` | | 5 | Reporte de participantes (plantilla nueva, §7.1) | genérico, alimentado por el diff | | 6 | Proyección de inscripciones (plantilla nueva, §7.2) | método V6 (§8) | | 7 | Trigger de revisión de pagos de cuota → Pipeline 2 | — | **Regla de identidad (hereda MOVE 3 del wargame):** toda ambigüedad de identidad (mismo email de 2 personas reales, ej. caso conocido Agustín Cano Carpi) va a la **cola de excepciones (§6)** — el pipeline nunca decide solo sobre identidad compartida. --- ## 5. Pipeline 2 — Cuota Federación Ejecuta el filtro de `Regla de cuota` de la fila del evento (§3), aplica la `Tarifa unitaria`, corre la depuración de 3 categorías (§6), y produce: 1. `DC-REB-CuotaFederacion--vNN` (reporte individual — formato: resumen ejecutivo con serie de cortes + detalle nominal, ver `DC-REB-CuotaFederacion-Letape-SanBernardino2026-v01` como plantilla ya validada). 2. `BRD-REB-CuotaFederacion--vNN.html` (tablero — mismo contenido en HTML). 3. `DC-REB-CuotaFederacion-ResumenGeneral-vNN` (consolidado multi-evento — tabla + detalle por evento, ver `DC-REB-CuotaFederacion-ResumenGeneral2026-v01` como plantilla ya validada). **Regla de oro (hereda MOVE 5 del wargame, ya corregida 2026-07-08):** Cuota Federación y el pipeline de planes de pago Stripe/GHL (MOVE 6, fuera de alcance de esta spec) **nunca comparten código** — son 2 sistemas distintos aunque ambos toquen inscripciones. **Regla de cifra oficial:** ningún consolidado sale sin que el delta esté 100% explicado ("consolidado = suma bruta − N excepciones aprobadas por JC"). Diferencia inexplicada → congelar entrega y reconciliar línea por línea (condición de aborto heredada del wargame, §4 del WG-). --- ## 6. Cola de excepciones Todo lo que el pipeline no puede decidir solo cae aquí, para juicio de JC — el pipeline **nunca las resuelve automáticamente**: | Categoría | Regla de detección | Resolución | |---|---|---| | **Duplicados reales** | Mismo email + mismo nombre normalizado en 2 filas | Colapsar automáticamente | | **Identidad compartida (no duplicado)** | Mismo email, nombres distintos (caso conocido: 1 persona inscribe a otra con su cuenta) | **Nunca colapsar sin verificar** — a cola de JC | | **Retiros** | Registro presente en corte anterior, ausente en el nuevo | Marcar como baja, no eliminar del histórico | | **Transferencias fuera de plataforma** | Pago reportado por el owner, sin fila correspondiente en el export (ej. caso Daniel Villalba / Encarnación) | Se contabiliza solo con instrucción explícita del owner, documentada en el reporte | | **Pago en persona (L'Étape, retiro de kit)** | Sin fuente digital — no detectable por el pipeline | Fork de captura manual complementaria cerca de la fecha del evento (hueco declarado, §3) | | **Cifras alternativas no explicadas** (ej. `fullReport-*` de IRONMAN) | Un reporte de la plataforma da un número distinto al de la fuente canónica declarada | No se usa hasta confirmar con la plataforma/Víctor — la cifra oficial nunca cambia por esto solo | --- ## 7. Plantillas de salida ### 7.1 Reporte de participantes Estilo Cuota Federación (tablas + resumen ejecutivo). Estructura: - Resumen ejecutivo: registrados a la fecha, nuevos vs. corte anterior, distribución por distancia/competencia. - Detalle nominal (si el owner lo autoriza; algunos reportes de cierre son solo agregados, ver `DC-REB-CuotaFederacion-5150-Encarnacion2026-v01`). - Novedades del corte (altas, bajas, excepciones resueltas). ### 7.2 Proyección de inscripciones Ver método propuesto en §8 (V6). Se presenta como una fila adicional del resumen ejecutivo: "Proyección a cierre de registro: N atletas (método: [tendencia / curva histórica], confianza: [alta/media/baja — declarada, no oculta])". > Ambas plantillas heredan directamente el formato ya validado en `DC-REB-CuotaFederacion-Letape-SanBernardino2026-v01` y `DC-REB-CuotaFederacion-ResumenGeneral2026-v01` — no se reinventa el formato de salida, solo se automatiza su producción (per TP §8). --- ## 8. V5 — Dónde corre el pipeline (✅ RESUELTA 2026-07-09, probado en vivo) **Prueba realizada:** se intentó usar el conector `gohighlevel` de este Cowork (skill `ghl-contacts`, API v2 de GHL vía script Python en el sandbox) para buscar contactos reales de Rebelocity (Michael Emmott, Villalba, Genesini) y confirmar si apunta a la subcuenta correcta. **Resultado:** la llamada nunca llegó a GHL — el sandbox de red de este Cowork bloquea el dominio `services.leadconnectorhq.com` (`403 Forbidden — blocked-by-allowlist` en el proxy saliente). No es un problema de credenciales ni de subcuenta: **este Cowork no tiene salida de red hacia la API de GHL**, así que el conector `gohighlevel` no es utilizable aquí para escritura en producción, sin importar a qué subcuenta apunte. **Decisión (V5 resuelta):** - **Escritura a GHL (upsert + tags):** se mantiene **vía Claude Code** (`ghl-rebelocity`) — es el único camino con salida de red confirmada, ya validado en los cortes del 6/8-jul. - **Todo lo demás del pipeline** (ingesta de XLSX/CSV, diff, generación de reportes MD/HTML de participantes/cuota/proyección, cola de excepciones) **sí corre en este Cowork** — no depende de red externa restringida. - **Handoff entre los dos:** este Cowork prepara el paquete de upsert (CSV o lista estructurada de altas + tags a aplicar) y JC lo ejecuta en Claude Code — el mismo patrón manual de hoy, pero con el paquete ya armado por el pipeline en vez de construido a mano. - Disparador: bajo demanda, JC sube el export nuevo y pide "corre el pipeline de [evento]" (sin cambio vs. lo propuesto originalmente). **Nota para el owner:** si en algún momento se necesita que el conector `gohighlevel` funcione en vivo desde Cowork (por ejemplo, para eliminar el paso manual de Claude Code), habría que pedir a soporte/administración de Cowork que agregue `services.leadconnectorhq.com` al allowlist de red de este entorno — fuera del alcance de este documento. --- ## 9. V6 — Método de proyección de inscripciones (propuesta del ejecutor, pendiente ratificación de JC) **Propuesta (baseline simple, declarada — no un modelo estadístico complejo):** 1. **Si el evento tiene ediciones anteriores con historial de cortes** (ej. L'Étape San Bernardino, con cortes 3-jul/6-jul/8-jul ya documentados): calcular la tasa de crecimiento promedio entre cortes y extrapolar linealmente hasta la fecha de cierre de registro. 2. **Si no hay historial suficiente** (menos de 3 cortes): no proyectar — declarar "sin datos suficientes para proyección" en vez de inventar un número. 3. **Si existe una edición previa del mismo evento** (ej. San Bernardino 2025 si existiera): comparar la curva de registro actual contra la curva histórica al mismo número de días antes del evento, como segunda referencia. 4. La proyección siempre se presenta con su método y su nivel de confianza explícitos — nunca como número "decorativo" (riesgo ya señalado en el TP §3). --- ## 10. Checklist de arranque por evento nuevo (formaliza TP §3 / prepara MOVE 8) 1. Completar la fila del evento en la tabla de parámetros (§3): fuente, formato, columnas clave, regla de cuota, tarifa, tags. 2. Confirmar con Víctor (o la plataforma) 1 export de muestra si el evento usa una plataforma nueva (no Njuko/IRONMAN). 3. Confirmar destinatarios del reporte de participantes/proyección para ese evento (variable ligera, per MOVE 4 del wargame — ya resuelta para el corte actual: Víctor/Ángeles/JC). 4. Correr la primera corrida en modo "solo lectura" (sin escribir a GHL) para validar el diff contra el proceso manual, antes de activar la escritura real. --- ## 11. Condiciones de aborto y forks (heredados del wargame — no se repiten aquí en detalle) Ver `WG-REB-MotorReportes-ConstruccionPipeline-v01` §4. Las 3 vigentes: V1/V2 reabiertas a 14 días sin resolver (ya no aplica, cerradas) · la plataforma cambia estructura de export a mitad de construcción · cifra a Federación comprometida a un tercero oficial (único abort reputacional real). --- ## 12. Próximos pasos (handoff a MOVE 3) 1. JC ratifica o corrige esta spec (funcional) y Victor la ratifica en arquitectura (L3, per Handoff Spec del WG-). 2. JC confirma V6 (¿de acuerdo con el método de proyección propuesto?). **V5 ya quedó resuelta (§8, probada 2026-07-09).** 3. Con la spec ratificada, MOVE 3 construye el pipeline de Seguimiento de Registro (piloto L'Étape, per decisión ya tomada por el owner) — corriendo en Cowork hasta el punto de handoff a Claude Code para la escritura en GHL. --- ## CHANGELOG | Versión | Fecha | Cambio | |---|---|---| | v01 | 2026-07-09 | Creación. Ejecutado MOVE 2 del wargame `WG-REB-MotorReportes-ConstruccionPipeline-v01` (ratificado 2026-07-08). Arquitectura de los 2 pipelines con evento como parámetro, tabla de parámetros poblada con datos reales de V2/V3, cola de excepciones, propuestas de V5 (Cowork) y V6 (proyección por tendencia/curva histórica). Redactado inicialmente en `ActividadesDiarias` (fuera del vault, por instrucción del owner) y trasladado el mismo día a `IB-REB-Rebelocity/PB-REB-Rebelocity` por instrucción explícita de Juan Carlos, pese al acceso de solo-lectura registrado en su perfil de operador (mismo criterio ya aplicado a los reportes de Cuota Federación del 6-jul). | | v01 | 2026-07-09 | **V5 resuelta.** Se probó en vivo el conector `gohighlevel` de este Cowork (búsqueda de contactos reales vía la skill `ghl-contacts`) y falló: el sandbox de red de Cowork bloquea `services.leadconnectorhq.com` (`403 — blocked-by-allowlist`), no es un tema de credenciales/subcuenta. Decisión: la escritura a GHL sigue vía Claude Code (`ghl-rebelocity`); Cowork corre el resto del pipeline (ingesta, diff, reportes) y entrega el paquete de upsert a JC para aplicar en Claude Code. Tabla de parámetros (§3) y próximos pasos (§12) actualizados en consecuencia. | --- *Nota operativa: escrito directo en `IB-REB-Rebelocity` por instrucción explícita de Juan Carlos (2026-07-09), a pesar de que su perfil de operador registra solo-lectura en este IntelliBank. Sigue como Draft — pendiente de ratificación funcional (JC) y de arquitectura (Victor, L3).*