ANEXO 9

RAW y trazabilidad

Este anexo corresponde a la Fase 2 — Resguardo, especialmente a las etapas RAW y Control de origen de FARO Connect.

1. Objetivo del anexo

El objetivo del Anexo 9 — RAW y trazabilidad es definir cómo FARO Connect guarda la información original, sin modificarla, para que cada dato, KPI, alerta, tensión, recomendación o acción pueda ser auditado desde su origen.

La pregunta central es:

¿De dónde salió este dato y cómo llegó hasta esta conclusión?

FARO debe poder responder eso con precisión.

No alcanza con decir:

“El margen bajó.”

FARO tiene que poder demostrar:

El margen bajó porque:
- se tomó la venta del archivo ventas_mayo.xlsx,
- cargado el 27/05/2026,
- por Administración,
- desde la sucursal San Juan,
- procesado en el lote LOAD_2026_05_27_001,
- usando costo unitario del ERP,
- con descuento informado por Comercial,
- y validado contra la tabla maestra de productos.

Eso es trazabilidad. Sin trazabilidad, FARO puede ser interesante, pero no confiable.

2. Tesis del Anexo 9

La tesis es:

FARO Connect debe conservar siempre el dato original antes de limpiarlo, normalizarlo, interpretarlo o usarlo para tomar decisiones.

El dato original es la evidencia.

Después se puede limpiar, ordenar, corregir, mapear, normalizar y enriquecer. Pero la versión original no debe perderse nunca.

En términos simples:

RAW = lo que llegó.
Staging = lo que se limpió.
Normalizado = lo que se ordenó.
Modelo ejecutivo = lo que se puede usar para dirigir.

Si algo sale mal, FARO debe poder volver al RAW y reconstruir el camino.

3. Qué es RAW

RAW significa dato crudo.

Es la información guardada exactamente como llegó desde la fuente.

Puede venir desde:

Excel
ERP
CRM
Banco
WhatsApp
PDF
API
POS
Google Sheets
Sistema de stock
Sistema de RRHH
Formulario interno
Acta de reunión

Ejemplo:

Un Excel trae este producto:

Cem x50

FARO lo guarda así en RAW:

{
  "producto": "Cem x50",
  "cantidad": "100",
  "precio": "$ 8.500",
  "descuento": "8%",
  "vendedor": "Juan P.",
  "fecha": "27/05/26"
}

Después, en normalización, puede transformarlo en:

{
  "product_id": "PROD_001",
  "producto_normalizado": "CEMENTO_BOLSA_50KG",
  "cantidad": 100,
  "precio_unitario": 8500,
  "descuento": 0.08,
  "vendedor_id": "EMP_014",
  "fecha": "2026-05-27"
}

Pero el RAW original queda guardado.

4. Por qué RAW es crítico

La regla debería ser:

FARO nunca destruye el dato original. Lo preserva, lo versiona y lo audita.

5. Diferencia entre RAW, Staging, Normalización y Modelo Ejecutivo

Ejemplo completo:

RAW:
"Cem x50"

Staging:
"cem x50"

Normalización:
"CEMENTO_BOLSA_50KG"

Modelo ejecutivo:
Producto PROD_001, categoría Cemento, costo actualizado, margen calculable.

6. Qué debe guardar FARO en RAW

FARO debe guardar dos cosas:

1. El dato original.
2. La metadata de origen.

6.1 Dato original

Puede ser:

Fila de Excel.
Archivo completo.
Evento API.
Mensaje de WhatsApp.
Movimiento bancario.
Registro de ERP.
PDF.
Acta.
Formulario.

6.2 Metadata de origen

Debe incluir:

Fuente.
Usuario o sistema que lo envió.
Fecha y hora de carga.
Empresa.
Sucursal.
Área.
Archivo original.
Versión.
Lote de carga.
Estado.
Cantidad de registros.
Errores detectados.
Hash o identificador único.

Sin metadata, el RAW queda rengo. Es como tener una factura sin fecha ni proveedor.

