# FARO-DOC-002 · Runbook de Implementación Piloto **Código:** FARO-DOC-002 **Nombre:** Runbook de Implementación Piloto FARO Connect **Versión:** v1.0 **Estado:** Documento operativo oficial **Prioridad:** P1 · Implementación inicial / piloto controlado **Uso:** Cliente piloto · socio técnico · equipo de implementación · PM · data engineer · backend · dirección **Duración sugerida del piloto:** 30 a 60 días **Conecta con:** * FARO-DOC-001 · Script Workshop Discovery * FARO-PL-016 · Inventario de Fuentes de Datos * FARO-SQL-001 · Migraciones Base MVP * FARO-SQL-002 · Multiempresa, roles y RLS * FARO-CFG-001 · Reglas MVP YAML * FARO-DEMO-001 · Dataset Demo Integral * FARO-TPL-002 · Reporte Semanal Ejecutivo --- # 1. Objetivo del runbook Este runbook define el procedimiento operativo para implementar un piloto de FARO Connect en una empresa real o demo controlada. Su objetivo es que el equipo FARO pueda pasar de: ```text Workshop Discovery → Inventario de fuentes → Muestras de datos → Validación técnica → Carga RAW → Staging → Normalización → KPIs → Señales → Tensiones → Acciones → Responsables → Evidencia → Score → Reporte ejecutivo ``` sin improvisar, sin depender de memoria oral y sin convertir el piloto en una “aventura artesanal”. En criollo ejecutivo: este documento evita que el piloto arranque con entusiasmo y termine con veinte Excels, tres reuniones, cero trazabilidad y todos diciendo “lo vemos la semana que viene”. --- # 2. Principio rector Un piloto FARO no busca construir todo el producto. Busca demostrar, con datos reales o semirreales, que FARO puede convertir información dispersa en dirección ejecutiva accionable. La validación mínima es: ```text Dato entra → dato se conserva → dato se limpia → dato se mide → KPI se calcula → señal se detecta → tensión se genera → acción se asigna → responsable actúa → evidencia se carga → score cambia → dirección recibe reporte ``` Si esa cadena no ocurre, no hay piloto. Hay presentación. --- # 3. Alcance del piloto ## 3.1 Alcance recomendado MVP Para el primer piloto, FARO debe enfocarse en los módulos de mayor valor ejecutivo y menor complejidad técnica. | Módulo | Incluir en piloto | Motivo | | ------------------------------- | ----------------: | ---------------------------------------------- | | Empresas / sucursales / áreas | Sí | Base organizativa | | Usuarios / roles / responsables | Sí | Necesario para acciones | | Productos | Sí | Necesario para ventas, margen y stock | | Clientes | Sí | Necesario para ventas y cobranza | | Ventas | Sí | Fuente primaria de desempeño | | Margen | Sí | Clave para detectar crecimiento no rentable | | Descuentos | Sí | Tensión comercial recurrente | | Stock | Sí | Impacta venta, capital inmovilizado y quiebres | | Cobranza | Sí | Conecta venta con caja | | Acciones | Sí | Diferencia FARO de un dashboard | | Evidencia | Sí | Cierre real, no relato | | FARO Score | Sí | Síntesis ejecutiva | | Reporte semanal | Sí | Entregable directivo | | IA explicativa controlada | Opcional | Solo si hay datos confiables | | Simulación avanzada | No | Requiere histórico validado | | Peer comparison | No | Requiere base comparativa | | Recalibración automática | No | Requiere aprendizaje posterior | | Integración total ERP/API | No obligatorio | Primero validar flujo mínimo | ## 3.2 Objetivo mínimo demostrable El piloto debe demostrar al menos 5 tensiones ejecutivas. Ejemplo para empresa comercial / insumos / distribución: | Tensión | Datos necesarios | Acción esperada | | -------------------------------- | ----------------------------------- | ---------------------------------------- | | Crecimiento no rentable | Ventas, margen, descuentos | Revisar política comercial | | Venta sin caja | Facturación, vencimientos, pagos | Priorizar cobranza | | Stock crítico en productos clave | Stock, rotación, ventas | Reponer o reasignar stock | | Stock inmovilizado | Stock, rotación, antigüedad | Liquidar / promocionar / bloquear compra | | Descuento excesivo por vendedor | Ventas, vendedor, margen, descuento | Revisar autorización / comisión | --- # 4. Participantes y responsabilidades ## 4.1 Roles FARO | Rol | Responsabilidad | | ------------------------ | ------------------------------------------------------------------- | | Sponsor FARO | Define alcance, cuida posicionamiento y toma decisiones comerciales | | Líder de implementación | Coordina el piloto, agenda, entregables y seguimiento | | Analista de negocio | Traduce dolores en KPIs, tensiones y acciones | | Data analyst | Revisa archivos, campos, calidad y mapeos | | Data engineer | Diseña carga, RAW, staging y normalización | | Backend developer | Implementa APIs, reglas, motor y persistencia | | Frontend developer | Implementa bandejas, vistas y reporte visual | | QA / tester | Valida KPIs, reglas, datos esperados y regresiones | | Responsable de seguridad | Revisa accesos, roles, datos sensibles y auditoría | | Dirección FARO | Aprueba salida ejecutiva y mensajes al cliente | ## 4.2 Roles cliente | Rol | Responsabilidad | | ----------------------------------- | ----------------------------------------------------- | | Sponsor interno | Autoriza piloto, prioriza y destraba | | Responsable de sistemas | Entrega accesos, exportaciones o muestras | | Responsable administración/finanzas | Valida cobranza, facturación, bancos y caja | | Responsable comercial | Valida ventas, descuentos, clientes y vendedores | | Responsable stock/compras | Valida stock, productos, proveedores y reposición | | Usuarios responsables | Reciben acciones y prueban flujo operativo | | Dirección cliente | Evalúa reporte, score, tensiones y utilidad ejecutiva | --- # 5. Condiciones mínimas para iniciar No se debe iniciar un piloto si no se cumplen estas condiciones mínimas. ## 5.1 Condiciones comerciales | Condición | Requerida | | -------------------------------------- | ----------: | | Sponsor interno identificado | Sí | | Alcance acordado | Sí | | NDA o acuerdo de confidencialidad | Recomendado | | Expectativa clara de piloto | Sí | | Aprobación para usar muestras de datos | Sí | | Reunión de seguimiento semanal | Sí | ## 5.2 Condiciones técnicas | Condición | Requerida | | ---------------------------------------------- | --------: | | Inventario de fuentes iniciado | Sí | | Al menos 2 fuentes disponibles | Sí | | Exportación de ventas disponible | Sí | | Exportación de productos o maestro equivalente | Sí | | Identificador de fecha | Sí | | Identificador de documento o transacción | Sí | | Responsable técnico del cliente | Sí | | Formato repetible CSV/XLSX/API | Sí | | Ambiente local o staging definido | Sí | ## 5.3 Condiciones de datos | Condición | Requerida | | ------------------------------ | ----------: | | Muestra de ventas | Sí | | Muestra de productos | Sí | | Muestra de clientes | Recomendado | | Muestra de stock | Recomendado | | Muestra de cobranza | Recomendado | | Histórico mínimo 3 meses | Ideal | | Histórico mínimo 1 mes | Aceptable | | Datos anónimos permitidos | Sí | | Estructura de columnas estable | Sí | --- # 6. Fases del piloto ## Resumen general | Fase | Nombre | Objetivo | Duración sugerida | | ---: | ----------------------- | ------------------------------------------------ | ----------------: | | 0 | Preparación | Alinear alcance, responsables y confidencialidad | 2-3 días | | 1 | Discovery | Levantar negocio, fuentes, dolores y decisiones | 1-3 días | | 2 | Inventario de fuentes | Completar FARO-PL-016 | 2-5 días | | 3 | Recepción de muestras | Recibir archivos y validar estructura | 2-5 días | | 4 | Diseño técnico MVP | Definir tablas, mapeos, reglas y KPIs | 3-7 días | | 5 | Carga RAW | Conservar datos originales | 1-3 días | | 6 | Staging y normalización | Limpiar, validar y transformar | 3-7 días | | 7 | KPIs y señales | Calcular indicadores y umbrales | 3-5 días | | 8 | Tensiones y acciones | Generar tensiones, responsables y workflow | 3-7 días | | 9 | Reporte y Score | Generar salida ejecutiva | 2-5 días | | 10 | Validación piloto | Revisar con cliente y ajustar | 1-2 semanas | | 11 | Cierre / expansión | Decidir continuidad, módulos y contrato | 2-5 días | --- # 7. Fase 0 · Preparación ## Objetivo Asegurar que el piloto no arranque desordenado. ## Actividades | Actividad | Responsable | Output | | -------------------------- | -------------- | ---------------------- | | Confirmar sponsor interno | FARO / Cliente | Sponsor definido | | Confirmar participantes | FARO / Cliente | Lista de participantes | | Confirmar confidencialidad | FARO / Cliente | NDA / acuerdo | | Definir alcance preliminar | FARO | Alcance v0 | | Definir fechas clave | FARO / Cliente | Cronograma | | Crear carpeta de proyecto | FARO | Repositorio documental | | Crear código de cliente | FARO | `company_code` | | Definir entorno de trabajo | Técnico FARO | Local / staging | ## Checklist | Check | Ítem | | ----- | ----------------------------------- | | ☐ | Sponsor interno identificado | | ☐ | Responsable técnico identificado | | ☐ | Responsable de negocio identificado | | ☐ | Reunión Discovery agendada | | ☐ | NDA enviado o firmado | | ☐ | Carpeta segura creada | | ☐ | Alcance preliminar definido | | ☐ | Código de cliente asignado | ## Output de fase ```yaml fase_0_preparacion: sponsor_interno: responsable_tecnico_cliente: responsable_negocio_cliente: alcance_preliminar: fecha_discovery: carpeta_proyecto: company_code: estado: listo_para_discovery ``` --- # 8. Fase 1 · Discovery ## Objetivo Ejecutar FARO-DOC-001 y obtener una primera lectura de negocio, dolores, decisiones, datos y responsables. ## Entradas | Entrada | Fuente | | ------------------------ | ------- | | FARO-DOC-001 | FARO | | Organigrama o estructura | Cliente | | Lista de sistemas | Cliente | | Reportes actuales | Cliente | | Dolores principales | Cliente | | KPIs actuales | Cliente | ## Actividades | Actividad | Responsable | Resultado | | ------------------------------- | ---------------- | --------------------- | | Ejecutar workshop | Facilitador FARO | Información levantada | | Identificar decisiones críticas | Analista FARO | Matriz de decisiones | | Identificar dolores | Analista FARO | Matriz dolor/tensión | | Identificar fuentes | Data analyst | Borrador FARO-PL-016 | | Identificar responsables | Analista FARO | RACI preliminar | | Identificar red flags | Equipo FARO | Riesgos iniciales | ## Preguntas clave 1. ¿Qué problema quiere ver antes la dirección? 2. ¿Qué fuente de datos está más disponible? 3. ¿Qué decisión se toma tarde o a ciegas? 4. ¿Qué KPI existe pero no genera acción? 5. ¿Qué responsable debería actuar ante cada tensión? 6. ¿Qué evidencia demuestra cierre real? ## Output de fase | Entregable | Código | | ----------------------------- | -------------- | | Minuta Discovery | FARO-DOC-001-R | | Mapa inicial empresa/áreas | FARO-PL-001 | | Inventario preliminar fuentes | FARO-PL-016 | | KPIs candidatos MVP | FARO-KPI-MVP | | Tensiones candidatas MVP | FARO-TNS-MVP | | Red flags iniciales | FARO-RISK-001 | ## Gate de avance Para pasar a Fase 2 deben cumplirse: | Condición | Requerida | | -------------------------------- | --------: | | Al menos 3 fuentes identificadas | Sí | | Al menos 1 responsable técnico | Sí | | Al menos 5 decisiones críticas | Sí | | Al menos 5 tensiones candidatas | Sí | | Sponsor interno activo | Sí | --- # 9. Fase 2 · Inventario de fuentes ## Objetivo Completar FARO-PL-016 con todas las fuentes relevantes del piloto. ## Entradas | Entrada | Fuente | | -------------------- | ------- | | FARO-PL-016 | FARO | | Lista de sistemas | Cliente | | Reportes actuales | Cliente | | Entrevistas por área | Cliente | | Archivos de muestra | Cliente | ## Fuentes mínimas recomendadas | Fuente | Prioridad | Motivo | | ---------------------- | --------- | ------------------------------------------ | | Ventas | P1 | Base de facturación, margen y comercial | | Productos | P1 | Permite cruzar ventas y stock | | Clientes | P1 | Permite cobranza y segmentación | | Stock | P1 | Permite quiebres, cobertura e inmovilizado | | Cobranza | P1 | Permite caja, mora y riesgo | | Vendedores / empleados | P2 | Permite desempeño y comisiones | | Compras | P2 | Permite reposición y costos | | Proveedores | P2 | Permite riesgo y abastecimiento | | Bancos | P2 | Permite conciliación y flujo | | Acciones actuales | P1 | Permite workflow y evidencia | ## Actividades | Actividad | Responsable | Output | | ---------------------------- | --------------- | -------------------- | | Completar pestaña inventario | Cliente / FARO | Fuentes relevadas | | Completar campos por fuente | Data analyst | Diccionario inicial | | Completar accesos | Cliente técnico | Mapa de acceso | | Evaluar calidad | FARO | Score DQ preliminar | | Evaluar frecuencia | FARO / Cliente | SLA de actualización | | Mapear a módulos FARO | FARO | Mapeo fuente→módulo | | Registrar riesgos | FARO | Brechas y bloqueos | ## Clasificación de fuentes | Clase | Definición | Acción | | ---------------------- | -------------------------- | -------------------- | | A · Automatizable | API, DB, export programado | Preparar conector | | B · Semi-automatizable | Export manual estable | Plantilla controlada | | C · Manual controlada | Se carga en Excel FARO | Validar formato | | D · No apta | Incompleta o no confiable | Excluir del MVP | ## Gate de avance | Condición | Requerida | | -------------------------------------- | --------: | | FARO-PL-016 completo al 70% | Sí | | Fuente de ventas clasificada | Sí | | Fuente de productos clasificada | Sí | | Al menos una fuente financiera o stock | Sí | | Responsable por fuente definido | Sí | | Riesgos principales identificados | Sí | --- # 10. Fase 3 · Recepción de muestras ## Objetivo Recibir archivos de muestra para validar estructura, calidad, campos y posibilidad de carga. ## Reglas de recepción 1. No recibir archivos por WhatsApp si contienen datos sensibles. 2. Preferir carpeta compartida controlada. 3. Registrar fecha de recepción. 4. Registrar responsable que entrega. 5. Registrar versión del archivo. 6. No modificar el archivo original. 7. Guardar copia RAW intacta. 8. Trabajar sobre copia de análisis. 9. Anonimizar cuando sea necesario. 10. No pedir datos innecesarios. ## Estructura de carpetas sugerida ```text /clientes /empresa_demo /00_admin /01_discovery /02_fuentes /03_raw_samples /04_mapping /05_staging_tests /06_kpis /07_rules /08_reports /09_evidence /10_delivery ``` ## Nomenclatura de archivos ```text {company_code}_{source_name}_{periodo}_{version}_{fecha_recepcion}.{ext} ``` Ejemplos: ```text EMP001_ventas_2026-01_v01_2026-05-30.xlsx EMP001_stock_2026-01_v01_2026-05-30.csv EMP001_cobranza_2026-Q1_v02_2026-05-30.xlsx ``` ## Validación inicial de archivo | Control | Descripción | | ------------ | -------------------------------------- | | Formato | CSV, XLSX, JSON, PDF, API | | Tamaño | Peso razonable | | Hojas | Hojas identificadas | | Encabezados | Columnas claras | | Fechas | Formato reconocible | | IDs | Documento, cliente, producto, vendedor | | Montos | Moneda, separador decimal | | Duplicados | Registros repetidos | | Vacíos | Campos críticos sin valor | | Sensibilidad | Datos personales, sueldos, bancos | ## Checklist por archivo | Check | Ítem | | ----- | ------------------------------- | | ☐ | Archivo recibido | | ☐ | Nombre normalizado | | ☐ | Copia RAW guardada | | ☐ | Fuente vinculada en FARO-PL-016 | | ☐ | Responsable registrado | | ☐ | Periodo identificado | | ☐ | Columnas principales detectadas | | ☐ | Riesgo de sensibilidad revisado | | ☐ | Calidad preliminar evaluada | | ☐ | Apto para mapping | ## Output de fase ```yaml muestras_recibidas: - fuente: archivo: periodo: responsable: formato: registros_estimados: columnas_detectadas: calidad_preliminar: apto_mapping: true ``` --- # 11. Fase 4 · Diseño técnico MVP ## Objetivo Traducir fuentes y datos en diseño técnico inicial. ## Decisiones técnicas mínimas | Decisión | Opciones | Criterio | | ----------------- | ----------------------------------- | ------------------------- | | Base de datos | PostgreSQL | Estándar MVP | | Storage RAW | S3 / Supabase / GCS / local demo | Según piloto | | Backend | FastAPI / Node / monolito modular | Según equipo | | Jobs | Celery / RQ / BullMQ / cron | Según stack | | Frontend | Next.js / React | Producto web | | Validación schema | JSON Schema / Zod / SQL constraints | Preferible combinada | | Reglas | YAML/JSON declarativo | Evitar hardcodear | | IA | Explicativa controlada | No decide ni inventa | | Seguridad | company_id + roles + RLS futuro | Multiempresa desde inicio | ## Actividades | Actividad | Responsable | Output | | ---------------------- | ----------------------- | ----------------------- | | Definir entidades base | Data engineer | Modelo inicial | | Definir RAW tables | Data engineer | SQL base | | Definir staging tables | Data engineer | SQL base | | Definir maestros | Data analyst / engineer | Master data | | Definir facts | Data engineer | Ventas, stock, cobranza | | Definir KPIs MVP | Analista negocio | Lista priorizada | | Definir tensiones MVP | Analista FARO | Reglas candidatas | | Definir acciones | Analista FARO | Workflow base | | Definir permisos | Seguridad / backend | Roles y policies | ## Modelo mínimo de entidades | Entidad | Uso | | ---------------- | ---------------------- | | companies | Empresa / cliente | | branches | Sucursales | | areas | Áreas | | users | Usuarios | | roles | Roles | | permissions | Permisos | | products | Maestro productos | | customers | Maestro clientes | | suppliers | Maestro proveedores | | employees | Empleados / vendedores | | raw_ingestions | Lotes RAW | | raw_records | Registros originales | | staging_records | Registros normalizados | | fact_sales | Ventas | | fact_stock | Stock | | fact_receivables | Cuentas por cobrar | | kpi_snapshots | KPIs calculados | | signal_log | Señales | | rule_evaluations | Evaluaciones de reglas | | tensions | Tensiones | | actions | Acciones | | evidence | Evidencias | | score_snapshots | FARO Score | | reports | Reportes | ## Gate de avance | Condición | Requerida | | ----------------------------- | --------: | | Entidades MVP definidas | Sí | | Tablas RAW definidas | Sí | | Tablas staging definidas | Sí | | KPIs MVP definidos | Sí | | Tensiones MVP seleccionadas | Sí | | Mapeo fuente→tabla definido | Sí | | Riesgos técnicos documentados | Sí | --- # 12. Fase 5 · Carga RAW ## Objetivo Guardar los datos originales sin alterarlos. RAW es la verdad recibida, no la verdad corregida. ## Principios RAW 1. Nunca modificar el archivo original. 2. Guardar payload original. 3. Registrar fuente. 4. Registrar lote de carga. 5. Registrar usuario/responsable. 6. Registrar timestamp. 7. Registrar hash/checksum. 8. Registrar estado de carga. 9. Permitir reproceso. 10. Mantener trazabilidad hasta staging y facts. ## Estados de ingesta | Estado | Descripción | | ------------- | -------------------------- | | received | Archivo recibido | | stored | Archivo almacenado | | parsed | Archivo leído | | failed_parse | Error al leer | | loaded_raw | Registros cargados | | rejected | Archivo rechazado | | quarantined | Archivo aislado por riesgo | | ready_staging | Listo para staging | ## Campos mínimos RAW ingestion | Campo | Tipo | Descripción | | ------------- | --------- | ------------------ | | ingestion_id | UUID | ID lote | | company_id | UUID | Empresa | | source_id | UUID | Fuente | | file_name | text | Nombre archivo | | file_type | text | CSV/XLSX/JSON/API | | file_hash | text | Checksum | | received_at | timestamp | Fecha recepción | | uploaded_by | UUID | Usuario | | records_count | integer | Cantidad registros | | status | text | Estado | | error_message | text | Error si aplica | ## Campos mínimos RAW record | Campo | Tipo | Descripción | | ------------- | --------- | ---------------------- | | raw_record_id | UUID | ID registro | | ingestion_id | UUID | Lote | | company_id | UUID | Empresa | | row_number | integer | Fila original | | payload | jsonb | Registro original | | created_at | timestamp | Fecha carga | | dq_status | text | ok/warning/error/fatal | | dq_errors | jsonb | Errores detectados | ## Checklist | Check | Ítem | | ----- | ----------------------------- | | ☐ | Archivo RAW almacenado | | ☐ | Hash generado | | ☐ | Lote creado | | ☐ | Registros parseados | | ☐ | Payload original preservado | | ☐ | Conteo de registros validado | | ☐ | Errores de parseo registrados | | ☐ | Listo para staging | --- # 13. Fase 6 · Staging y normalización ## Objetivo Transformar datos originales en datos utilizables. Staging no es “limpiar a mano”. Es aplicar reglas explícitas, repetibles y auditables. ## Transformaciones típicas | Transformación | Ejemplo | | -------------- | ------------------------------------- | | Fechas | `30/05/2026` → `2026-05-30` | | Moneda | `$ 1.250,50` → `1250.50` | | Producto | `Cemento 50kg` → producto normalizado | | Cliente | `JUAN PEREZ SRL` → customer_id | | Vendedor | `M. Lopez` → employee_id | | Sucursal | `SJ` → branch_id | | Documento | `F A-0001-000123` → document_number | | Descuento | `10%` → `0.10` | | Margen | Calcular si faltara | | Nulos | Clasificar según criticidad | ## Estados DQ | Estado | Definición | Acción | | ------- | -------------------------- | ---------------------- | | ok | Registro válido | Procesar | | warning | Error menor no bloqueante | Procesar con marca | | error | Error relevante corregible | Revisar o corregir | | fatal | No puede procesarse | Excluir hasta resolver | ## Reglas mínimas de calidad | Regla | Severidad | | ----------------------------------- | ------------------------ | | Fecha vacía en venta | fatal | | Monto de venta vacío | fatal | | Producto no identificado | error | | Cliente no identificado | warning/error según caso | | Vendedor no identificado | warning | | Margen negativo | warning/error | | Descuento mayor al máximo permitido | warning | | Stock negativo | error | | Factura sin vencimiento | error | | Pago sin factura asociada | warning/error | ## Output staging | Tabla | Descripción | | ------------------- | ---------------------- | | staging_sales | Ventas normalizadas | | staging_products | Productos normalizados | | staging_customers | Clientes normalizados | | staging_stock | Stock normalizado | | staging_receivables | Cobranzas normalizadas | | staging_purchases | Compras normalizadas | | staging_employees | Vendedores / empleados | | staging_suppliers | Proveedores | ## Checklist | Check | Ítem | | ----- | -------------------------------------- | | ☐ | Campos mapeados | | ☐ | Fechas normalizadas | | ☐ | Monedas normalizadas | | ☐ | IDs maestros relacionados | | ☐ | DQ status asignado | | ☐ | Errores registrados | | ☐ | Registros fatales excluidos | | ☐ | Registros warning procesados con marca | | ☐ | Resumen de calidad generado | --- # 14. Fase 7 · KPIs y señales ## Objetivo Calcular KPIs MVP y detectar señales relevantes. Un KPI es una medición. Una señal es una variación o condición que merece atención. ## KPIs iniciales recomendados | Código | KPI | Fuente | | ----------- | -------------------------- | ------------------ | | KPI-SAL-001 | Ventas netas | Ventas | | KPI-SAL-002 | Margen bruto | Ventas / costos | | KPI-SAL-003 | Descuento promedio | Ventas | | KPI-SAL-004 | Venta por vendedor | Ventas / empleados | | KPI-FIN-001 | Días de cobranza | Cobranzas | | KPI-FIN-002 | Mora vencida | Cobranzas | | KPI-FIN-003 | Cobranza sobre facturación | Ventas / cobranzas | | KPI-STK-001 | Stock crítico | Stock / ventas | | KPI-STK-002 | Cobertura de stock | Stock / ventas | | KPI-STK-003 | Stock inmovilizado | Stock | | KPI-COM-001 | Variación de costo | Compras | | KPI-OPS-001 | Acciones vencidas | Acciones | ## Señales iniciales recomendadas | Señal | Condición | | ------------------ | ---------------------------------------- | | Ventas suben | Variación ventas > umbral | | Margen baja | Margen actual < margen referencia | | Descuento sube | Descuento actual > promedio histórico | | Cobranza se estira | Días cobranza > umbral | | Mora crece | Mora vencida > umbral | | Stock crítico | Cobertura < mínimo | | Stock inmovilizado | Días sin rotación > umbral | | Acción vencida | Fecha vencimiento < hoy y estado abierto | ## Campos mínimos kpi_snapshot | Campo | Descripción | | ---------------- | --------------------------------- | | kpi_snapshot_id | ID | | company_id | Empresa | | kpi_code | Código KPI | | period_start | Inicio período | | period_end | Fin período | | dimension_type | empresa/sucursal/área/responsable | | dimension_id | ID dimensión | | value | Valor | | reference_value | Valor referencia | | delta | Variación | | status | ok/warning/critical | | confidence_score | Confianza | | calculated_at | Fecha cálculo | ## Gate de avance | Condición | Requerida | | --------------------------- | ----------: | | Al menos 8 KPIs calculados | Sí | | KPIs por empresa | Sí | | KPIs por sucursal si aplica | Recomendado | | KPIs por vendedor si aplica | Recomendado | | Confianza calculada | Sí | | Señales generadas | Sí | --- # 15. Fase 8 · Tensiones, acciones y workflow ## Objetivo Convertir señales en tensiones FARO y tensiones en acciones. ## Principio clave FARO no debe alertar por cada número raro. Debe detectar combinaciones de señales que representen una tensión ejecutiva. Ejemplo: ```text Ventas suben + Margen baja + Descuento sube + Cobranza se estira = Tensión: crecimiento no rentable ``` ## Tensión MVP recomendada | Código | Tensión | Señales | | ------- | --------------------------- | ------------------------------------------- | | TNS-001 | Crecimiento no rentable | Ventas suben + margen baja + descuento sube | | TNS-002 | Venta sin caja | Ventas altas + cobranza baja + mora alta | | TNS-003 | Stock crítico comercial | Ventas altas + cobertura baja | | TNS-004 | Stock inmovilizado | Stock alto + rotación baja | | TNS-005 | Descuento fuera de política | Descuento alto + margen bajo | | TNS-006 | Reposición reactiva | Stock crítico + compras urgentes | | TNS-007 | Cliente de alto riesgo | Compra alta + mora alta | | TNS-008 | Vendedor erosiona margen | Venta alta + descuento alto + margen bajo | | TNS-009 | Acciones sin cierre | Acciones vencidas + sin evidencia | | TNS-010 | Dirección sin visibilidad | Datos atrasados + reportes manuales | ## Campos mínimos de tensión | Campo | Descripción | | ------------------- | -------------------------------------- | | tension_id | ID | | company_id | Empresa | | tension_code | Código | | title | Nombre | | description | Descripción | | severity | baja/media/alta/crítica | | area_id | Área | | responsible_user_id | Responsable | | detected_at | Fecha detección | | status | nueva/en análisis/en ejecución/cerrada | | confidence_score | Confianza | | evidence_required | Evidencia requerida | | score_impact | Impacto en FARO Score | ## Acciones | Campo | Descripción | | ------------------- | ---------------- | | action_id | ID | | tension_id | Tensión | | company_id | Empresa | | action_title | Acción | | responsible_user_id | Responsable | | approver_user_id | Aprobador | | due_date | Vencimiento | | status | Estado | | expected_impact | Impacto esperado | | evidence_required | Evidencia | | created_at | Creación | ## Workflow | Estado | Criterio de entrada | Criterio de salida | | --------------- | ------------------------- | ------------------------- | | Nueva | Tensión detectada | Responsable asignado | | En análisis | Responsable revisando | Acción definida | | En ejecución | Acción en marcha | Evidencia cargada | | En verificación | Evidencia cargada | Evidencia aprobada | | Cerrada | Cierre aprobado | Medición posterior | | Vencida | SLA vencido | Reprogramar o escalar | | Escalada | Riesgo alto o vencimiento | Dirección decide | | Rechazada | Falso positivo | Justificación obligatoria | ## Checklist | Check | Ítem | | ----- | --------------------------- | | ☐ | Reglas MVP cargadas | | ☐ | Señales vinculadas a reglas | | ☐ | Tensiones generadas | | ☐ | Severidad calculada | | ☐ | Responsable asignado | | ☐ | Acción sugerida creada | | ☐ | SLA definido | | ☐ | Evidencia requerida | | ☐ | Impacto en Score definido | | ☐ | Workflow probado | --- # 16. Fase 9 · FARO Score y reporte ejecutivo ## Objetivo Sintetizar el estado del piloto en una lectura ejecutiva clara. El FARO Score no debe ser un promedio simple. Debe reflejar: * KPIs; * alertas; * tensiones; * severidad; * ejecución; * acciones vencidas; * evidencia; * calidad de datos; * confianza; * riesgo; * impacto. ## Score v1 piloto Para el piloto, usar una versión controlada: | Dimensión | Peso sugerido | | ---------------------------- | ------------: | | Salud comercial | 20% | | Rentabilidad / margen | 20% | | Caja / cobranza | 15% | | Stock / operación | 15% | | Ejecución de acciones | 15% | | Calidad y confianza de datos | 10% | | Riesgo crítico | 5% | ## Salida del reporte semanal | Sección | Contenido | | ----------------- | ------------------------------------------- | | Resumen ejecutivo | Lectura clara para dirección | | FARO Score | Score actual, variación y explicación | | Top tensiones | 3 a 5 tensiones principales | | Acciones críticas | Vencidas, próximas y bloqueadas | | KPIs clave | Ventas, margen, descuentos, cobranza, stock | | Evidencia | Acciones cerradas y evidencia recibida | | Riesgos | Dato, operación, responsables | | Recomendaciones | Próximas decisiones sugeridas | | Próxima semana | Foco ejecutivo | ## Checklist reporte | Check | Ítem | | ----- | --------------------------- | | ☐ | Score calculado | | ☐ | Variación explicada | | ☐ | Top tensiones incluidas | | ☐ | Acciones vencidas incluidas | | ☐ | Acciones cerradas incluidas | | ☐ | KPIs con fuente incluida | | ☐ | Confianza de datos visible | | ☐ | Recomendaciones prudentes | | ☐ | No se inventan datos | | ☐ | Dirección puede decidir | --- # 17. Fase 10 · Validación con cliente ## Objetivo Validar si FARO genera lectura útil, no solo datos correctos. ## Preguntas de validación ejecutiva 1. ¿La tensión detectada tiene sentido? 2. ¿El responsable asignado es correcto? 3. ¿La acción sugerida es razonable? 4. ¿La evidencia requerida es posible? 5. ¿El Score refleja la realidad de la empresa? 6. ¿El reporte ayuda a decidir? 7. ¿Qué alerta fue ruido? 8. ¿Qué alerta faltó? 9. ¿Qué KPI no sirve? 10. ¿Qué dato necesita más confianza? ## Matriz de feedback | Elemento | Correcto | Ajustar | Eliminar | Comentario | | --------------- | -------- | ------- | -------- | ---------- | | KPI ventas | Sí / No | | | | | KPI margen | Sí / No | | | | | Tensión TNS-001 | Sí / No | | | | | Acción sugerida | Sí / No | | | | | Responsable | Sí / No | | | | | Score | Sí / No | | | | | Reporte | Sí / No | | | | ## Criterios de éxito del piloto | Criterio | Mínimo aceptable | | ----------------------- | ---------------- | | Fuentes cargadas | 3 | | KPIs calculados | 8 | | Tensiones detectadas | 5 | | Acciones generadas | 5 | | Responsables asignados | 3 | | Evidencias cargadas | 3 | | Reportes semanales | 2 | | Validación dirección | Sí | | Continuidad recomendada | Sí / No | --- # 18. Fase 11 · Cierre y decisión de continuidad ## Objetivo Cerrar el piloto con evidencia, aprendizajes y decisión comercial/técnica. ## Posibles decisiones | Decisión | Criterio | | ----------------------- | ------------------------------- | | Continuar a fase paga | El piloto mostró valor | | Extender piloto | Faltan datos pero hay potencial | | Repetir con otra fuente | Fuente inicial no alcanzó | | Pausar | Cliente no tiene madurez | | Rechazar implementación | Datos o sponsor insuficientes | ## Entregables de cierre | Entregable | Descripción | | ----------------------- | --------------------------- | | Informe cierre piloto | Resultado ejecutivo | | Matriz de fuentes final | Fuentes usadas y pendientes | | KPIs validados | Indicadores aceptados | | Tensiones validadas | Tensiones útiles | | Acciones ejecutadas | Seguimiento y evidencia | | Score evolución | Antes / después | | Riesgos remanentes | Qué falta resolver | | Roadmap siguiente fase | Qué construir después | | Propuesta comercial | Plan recomendado | ## Plantilla de cierre ```yaml cierre_piloto: cliente: periodo: fuentes_cargadas: kpis_calculados: tensiones_detectadas: acciones_generadas: acciones_cerradas: evidencias_recibidas: score_inicial: score_final: principales_logros: - principales_bloqueos: - recomendacion: tipo: continuar | extender | pausar | rechazar motivo: proxima_fase: modulos: integraciones: usuarios: plazo: ``` --- # 19. Cronograma recomendado 30 días ## Semana 1 · Relevamiento y datos | Día | Actividad | | --: | -------------------------------- | | 1 | Kickoff + confidencialidad | | 2 | Workshop Discovery | | 3 | Completar inventario FARO-PL-016 | | 4 | Recibir muestras de datos | | 5 | Validar archivos y riesgos | ## Semana 2 · Modelo y carga | Día | Actividad | | --: | -------------------------------- | | 6 | Diseño técnico MVP | | 7 | Crear tablas RAW/staging | | 8 | Cargar ventas/productos/clientes | | 9 | Cargar stock/cobranza | | 10 | Validar calidad y normalización | ## Semana 3 · KPIs, reglas y acciones | Día | Actividad | | --: | --------------------------- | | 11 | Calcular KPIs MVP | | 12 | Generar señales | | 13 | Configurar tensiones MVP | | 14 | Generar acciones | | 15 | Probar workflow y evidencia | ## Semana 4 · Reporte y validación | Día | Actividad | | --: | ---------------------------------- | | 16 | Calcular Score | | 17 | Generar reporte semanal | | 18 | Revisión interna FARO | | 19 | Presentación cliente | | 20 | Ajustes y cierre primera iteración | --- # 20. Cronograma recomendado 60 días | Semana | Objetivo | | -----: | ---------------------------------------------- | | 1 | Discovery + inventario | | 2 | Recepción y validación de fuentes | | 3 | Modelo técnico + carga RAW | | 4 | Staging + normalización | | 5 | KPIs + señales | | 6 | Tensiones + acciones | | 7 | Reporte + Score + evidencia | | 8 | Validación, ajustes y propuesta de continuidad | --- # 21. Matriz RACI del piloto | Actividad | FARO Dirección | Líder implementación | Data engineer | Backend | Frontend | Cliente técnico | Cliente negocio | | -------------------- | -------------- | -------------------- | ------------- | ------- | -------- | --------------- | --------------- | | Definir alcance | A | R | C | C | C | C | C | | Ejecutar workshop | C | R | C | I | I | C | A | | Completar inventario | I | R | C | I | I | C | A | | Recibir muestras | I | R | C | I | I | A | C | | Diseñar modelo SQL | I | C | R | C | I | C | I | | Cargar RAW | I | C | R | C | I | C | I | | Normalizar staging | I | C | R | C | I | C | C | | Calcular KPIs | C | R | C | R | I | I | C | | Configurar reglas | C | R | C | R | I | I | C | | Crear UI piloto | C | C | I | C | R | I | C | | Generar reporte | A | R | C | C | C | I | C | | Validar resultados | A | R | C | C | C | C | A | | Cierre piloto | A | R | I | I | I | C | A | Leyenda: * **R:** Responsable ejecutor * **A:** Aprobador * **C:** Consultado * **I:** Informado --- # 22. Riesgos y mitigaciones ## Riesgos técnicos | Riesgo | Severidad | Mitigación | | --------------------------- | ---------- | -------------------------------------- | | ERP no exporta datos | Alta | Usar export manual / plantilla FARO | | Archivos cambian de formato | Alta | Definir contrato de columnas | | No hay IDs únicos | Alta | Crear claves compuestas temporales | | Datos incompletos | Media/Alta | Clasificar DQ y excluir lo fatal | | Carga manual inconsistente | Media | Validaciones en plantilla | | Histórico insuficiente | Media | Piloto con período corto y advertencia | | Performance baja | Media | Reducir alcance y batch inicial | | Seguridad no definida | Alta | Roles mínimos y separación company_id | ## Riesgos organizacionales | Riesgo | Severidad | Mitigación | | ----------------------------- | --------- | ------------------------------- | | Sponsor no participa | Alta | No iniciar o pausar | | Áreas no entregan datos | Alta | Escalar a sponsor | | Responsables no usan acciones | Alta | Piloto con pocos usuarios clave | | Cliente espera IA mágica | Media | Reforzar reglas y datos primero | | Dirección quiere todo | Alta | Acotar MVP con criterios | | Nadie valida resultados | Alta | Reunión semanal obligatoria | ## Riesgos de producto | Riesgo | Severidad | Mitigación | | ------------------------------------- | --------- | ----------------------------------- | | FARO parece dashboard | Alta | Mostrar acciones, evidencia y score | | Muchas alertas generan ruido | Alta | Limitar tensiones MVP | | Score no se entiende | Media | Explicar fórmula v1 y confianza | | Reporte demasiado largo | Media | Resumen ejecutivo primero | | UI piloto parece producto final pobre | Media | Aclarar que es demo funcional | --- # 23. Política de cambios durante el piloto ## Regla general No se agregan nuevas fuentes, KPIs o tensiones sin evaluar impacto. El entusiasmo del cliente es bueno. El descontrol del alcance no. ## Clasificación de cambios | Tipo | Ejemplo | Decisión | | ----------------- | --------------------- | ---------------- | | Corrección | Campo mal mapeado | Se acepta | | Ajuste menor | Cambiar nombre de KPI | Se acepta | | Mejora | Nuevo umbral | Se evalúa | | Nuevo alcance | Agregar RRHH completo | Backlog | | Nueva integración | API ERP | Fase siguiente | | Nueva industria | Otro rubro | Fuera del piloto | ## Formato de solicitud de cambio ```yaml change_request: id: fecha: solicitante: descripcion: motivo: impacto_en_datos: impacto_en_tiempo: impacto_en_costo: decision: aceptado | rechazado | backlog aprobador: ``` --- # 24. Política de seguridad y datos ## Principios 1. Usar datos mínimos necesarios. 2. Anonimizar cuando sea posible. 3. No pedir claves por chat. 4. No compartir archivos sensibles fuera de canal acordado. 5. Separar datos por empresa. 6. Registrar cargas y responsables. 7. Evitar datos personales innecesarios. 8. No usar información del cliente para demos externas sin permiso. 9. No entrenar modelos con datos del cliente sin autorización explícita. 10. No permitir que IA invente datos faltantes. ## Datos sensibles | Tipo de dato | Tratamiento | | ---------------- | ------------------------- | | Sueldos | Restringido | | Comisiones | Restringido | | Márgenes | Restringido | | Bancos | Restringido | | Clientes | Controlado | | Proveedores | Controlado | | Datos personales | Minimizar | | Contratos | Solo si es imprescindible | | Facturas | Anonimizar si aplica | ## Accesos mínimos | Rol | Acceso | | ----------------- | ---------------------------------- | | Dirección FARO | Resumen y datos necesarios | | Data engineer | Archivos y estructura | | Backend | Datos técnicos necesarios | | Frontend | Datos anonimizados preferentemente | | Cliente técnico | Fuentes y exportaciones | | Cliente dirección | Reportes y resultados | --- # 25. Rollback y contingencia ## Cuándo aplicar rollback | Caso | Acción | | ----------------------------- | ----------------------------------- | | Carga incorrecta | Revertir lote | | Mapeo incorrecto | Reprocesar staging | | KPI mal calculado | Invalidar snapshot | | Regla genera falsos positivos | Desactivar regla | | Acción mal asignada | Reasignar con auditoría | | Score distorsionado | Recalcular versión | | Datos sensibles expuestos | Bloquear acceso y revisar incidente | ## Procedimiento rollback de lote ```text 1. Identificar ingestion_id. 2. Marcar lote como invalidado. 3. Eliminar o invalidar staging asociado. 4. Invalidar facts derivados. 5. Invalidar KPIs derivados. 6. Invalidar señales y tensiones derivadas. 7. Registrar motivo. 8. Reprocesar desde RAW corregido. 9. Validar resultados. 10. Notificar al equipo. ``` ## Registro de incidente ```yaml incident: id: fecha: tipo: severidad: descripcion: fuente_afectada: registros_afectados: impacto: accion_correctiva: responsable: estado: ``` --- # 26. Criterios de aceptación técnica ## Datos | Criterio | Aceptación | | ---------------------------- | ------------------- | | RAW preserva original | 100% | | Staging vincula a RAW | Sí | | DQ status asignado | Sí | | Registros fatales separados | Sí | | Registros válidos procesados | Sí | | Conteos coinciden | Tolerancia definida | | Reproceso posible | Sí | ## KPIs | Criterio | Aceptación | | --------------------- | ---------------------------- | | Fórmula definida | Sí | | Fuente identificada | Sí | | Resultado verificable | Sí | | Periodo claro | Sí | | Dimensión clara | Empresa/sucursal/responsable | | Confianza calculada | Sí | ## Tensiones | Criterio | Aceptación | | -------------------------- | ---------- | | Regla definida | Sí | | Señales asociadas | Sí | | Severidad definida | Sí | | Responsable asignado | Sí | | Acción sugerida | Sí | | Evidencia requerida | Sí | | Falsos positivos revisados | Sí | ## Reporte | Criterio | Aceptación | | -------------------------- | ---------- | | Resumen ejecutivo claro | Sí | | Top tensiones visibles | Sí | | Acciones vencidas visibles | Sí | | Score explicado | Sí | | Confianza de datos visible | Sí | | Recomendación prudente | Sí | --- # 27. Criterios de aceptación ejecutiva El piloto es exitoso si la dirección puede responder: 1. ¿Qué está pasando? 2. ¿Por qué importa? 3. ¿Dónde está ocurriendo? 4. ¿Quién debe actuar? 5. ¿Qué acción se recomienda? 6. ¿Cuándo debe cerrarse? 7. ¿Qué evidencia se necesita? 8. ¿Cómo impacta en el Score? 9. ¿Qué debe decidir esta semana? 10. ¿Qué cambió respecto a la semana anterior? Si el sistema solo muestra números, el piloto queda incompleto. --- # 28. Salidas documentales obligatorias Durante el piloto deben generarse estas piezas: | Código | Documento | | -------------- | ---------------------------- | | FARO-DOC-001-R | Minuta Workshop Discovery | | FARO-PL-016 | Inventario Fuentes de Datos | | FARO-MAP-001 | Mapa fuente → campo → tabla | | FARO-DQ-001 | Diagnóstico calidad de datos | | FARO-KPI-MVP | KPIs MVP seleccionados | | FARO-TNS-MVP | Tensiones MVP seleccionadas | | FARO-ACT-MVP | Acciones MVP | | FARO-RACI-MVP | Responsables y permisos | | FARO-RISK-001 | Riesgos del piloto | | FARO-REP-001 | Reporte semanal piloto | | FARO-CLOSE-001 | Informe cierre piloto | --- # 29. Salidas técnicas obligatorias | Código | Artefacto técnico | | ------------- | ------------------------- | | FARO-SQL-001 | Migraciones base | | FARO-SQL-002 | Multiempresa, roles y RLS | | FARO-SQL-003 | Seeds empresa piloto/demo | | FARO-CFG-001 | Reglas MVP YAML | | FARO-CFG-003 | Política retención | | FARO-ENG-001 | Scaffold conectores | | FARO-ENG-002 | Parser reglas | | FARO-ENG-003 | Motor evaluador | | FARO-TEST-001 | Tests KPI | | FARO-TEST-002 | Tests reglas | | FARO-DEMO-001 | Dataset demo integral | --- # 30. Comandos conceptuales del piloto Estos comandos son referenciales. El equipo técnico deberá adaptarlos al stack real. ```bash # 1. Levantar entorno demo docker compose up -d # 2. Correr migraciones npm run db:migrate # 3. Cargar seeds base npm run db:seed # 4. Ingestar archivo npm run ingest --source=sales --file=./data/ventas.csv # 5. Procesar RAW a staging npm run staging --source=sales # 6. Calcular KPIs npm run kpis:calculate --period=2026-05 # 7. Evaluar reglas npm run rules:evaluate --period=2026-05 # 8. Generar tensiones npm run tensions:generate --period=2026-05 # 9. Generar acciones npm run actions:generate # 10. Generar reporte npm run report:weekly --company=EMP001 ``` --- # 31. Tablero interno de seguimiento del piloto | Semana | Objetivo | Estado | Riesgo | Responsable | Próximo paso | | ------ | -------------------- | ---------------------------- | ------ | ----------- | ------------ | | 1 | Discovery + fuentes | Pendiente / En curso / Listo | | | | | 2 | Datos + RAW | | | | | | 3 | Staging + KPIs | | | | | | 4 | Tensiones + acciones | | | | | | 5 | Reporte + validación | | | | | | 6 | Cierre + expansión | | | | | --- # 32. Guion para presentar avance al cliente ## Primera reunión de avance > Ya relevamos las fuentes principales, identificamos responsables y recibimos muestras iniciales. El foco del piloto no será automatizar todo, sino demostrar un flujo completo: datos disponibles, KPIs confiables, tensiones accionables, responsables claros y reporte ejecutivo. ## Segunda reunión de avance > Los datos ya fueron cargados en RAW y pasaron por una primera normalización. Detectamos algunos problemas de calidad que vamos a separar entre bloqueantes y no bloqueantes. Esto es positivo: FARO no solo mide, también muestra dónde el dato no puede usarse con confianza. ## Tercera reunión de avance > Ya calculamos los primeros KPIs y detectamos señales. El siguiente paso es convertir esas señales en tensiones concretas y asociarlas a acciones, responsables y evidencia. ## Presentación final > El piloto permitió demostrar la cadena completa: dato, KPI, tensión, acción, evidencia, score y reporte. La recomendación es avanzar con una siguiente fase enfocada en estabilizar fuentes, ampliar reglas y habilitar usuarios operativos. --- # 33. Errores comunes a evitar | Error | Consecuencia | | ---------------------------------- | ---------------------------------- | | Querer conectar todos los sistemas | Se demora el piloto | | Empezar por UI | Se construyen pantallas sin verdad | | Aceptar datos sin validar | KPIs incorrectos | | No definir responsables | Acciones inútiles | | No pedir evidencia | Cierres ficticios | | Usar IA antes de reglas | Riesgo de humo | | Prometer integración total | Expectativa peligrosa | | Medir demasiados KPIs | Ruido ejecutivo | | No mostrar confianza de datos | Falsa precisión | | No cerrar con reporte | Piloto sin decisión | --- # 34. Frase operativa del piloto Un piloto FARO no se gana por cantidad de pantallas. Se gana cuando un director puede mirar el sistema y decir: ```text Ahora entiendo qué está pasando, por qué importa, quién debe actuar, qué evidencia necesito y cómo eso afecta la salud real de la empresa. ``` --- # 35. Próximo paso recomendado Después de este runbook, el siguiente entregable lógico es: ## FARO-SQL-001 · Migraciones Base MVP Objetivo: Crear la estructura inicial de base de datos para soportar: * empresas; * sucursales; * áreas; * usuarios; * roles; * fuentes; * ingestas RAW; * staging; * maestros; * facts; * KPIs; * señales; * reglas; * tensiones; * acciones; * evidencia; * score; * reportes. Sin FARO-SQL-001, el piloto queda documentado, pero no construible.