Data Design Standard

Estado: activo
Scope: global
tenant_id: global
Owner: OpenClaw Platform Governance
Fuente de verdad: docs/governance/standards/DATA-DESIGN-STANDARD.md

Objetivo

Definir la norma base para futuras tablas PostgreSQL derivadas de SGC y otras fuentes, de manera que sirvan al mismo tiempo para operacion, aplicaciones, alarmas, automatizaciones, analisis con Python, machine learning, LLM / IA, auditoria, trazabilidad y sincronizacion robusta.

Este estandar es global y aplica a dominios como Clientes, Productos, Ventas y futuras fuentes multi-tenant.

No crea tablas, no define migraciones y no reemplaza los contratos de cada tenant o fuente.

Regla madre

Toda tabla futura debe diseñarse no solo para guardar datos, sino para poder:

• identificar el registro con claridad
• preservar origen y trazabilidad
• auditar sincronizaciones y cambios
• sostener lectura operativa performante
• habilitar analitica futura sin remodelado destructivo
• conservar senales utiles para ML y LLM / IA

Regla de aplicabilidad

• no todos los campos de este estandar aplican a todas las tablas
• toda tabla debe justificar que campos usa y cuales no usa
• created_at y updated_at son obligatorios salvo excepcion documentada
• los datos del sistema origen no reemplazan timestamps internos
• fecha_alta_sgc no es igual a created_at
• fecha_modificacion_origen, si existe, debe guardarse aparte

Categorias de campos recomendados

1. Identidad

Campos recomendados:

• id interno
• tenant_id
• source_key o codigo_origen

Reglas:

• id interno sirve como identificador tecnico estable de la tabla destino
• tenant_id es obligatorio en tablas scope=tenant
• source_key o codigo_origen preserva la identidad funcional del origen
• cuando exista una clave logica fuerte, debe quedar explicitada y defendida por indices y validaciones

Aplicacion ya validada para APV / SOURCE-001:

• tenant_id + codigo_cliente queda documentado como clave logica fuerte
• codigo_cliente debe canonicalizarse como NULLIF(LTRIM(RTRIM([Codigo])), '')
• Telefono / WhatsApp no debe usarse como identificador unico

2. Trazabilidad

Campos recomendados:

• source_system
• source_object
• source_query_version
• sync_batch_id
• source_row_hash
• created_at
• updated_at
• extracted_at
• last_seen_at

Reglas:

• source_system identifica el sistema origen
• source_object identifica vista, tabla, archivo o endpoint origen
• source_query_version permite saber con que logica se extrajo el dato
• sync_batch_id permite auditar cada corrida de sync
• source_row_hash permite detectar cambios sin comparar campo por campo
• created_at y updated_at pertenecen a la fundacion de datos, no al origen
• extracted_at refleja cuando la fila fue leida desde origen
• last_seen_at refleja la ultima vez que la fila fue observada en una extraccion valida

3. Estado y vigencia

Campos recomendados:

• record_status
• is_current
• valid_from
• valid_to

Reglas:

• record_status debe separar estado funcional de estado tecnico
• is_current facilita lectura de la version vigente cuando existe historico
• valid_from y valid_to permiten trazabilidad temporal
• baja comercial, suspension o inactividad no equivalen a hard delete

4. Calidad de dato

Campos recomendados:

• data_quality_status
• validation_status
• validation_notes

Reglas:

• la calidad debe poder leerse fila a fila o por lote cuando haga falta
• validation_status debe distinguir validado, pendiente, observado o fallido
• validation_notes debe usarse para excepciones concretas, no como reemplazo de modelado

5. Preparacion analitica y IA

Campos recomendados:

• campos normalizados
• campos derivados
• features_json
• metadata_json

Reglas:

• distinguir dato raw, dato normalizado y dato derivado
• no perder senales comerciales importantes por simplificacion temprana
• features_json sirve para features flexibles de analitica y ML
• metadata_json sirve para metadata flexible no critica
• JSON no debe reemplazar columnas criticas, claves ni filtros principales

Criterio minimo por capa

Raw / staging

• preservar la mayor fidelidad posible al origen
• conservar valores raw relevantes como estado_raw o whatsapp_raw
• registrar extraccion, batch y hash cuando aplique

Core

• consolidar identidad, normalizacion y trazabilidad operativa
• exponer claves claras, timestamps internos y estado funcional consistente
• separar lo critico en columnas explicitas

Analytics

• derivar agregados, features, snapshots y lecturas de consumo
• no reemplazar la trazabilidad del core
• facilitar consultas de analisis sin destruir granularidad de origen

Reglas de performance

• definir claves claras desde el diseño
• indexar por tenant_id + clave logica cuando aplique
• indexar por source_row_hash cuando se use para deteccion de cambios
• indexar por last_seen_at cuando se use para auditoria o reconciliacion
• separar raw / staging, core y analytics
• evitar JSON como reemplazo de columnas criticas
• usar JSON solo para metadata flexible o features no criticas
• diseñar para lectura performante y analisis futuro, no solo para carga

Criterio para IA / ML

• preservar historico cuando el dato tenga valor de decision
• no hacer hard delete salvo excepcion documentada
• mantener cambios trazables
• facilitar construccion futura de features
• distinguir datos raw, normalizados y derivados
• evitar perder senales comerciales importantes

Regla sobre historico y borrado

• la desaparicion de un registro en una extraccion no equivale por defecto a eliminacion logica del dominio
• el hard delete debe ser excepcional y quedar documentado
• cuando un cambio sea importante para decision, auditoria o analitica, debe preservarse como historico, vigencia o snapshot

Checklist minimo por tabla futura

• identidad explicita
• tenant_id cuando aplique
• clave logica justificada
• created_at y updated_at presentes o excepcion documentada
• timestamps de origen diferenciados de timestamps internos
• estrategia de trazabilidad definida
• estrategia de estado y vigencia definida
• estrategia de calidad definida
• criterios de performance definidos
• decision explicita sobre historico, hard delete y uso de JSON

Relacion con otros contratos

• MULTI-TENANT-FOUNDATION.md define el aislamiento global y por tenant
• DATA-FOUNDATION.md define la arquitectura documental de la capa de datos
• los contratos por tenant y por fuente deben aplicar este estandar y justificar sus excepciones

Regla final

Ninguna tabla futura de la Data Foundation deberia considerarse bien diseñada si no puede explicar:

• cual es su identidad estable
• de que fuente viene
• cuando fue creada y actualizada internamente
• que lote la cargo
• como detecta cambios
• que historico preserva
• que senales deja disponibles para operacion, analitica y IA