7. Metadata obligatoria por carga

Ejemplo:

{
  "load_id": "LOAD_2026_05_27_001",
  "source_id": "EXCEL_VENTAS_001",
  "source_type": "excel",
  "company_id": "COMP_001",
  "branch_id": "SUC_SAN_JUAN",
  "area": "Comercial",
  "uploaded_by": "administracion",
  "uploaded_at": "2026-05-27T22:00:00",
  "file_name": "ventas_mayo.xlsx",
  "file_version": "v1",
  "record_count": 1200,
  "status": "received",
  "checksum": "a93f8d1c...",
  "processing_version": "rules_v1.0"
}

8. Modelo de base de datos RAW

Una estructura inicial podría ser así:

CREATE TABLE raw_imports (
    id UUID PRIMARY KEY,
    load_id TEXT UNIQUE NOT NULL,
    source_id TEXT NOT NULL,
    source_type TEXT NOT NULL,
    company_id TEXT NOT NULL,
    branch_id TEXT,
    area TEXT,
    uploaded_by TEXT,
    uploaded_at TIMESTAMP DEFAULT now(),
    file_name TEXT,
    file_version TEXT,
    record_count INTEGER,
    status TEXT DEFAULT 'received',
    checksum TEXT,
    processing_version TEXT,
    raw_payload JSONB,
    created_at TIMESTAMP DEFAULT now()
);

Para eventos individuales:

CREATE TABLE raw_events (
    id UUID PRIMARY KEY,
    load_id TEXT,
    source_id TEXT NOT NULL,
    event_type TEXT NOT NULL,
    company_id TEXT NOT NULL,
    branch_id TEXT,
    area TEXT,
    occurred_at TIMESTAMP,
    received_at TIMESTAMP DEFAULT now(),
    raw_payload JSONB NOT NULL,
    status TEXT DEFAULT 'received',
    checksum TEXT,
    created_at TIMESTAMP DEFAULT now()
);

Para archivos:

CREATE TABLE raw_files (
    id UUID PRIMARY KEY,
    load_id TEXT UNIQUE NOT NULL,
    source_id TEXT NOT NULL,
    file_name TEXT NOT NULL,
    file_type TEXT,
    file_size_bytes BIGINT,
    storage_path TEXT NOT NULL,
    uploaded_by TEXT,
    uploaded_at TIMESTAMP DEFAULT now(),
    checksum TEXT,
    status TEXT DEFAULT 'stored'
);

9. Ejemplo de RAW de venta

Registro original

{
  "fecha": "27/05/26",
  "cliente": "Constructora Norte",
  "producto": "Cem x50",
  "cantidad": "100",
  "precio": "$ 8.500",
  "descuento": "8%",
  "vendedor": "Juan P.",
  "sucursal": "SJ"
}

RAW guardado

{
  "load_id": "LOAD_2026_05_27_001",
  "source": "ventas_mayo.xlsx",
  "row_number": 128,
  "raw_payload": {
    "fecha": "27/05/26",
    "cliente": "Constructora Norte",
    "producto": "Cem x50",
    "cantidad": "100",
    "precio": "$ 8.500",
    "descuento": "8%",
    "vendedor": "Juan P.",
    "sucursal": "SJ"
  }
}

Dato normalizado posterior

{
  "fecha": "2026-05-27",
  "customer_id": "CLI_003",
  "product_id": "PROD_001",
  "cantidad": 100,
  "precio_unitario": 8500,
  "descuento": 0.08,
  "employee_id": "EMP_014",
  "branch_id": "SUC_SAN_JUAN"
}

10. Trazabilidad de punta a punta

La trazabilidad debe permitir seguir el dato desde el origen hasta la decisión.

Ejemplo:

Archivo original
→ RAW
→ Staging
→ Normalización
→ Tabla maestra
→ Fact table
→ KPI
→ Señal
→ Regla
→ Alerta
→ Tensión
→ Diagnóstico
→ Acción
→ Responsable
→ Seguimiento
→ FARO Score

