Spec · Dataset Demo Ejecutable

1Objetivo

Producir un paquete ejecutable que cualquiera con Docker + Git pueda levantar en 5 minutos y ver FARO Connect funcionando con datos realistas de una empresa demo durante 6 meses, generando KPIs, detectando las 30 tensiones MVP, asignando acciones y mostrando el FARO Score evolucionar.

Por qué importa esta tarea

• Cierra el gap "documental → ejecutable" identificado por la matriz de estado de implementación (95 activos en 📄 vs 0 en 🚀).
• Vende confianza por demostración, no por discurso. Un inversor no va a leer 50 anexos — sí va a quedar impactado por ver el sistema corriendo en su laptop en 5 minutos.
• Es la base de toda demo futura. Cada vez que vayas a una reunión con Horacio, un CTO o un inversor, levantás el demo y mostrás. Sin esto, la conversación queda en abstracciones.
• Habilita testing real. Una vez que el dataset corre, podés iterar fórmulas KPI, reglas, umbrales, etc. midiendo impacto en tensiones detectadas.

2Criterios de aceptación

El entregable se acepta si y solo si cumple los 8 criterios objetivos siguientes:

3Arquitectura local

Stack mínimo necesario. Todo corre en Docker — el dev no tiene que instalar PostgreSQL nativo ni Node global.

docker-compose.yml (componentes)

Flujo de ./demo-up.sh

#!/bin/bash
set -e
echo "🚀 FARO Demo · levantando entorno..."
docker compose up -d postgres
echo "⏳ Esperando PostgreSQL..."
until docker compose exec -T postgres pg_isready -U faro; do sleep 1; done
echo "📦 Aplicando DDL + migrations..."
docker compose run --rm seed npm run migrate
echo "🌱 Cargando 6 meses de datos demo..."
docker compose run --rm seed npm run seed
echo "🧮 Calculando KPIs..."
docker compose run --rm compute npm run kpis
echo "⚡ Evaluando reglas y detectando tensiones..."
docker compose run --rm compute npm run rules
echo "🧭 Calculando FARO Score..."
docker compose run --rm compute npm run score
echo ""
echo "✅ Demo lista. Acceder a:"
echo "   pgAdmin:  http://localhost:5050"
echo "   Reporte:  ./reports/demo-report.html"
echo ""
docker compose run --rm compute npm run report

4Estructura del repo

Repo Git aparte (sugerido: faro-connect-demo). Estructura propuesta:

5Diseño de datos sintéticos

Empresa demo: distribuidora de materiales de construcción "Premium SA". 3 sucursales (Mendoza, San Juan, Córdoba). ~65 empleados. Facturación USD 2.4M/año. Esto es coherente con el resto del pack — no cambiar.

Patrones intencionales (para disparar tensiones)

Las 30 tensiones MVP totales deben dispararse — la mayoría con menor severidad. Lo importante: el dataset NO es aleatorio, es intencional. El dev debe trabajar con el equipo FARO para refinar los patrones hasta que las 30 disparen.

Generación de los CSVs

El dev puede usar Python (pandas + faker) o Node (faker.js). El criterio:

• Reproducibilidad: seed fijo en el generador → mismo output siempre.
• Volumen razonable: ~12.000 ventas (no 100.000, no 100).
• Coherencia interna: una venta tiene FK válido a cliente + producto + vendedor + sucursal. No inventar IDs huérfanos.
• Estacionalidad: ventas más altas en marzo/abril (inicio año fiscal construcción).
• Plantillas oficiales como contrato: respetar las columnas de las 15 plantillas oficiales MVP.

6SQL seed + DDL

El DDL de partida ya existe en el pack: FARO-Connect-MVP-completo.sql (25 tablas + 21 funciones + extensiones).

Qué tiene que producir el dev

1. Migrations versionadas: dividir el DDL monolítico en 001_*.sql, 002_*.sql, etc. usando Flyway, Sqitch o equivalente.
2. 60 funciones fn_kpi_NNN() ejecutables: partir de las fórmulas en A5.2 Fórmulas KPI. Cada función retorna NUMERIC dado (company_id UUID, period DATE).
3. 30 reglas evaluables MVP: las 30 marcadas como mvp: true en Biblioteca Tensiones. Pueden ser tabla rules con DSL JSON + función evaluadora SQL, o JSON externo + motor Node.
4. seed.sql: SQL que: (a) crea la empresa demo + sucursales + usuarios, (b) inserta los maestros desde CSVs vía COPY, (c) inserta los facts vía COPY, (d) tira un ANALYZE al final.

El dev NO debe re-inventar el modelo de datos — el DDL del pack ya está completo y aprobado. Su trabajo es operacionalizarlo (migrations, seed, funciones SQL ejecutables).

7Validation script

./demo-check.sh debe correr automáticamente las assertions y producir un reporte HTML claro.

kpi_expected.json (estructura)

{
  "KPI-001": { "period": "2026-05-01", "value": 198450.00, "tolerance": 0.01 },
  "KPI-002": { "period": "2026-05-01", "value": 0.224, "tolerance": 0.001 },
  "KPI-008": { "period": "2026-05-01", "value": 51.3, "tolerance": 0.5 },
  ...
}

tensiones_expected.json (estructura)

{
  "TNS-001": {
    "must_trigger": true,
    "first_trigger_period": "2026-03-01",
    "severity_min": 3,
    "affects": ["sucursal:mendoza", "area:comercial"]
  },
  "TNS-027": {
    "must_trigger": true,
    "first_trigger_period": "2026-04-15",
    "severity_min": 4,
    "affects": ["producto:SUP_PREMIUM_001"]
  },
  ...
}

check.ts (algoritmo)

1. Cargar kpi_expected.json + tensiones_expected.json + score_expected.json
2. Querear BD para cada KPI esperado → comparar contra value ± tolerance
3. Querear tensiones disparadas → confirmar que todas las must_trigger:true están + severidad correcta
4. Calcular Score actual → comparar contra esperado
5. Generar check-report.html con tabla de pass/fail + summary
6. Exit code 0 si todo pasa, 1 si algo falla

8Storyboard de presentación

El archivo docs/STORYBOARD.md es el guion de 7-10 minutos para mostrarle a Horacio, un CTO o un inversor. No es un README técnico — es teatro guiado.

Estructura propuesta del storyboard

9Estimación de esfuerzo

Para un dev junior-senior con TS + PostgreSQL + Docker:

Total: 25 horas (sumar 30-40% para imprevistos → presupuestar 30-35h con dev junior, 20-25h con dev senior).

10Entrega + criterios de revisión

Qué se entrega

• Repo Git público o privado con todo el código
• Tag v1.0.0
• README claro con git clone + ./demo-up.sh
• Demo grabada (Loom o equivalente · 5 min) corriendo end-to-end · prueba que funciona en SU máquina
• Reporte final de ./demo-check.sh con 8/8 criterios verde

Criterios de revisión por Tomás

1. Reproducibilidad: Tomás clona en una máquina limpia (Mac o Linux) y corre ./demo-up.sh. Debe funcionar sin pasos extra.
2. 5 minutos: cronometrar de clone a primera tensión visible. Si pasa de 8 min, hay que optimizar.
3. Las 30 tensiones MVP efectivamente disparan. Sin ese mínimo, no se acepta.
4. El storyboard se puede leer y ejecutar: Tomás hace dry-run con el guion y debe poder presentarlo sin saber el código.

Quién puede ejecutar esta tarea

• Dev full-stack TS/SQL: ideal. 1 persona, 25-35hs.
• Tomás + dev SQL: posible. Tomás guía decisiones de datos sintéticos (qué patrones meter), dev hace el código.
• Agencia técnica: viable si entiende el contexto. Pedir cotización por todo el ticket cerrado, no por hora.