Ejemplo aplicado:

ventas_mayo.xlsx fila 128
→ raw_imports LOAD_2026_05_27_001
→ staging_sales
→ fact_sales
→ KPI margen bruto
→ señal margen bajo
→ regla margen < 22%
→ alerta margen crítico
→ tensión crecimiento no rentable
→ acción auditar descuentos
→ responsable Gerente Comercial
→ seguimiento 72 horas
→ impacto en FARO Score

11. Tabla de linaje del dato

FARO debería tener una tabla de linaje.

CREATE TABLE data_lineage (
    id UUID PRIMARY KEY,
    raw_id UUID NOT NULL,
    staging_id UUID,
    normalized_id UUID,
    fact_table TEXT,
    fact_id UUID,
    kpi_code TEXT,
    signal_id UUID,
    alert_id UUID,
    tension_id UUID,
    action_id UUID,
    score_snapshot_id UUID,
    created_at TIMESTAMP DEFAULT now()
);

Esto permite responder preguntas como:

¿Qué datos alimentaron este KPI?
¿Qué carga generó esta alerta?
¿Qué regla disparó esta tensión?
¿Qué acción nació de este diagnóstico?
¿Qué registros afectaron el FARO Score?

12. Versionado de datos y reglas

No basta con guardar el dato. También hay que guardar con qué regla fue procesado.

Ejemplo:

Regla de margen v1:
margen crítico < 20%

Regla de margen v2:
margen crítico < 22%

Regla de margen v3:
margen crítico depende de industria y producto.

Si FARO recalcula el pasado, debe saber con qué versión lo hizo.

Modelo sugerido:

CREATE TABLE processing_rules_versions (
    id UUID PRIMARY KEY,
    rule_code TEXT NOT NULL,
    version TEXT NOT NULL,
    description TEXT,
    rule_definition JSONB,
    active_from TIMESTAMP,
    active_to TIMESTAMP,
    created_by TEXT,
    created_at TIMESTAMP DEFAULT now()
);

Ejemplo:

{
  "rule_code": "MARGIN_CRITICAL",
  "version": "v1.2",
  "definition": {
    "threshold": 0.22,
    "operator": "<",
    "industry": "construction_supplies"
  },
  "active_from": "2026-05-01"
}

13. Hash y control de integridad

Para evitar duplicados o detectar cambios, FARO puede generar un hash del registro o archivo.

Ejemplo:

import hashlib
import json

def generar_hash(payload):
    payload_ordenado = json.dumps(payload, sort_keys=True, ensure_ascii=False)
    return hashlib.sha256(payload_ordenado.encode("utf-8")).hexdigest()

Uso:

registro = {
    "fecha": "27/05/26",
    "cliente": "Constructora Norte",
    "producto": "Cem x50",
    "cantidad": "100"
}

checksum = generar_hash(registro)
print(checksum)

Esto permite detectar:

Duplicados.
Archivos modificados.
Cargas repetidas.
Cambios no autorizados.

14. Estados del dato RAW

15. Auditoría de cambios

FARO debe registrar cualquier modificación, reproceso o corrección.

Tabla sugerida:

CREATE TABLE audit_log (
    id UUID PRIMARY KEY,
    entity_type TEXT NOT NULL,
    entity_id UUID NOT NULL,
    action TEXT NOT NULL,
    previous_value JSONB,
    new_value JSONB,
    changed_by TEXT,
    changed_at TIMESTAMP DEFAULT now(),
    reason TEXT
);

Ejemplo:

{
  "entity_type": "normalized_product",
  "entity_id": "PROD_ALIAS_001",
  "action": "alias_updated",
  "previous_value": {
    "alias": "Cem x50",
    "product_id": null
  },
  "new_value": {
    "alias": "Cem x50",
    "product_id": "PROD_001"
  },
  "changed_by": "data_admin",
  "reason": "Normalización contra maestro de productos"
}

16. Ejemplo: auditoría de una alerta

Supongamos que FARO genera esta alerta:

Alerta: margen crítico en cemento bolsa 50kg.

FARO debe poder mostrar:

Eso es FARO serio. Lo demás es “confía en mí, bro”, pero con logo.

17. Trazabilidad de documentos

Para PDFs, facturas, presupuestos, remitos o contratos, FARO debe guardar:

Archivo original.
Texto extraído.
Campos detectados.
Confianza de extracción.
Usuario que validó.
Versión procesada.
Relación con proveedor / cliente / operación.

Ejemplo:

{
  "document_id": "DOC_001",
  "file_name": "factura_proveedor_123.pdf",
  "source": "mail_compras",
  "raw_storage_path": "s3://faro/raw/docs/factura_proveedor_123.pdf",
  "extracted_fields": {
    "proveedor": "Proveedor Norte SA",
    "fecha": "2026-05-27",
    "importe": 1250000,
    "producto": "Hierro 8mm"
  },
  "extraction_confidence": 0.87,
  "validated_by": "administracion"
}

18. Trazabilidad de WhatsApp o mensajes

Los mensajes pueden ser útiles, pero son peligrosos si se usan sin control.

FARO debe guardar:

Mensaje original.
Número o usuario.
Fecha y hora.
Canal.
Texto completo.
Extracción estructurada.
Confianza.
Validación humana si corresponde.

Ejemplo:

{
  "message_id": "MSG_001",
  "channel": "whatsapp",
  "from": "vendedor_juan",
  "received_at": "2026-05-27T10:32:00",
  "raw_text": "Necesito 100 bolsas de cemento para Obra Norte mañana",
  "extracted_data": {
    "cliente": "Obra Norte",
    "producto": "cemento",
    "cantidad": 100,
    "fecha_requerida": "2026-05-28"
  },
  "confidence": 0.78,
  "requires_validation": true
}

Regla sana:

Un WhatsApp puede iniciar un flujo, pero no debería generar una decisión crítica sin validación.

19. Trazabilidad de decisiones

No solo los datos operativos deben tener trazabilidad. Las decisiones también.

Cada decisión debe guardar:

Quién la tomó.
Cuándo.
Con qué información.
Qué diagnóstico la originó.
Qué tensión estaba relacionada.
Qué acción generó.
Qué KPI buscaba mejorar.
Qué resultado tuvo.

Modelo:

CREATE TABLE decision_log (
    id UUID PRIMARY KEY,
    decision_code TEXT,
    title TEXT,
    description TEXT,
    created_by TEXT,
    decided_by TEXT,
    decided_at TIMESTAMP,
    related_tension_id UUID,
    related_alert_id UUID,
    related_kpis JSONB,
    expected_impact JSONB,
    action_id UUID,
    result_status TEXT,
    created_at TIMESTAMP DEFAULT now()
);

Ejemplo:

{
  "decision_code": "DEC_2026_001",
  "title": "Limitar descuentos mayores al 8%",
  "decided_by": "Dirección",
  "related_tension": "crecimiento_no_rentable",
  "related_kpis": ["margen_bruto", "descuento_promedio"],
  "expected_impact": {
    "margen_bruto": "+3 puntos"
  },
  "action": "auditar_descuentos_altos",
  "result_status": "en_seguimiento"
}

20. Trazabilidad de FARO Score

El FARO Score no puede ser un número mágico.

Debe tener desglose.

Ejemplo:

{
  "score_snapshot_id": "SCORE_2026_05_27",
  "score": 72,
  "componentes": {
    "kpis": -10,
    "tensiones": -8,
    "alertas_vencidas": -4,
    "acciones_en_fecha": 6,
    "calidad_datos": -2
  },
  "principales_causas": [
    "margen_bruto_en_rojo",
    "crecimiento_no_rentable",
    "acciones_comerciales_vencidas"
  ]
}

FARO debe poder responder:

¿Por qué el score bajó?
¿Qué tensión lo afectó?
Qué KPI lo afectó?
Qué acción vencida lo afectó?
¿Qué área debe actuar?

21. Reprocesamiento desde RAW

Una de las grandes ventajas del RAW es poder reprocesar.

Ejemplo:

Antes:
Producto “Cem x50” no estaba vinculado al maestro.

Después:
Se vincula a CEMENTO_BOLSA_50KG.

Entonces:
FARO reprocesa ventas históricas afectadas.
Recalcula margen.
Recalcula tensiones.
Recalcula score.

Ejemplo conceptual:

def reprocesar_lote(load_id):
    raw_records = obtener_raw_por_lote(load_id)

    for raw in raw_records:
        staging = transformar_a_staging(raw)
        normalizado = normalizar(staging)
        integrar_modelo_ejecutivo(normalizado)

    recalcular_kpis(load_id)
    recalcular_alertas(load_id)
    recalcular_tensiones(load_id)

    return {
        "load_id": load_id,
        "status": "reprocessed"
    }

22. Retención de datos

FARO debe definir cuánto tiempo conserva cada tipo de dato.

La política exacta depende del país, industria y contrato. Pero como criterio, FARO debe estar preparado para retención larga y auditoría seria.

23. Seguridad del RAW

RAW puede contener información sensible.

Por eso debe protegerse.

Medidas recomendadas:

Control de acceso por rol.
Cifrado en reposo.
Cifrado en tránsito.
Logs de acceso.
Separación por empresa.
Separación por sucursal si corresponde.
Permisos por área.
Auditoría de descargas.
Anonimización cuando aplique.
Backups.
Política de retención.

Ejemplo de permisos:

24. Riesgos si no existe RAW y trazabilidad

25. Ejemplo completo: de venta a tensión

Dato original

Archivo: ventas_mayo.xlsx
Fila: 128
Producto: Cem x50
Cantidad: 100
Precio: $8.500
Descuento: 12%
Vendedor: Juan P.

RAW

Se guarda exactamente como llegó.

Staging

Precio = 8500
Descuento = 0.12
Cantidad = 100
Fecha normalizada

Normalización

Producto = CEMENTO_BOLSA_50KG
Vendedor = EMP_014
Sucursal = SUC_SAN_JUAN

Modelo ejecutivo

Venta neta.
Costo.
Margen.
Cliente.
Vendedor.
Sucursal.
Condición de cobro.

KPI

Margen bruto = 19%

Regla

Si margen < 22% y descuento > 10%, activar alerta.

Alerta

Margen crítico con descuento alto.

Tensión

Crecimiento no rentable.

Acción

Auditar operaciones con descuento superior al 8%.

Responsable

Gerente Comercial.

Trazabilidad

FARO puede mostrar toda la cadena desde la fila 128 del Excel hasta la acción generada.

26. Output final del Anexo 9

Al finalizar este anexo, FARO debe tener definido:

1. Modelo de almacenamiento RAW.
2. Metadata obligatoria por fuente.
3. Estructura de lotes de carga.
4. Tabla de eventos RAW.
5. Tabla de archivos RAW.
6. Tabla de linaje del dato.
7. Tabla de auditoría de cambios.
8. Versionado de reglas de procesamiento.
9. Hash de integridad.
10. Estados del dato RAW.
11. Política de reprocesamiento.
12. Política de retención.
13. Permisos de acceso al RAW.
14. Trazabilidad de KPIs.
15. Trazabilidad de alertas.
16. Trazabilidad de tensiones.
17. Trazabilidad de acciones.
18. Trazabilidad de FARO Score.

27. Conexión con otros anexos

RAW y trazabilidad son la columna vertebral de confianza de FARO Connect. Cada dato se guarda como llegó, con su origen, fecha, usuario, fuente, versión y estado. Desde ahí FARO puede reconstruir el camino completo: dato original, KPI, alerta, tensión, acción, seguimiento y FARO Score.