Data Foundation

Estado: VERDE DOCUMENTAL
Scope: global
tenant_id: global
Owner: OpenClaw Platform Governance
Fuente de verdad: docs/architecture/DATA-FOUNDATION.md

Objetivo

Definir la base oficial de datos multi-tenant de la future platform para que las capas futuras de API Platform, dashboards, alertas y agentes trabajen sobre datos aislados por tenant, auditables y preparados para evolucionar sin mezclar empresas.

Esta etapa no crea bases nuevas, no instala PostgreSQL, no modifica produccion, no expone APIs y no crea dashboards ni agentes nuevos.

Relacion con la arquitectura vigente

• la infraestructura actual sigue cerrada y operativa
• la Multi-Tenant Foundation sigue siendo el contrato de alcance y aislamiento
• la Data Foundation queda definida como capa documental futura
• PostgreSQL sigue siendo tecnologia objetivo, no realidad implementada
• existe una apertura controlada de sandbox en infra/data-foundation/postgres-sandbox/, separada de cualquier uso productivo
• sobre esa base existe tambien un PostgREST sandbox interno en infra/data-foundation/postgrest-sandbox/, solo de lectura, con JWT sandbox, scope enforcement por recurso y sin exposicion publica

Alcance de la capa de datos

La Data Foundation debe servir para:

• persistir datos estructurados globales y por tenant
• conservar trazabilidad de origen, cambios y consumo
• separar datos tecnicos de datos de negocio
• alimentar futuras APIs, dashboards, alertas y agentes
• habilitar controles de seguridad por tenant_id

La Data Foundation no debe usarse para:

• reemplazar la observabilidad tecnica actual
• mezclar tenants por conveniencia operativa
• guardar secretos en tablas de negocio
• introducir integraciones runtime sin documentacion previa

Modelo de alcance de datos

Datos globales

Son datos compartidos de plataforma cuyo owner es global y que no pertenecen a una empresa particular.

Ejemplos:

• catalogo de tenants aprobados
• metadata de fuentes de datos
• catalogo de integraciones aprobadas
• definiciones globales de dominios y contratos
• auditoria global de procesos cross-tenant autorizados

Datos por tenant

Son datos cuyo contenido, visibilidad o efecto corresponde a una sola empresa.

Ejemplos:

• clientes
• potenciales clientes
• productos
• SKU
• marcas
• categorias
• pedidos
• ventas
• canales
• proveedores
• finanzas
• capital por marca
• alertas de negocio
• workflows del tenant
• agentes del tenant
• configuraciones de integracion del tenant

Datos que nunca deben mezclarse

Las siguientes categorias no deben mezclarse entre tenants en consultas, vistas, exports, APIs, dashboards, alertas o agentes salvo aprobacion global formal y trazable:

• identificadores de clientes
• catalogos comerciales del tenant
• pedidos y ventas
• datos financieros
• credenciales o referencias operativas sensibles
• logs funcionales de workflows y agentes
• alertas de negocio
• configuraciones de integraciones propias del tenant

Identidad del tenant

Todo dato futuro scope=tenant debe declarar:

• tenant_id
• scope
• source_system
• owner

Reglas:

• tenant_id=global solo para datos globales de plataforma
• tenant_id obligatorio para todo dato de tenant
• el valor debe ser un slug estable, en minusculas y sin espacios
• tenants iniciales aprobados:
• alpuntodeventa
• ladirecta
• no se permiten registros productivos con tenant_id ambiguo, vacio o derivado implicitamente

Estrategia multi-tenant de datos

Opcion 1 - Tablas compartidas con tenant_id

Modelo:

• una misma tabla fisica contiene datos de multiples tenants
• cada fila declara tenant_id obligatorio
• el filtrado y la seguridad se apoyan en claves, indices, vistas y RLS

Ventajas:

• modelo simple para arrancar
• menor complejidad operativa inicial
• facilita dominios globales y cross-tenant autorizados
• favorece estandares comunes de auditoria y APIs

Riesgos:

• requiere disciplina estricta de filtrado
• cualquier omision de tenant_id puede abrir mezcla accidental
• demanda controles de seguridad y revisiones de consultas

Opcion 2 - Schema por tenant

Modelo:

• cada tenant tiene su propio schema
• las tablas se replican por tenant

Ventajas:

• separacion logica mas visible
• menos riesgo de consultas sin filtro por fila

Riesgos:

• mas complejidad en migraciones y versionado
• catalogos y dominios globales se vuelven mas incomodos
• crecimiento operacional mas costoso si aumentan tenants

Opcion 3 - Base separada por tenant

Modelo:

• cada tenant vive en una base distinta

Ventajas:

• aislamiento fuerte a nivel fisico
• blast radius mas acotado por tenant

Riesgos:

• mayor costo operativo y administrativo
• mas complejidad para reporting global autorizado
• mas friccion para APIs, dashboards y automatizaciones comunes

Recomendacion inicial

La opcion inicial recomendada es:

• tablas compartidas con tenant_id obligatorio

Motivos:

• coincide con la preferencia ya sugerida para esta etapa
• respeta la Multi-Tenant Foundation sin inventar infraestructura adicional
• prepara el camino para Row Level Security futuro en PostgreSQL
• permite combinar datos globales y datos de tenant bajo un contrato uniforme

Condiciones obligatorias de esta recomendacion:

• tenant_id no nulo en toda tabla multi-tenant
• indices compuestos que incluyan tenant_id cuando corresponda
• Row Level Security futuro antes de exponer APIs o dashboards multi-tenant
• auditoria de lectura y escritura en capas de consumo autorizadas

Campos obligatorios para tablas multi-tenant futuras

Toda tabla multi-tenant futura debe incluir como minimo:

• tenant_id
• source_system
• created_at
• updated_at
• created_by
• updated_by
• record_status
• external_id si aplica
• sync_batch_id si aplica

Significado de los campos obligatorios

• tenant_id: identifica a que tenant pertenece el registro
• source_system: sistema origen del dato, por ejemplo woocommerce, sgc_erp, openclaw, import_file
• created_at: fecha y hora de creacion del registro en la fundacion
• updated_at: fecha y hora de la ultima mutacion conocida
• created_by: actor, proceso o integracion que creo el registro
• updated_by: actor, proceso o integracion que actualizo el registro
• record_status: estado funcional del registro, por ejemplo active, inactive, deleted, draft
• external_id: identificador del sistema origen cuando exista
• sync_batch_id: corrida de sincronizacion o importacion cuando aplique

Ejemplo conceptual de tabla

sql create table sales_orders ( id bigserial primary key, tenant_id text not null, source_system text not null, external_id text, sync_batch_id text, created_at timestamptz not null default now(), updated_at timestamptz not null default now(), created_by text not null, updated_by text not null, record_status text not null default 'active', total_amount numeric(14,2) not null );

Auditoria del dato

Todo dato futuro debe poder responder:

• de que sistema vino
• a que tenant pertenece
• cuando se creo
• cuando cambio
• quien o que proceso lo cambio
• en que corrida o sync ingreso si aplica
• que estado funcional tiene

Lineamientos:

• la auditoria no reemplaza logs tecnicos actuales; los complementa
• lectura y escritura futuras deben dejar trazabilidad cuando el riesgo lo justifique
• las capas consumidoras no deben perder tenant_id ni source_system

Preparacion para capas futuras

APIs

La Data Foundation debe dejar datos listos para:

• filtros obligatorios por tenant_id
• contratos OpenAPI con alcance global o tenant
• exposicion controlada por permisos y auditoria
• uso futuro con PostgREST

Dashboards

La Data Foundation debe dejar datos listos para:

• dashboards globales autorizados
• dashboards por tenant sin mezcla de empresas
• metricas de negocio separadas de metricas tecnicas
• modelos consistentes para Grafana multi-tenant futuro

Alertas

La Data Foundation debe dejar datos listos para:

• alertas de negocio por tenant_id
• reglas sobre pedidos, ventas, stock o finanzas
• trazabilidad entre regla, dato fuente y tenant afectado

Agentes

La Data Foundation debe dejar datos listos para:

• agentes globales con permisos justificados
• agentes por tenant sin acceso cruzado
• contexto estable y auditado para consultas y acciones futuras

Catalogo inicial de dominios

Clientes

• proposito: registrar clientes finales o cuentas comerciales
• alcance: tenant
• relacion: se conecta con Potenciales clientes, Pedidos, Ventas y Canales
• fuente posible: WooCommerce, SGC / ERP, archivos importados
• uso futuro en APIs: consulta y actualizacion de clientes por tenant
• uso futuro en dashboards: cartera, recurrencia, ticket y segmentos
• uso futuro en agentes: seguimiento comercial y asistencia operativa

Potenciales clientes

• proposito: registrar prospectos y oportunidades comerciales
• alcance: tenant
• relacion: se conecta con Clientes, Canales, Workflows y Agentes
• fuente posible: OpenClaw, formularios, archivos importados, APIs externas
• uso futuro en APIs: captura y seguimiento de leads
• uso futuro en dashboards: embudo comercial y conversion
• uso futuro en agentes: priorizacion y contacto asistido

Productos

• proposito: representar productos comercializables
• alcance: tenant
• relacion: se conecta con SKU, Marcas, Categorias, Pedidos y Ventas
• fuente posible: WooCommerce, SGC / ERP, archivos importados
• uso futuro en APIs: catalogo de productos y consulta operativa
• uso futuro en dashboards: mix, rotacion y rentabilidad
• uso futuro en agentes: recomendacion y soporte comercial

SKU

• proposito: identificar variantes operativas y de stock
• alcance: tenant
• relacion: se conecta con Productos, Marcas, Categorias y Ventas
• fuente posible: WooCommerce, SGC / ERP, archivos importados
• uso futuro en APIs: lookup por SKU y sincronizacion de catalogo
• uso futuro en dashboards: rendimiento por variante
• uso futuro en agentes: respuestas de stock y catalogo

Marcas

• proposito: organizar productos por marca comercial
• alcance: tenant
• relacion: se conecta con Productos, SKU, Capital por marca y Finanzas
• fuente posible: SGC / ERP, archivos importados
• uso futuro en APIs: catalogo de marcas y asignaciones
• uso futuro en dashboards: performance y capital comprometido por marca
• uso futuro en agentes: seguimiento de foco comercial y reposicion

Categorias

• proposito: clasificar productos para analitica y operacion
• alcance: tenant
• relacion: se conecta con Productos, SKU y Ventas
• fuente posible: WooCommerce, SGC / ERP, archivos importados
• uso futuro en APIs: navegacion de catalogo y filtros
• uso futuro en dashboards: ventas y rotacion por categoria
• uso futuro en agentes: recomendaciones y deteccion de gaps

Pedidos

• proposito: registrar ordenes operativas del negocio
• alcance: tenant
• relacion: se conecta con Clientes, Productos, SKU, Canales y Ventas
• fuente posible: WooCommerce, SGC / ERP, APIs externas
• uso futuro en APIs: consulta y seguimiento de pedidos
• uso futuro en dashboards: pedidos abiertos, tiempos y cumplimiento
• uso futuro en agentes: atencion operativa y alertas

Ventas

• proposito: consolidar hechos comerciales cerrados
• alcance: tenant
• relacion: se conecta con Pedidos, Clientes, Productos, Canales y Finanzas
• fuente posible: WooCommerce, SGC / ERP, futuro PostgreSQL
• uso futuro en APIs: reportes y consulta transaccional
• uso futuro en dashboards: ventas, margen y tendencia
• uso futuro en agentes: analisis comercial y deteccion de desvios

Canales

• proposito: identificar origen comercial o ruta de venta
• alcance: tenant
• relacion: se conecta con Potenciales clientes, Pedidos y Ventas
• fuente posible: WooCommerce, SGC / ERP, archivos importados
• uso futuro en APIs: catalogo de canales y filtros
• uso futuro en dashboards: performance por canal
• uso futuro en agentes: optimizacion comercial por origen

Proveedores

• proposito: registrar proveedores y abastecimiento
• alcance: tenant
• relacion: se conecta con Productos, Marcas, Finanzas y Workflows
• fuente posible: SGC / ERP, archivos importados, APIs externas
• uso futuro en APIs: consulta operativa de proveedor
• uso futuro en dashboards: dependencia, abastecimiento y condiciones
• uso futuro en agentes: seguimiento de compras y reposicion

Finanzas

• proposito: consolidar movimientos, saldos o indicadores economicos
• alcance: tenant
• relacion: se conecta con Ventas, Proveedores y Capital por marca
• fuente posible: SGC / ERP, archivos importados, APIs externas
• uso futuro en APIs: reportes financieros por tenant
• uso futuro en dashboards: flujo, margen y situacion financiera
• uso futuro en agentes: alertas de desvio y analisis financiero

Capital por marca

• proposito: medir capital comprometido o asignado por marca
• alcance: tenant
• relacion: se conecta con Marcas, Finanzas, Productos y SKU
• fuente posible: SGC / ERP, archivos importados
• uso futuro en APIs: consulta especializada de capital por marca
• uso futuro en dashboards: capital inmovilizado y rentabilidad asociada
• uso futuro en agentes: alertas de concentracion y reposicion

Alertas

• proposito: representar eventos de negocio relevantes por tenant
• alcance: tenant
• relacion: se conecta con Pedidos, Ventas, Finanzas, Workflows y Agentes
• fuente posible: futuro PostgreSQL, OpenClaw, APIs externas
• uso futuro en APIs: consulta y acknowledge de alertas
• uso futuro en dashboards: tablero de alertas por tenant
• uso futuro en agentes: disparo de acciones o seguimiento asistido

Workflows

• proposito: registrar automatizaciones funcionales y sus ejecuciones
• alcance: tenant o global segun el caso
• relacion: se conecta con Alertas, Agentes e Integraciones
• fuente posible: OpenClaw, futuro PostgreSQL
• uso futuro en APIs: catalogo y estado de workflows
• uso futuro en dashboards: corridas, fallas y throughput
• uso futuro en agentes: coordinacion de tareas auditadas

Agentes

• proposito: representar agentes, sesiones o capacidades auditables
• alcance: tenant o global segun el caso
• relacion: se conecta con Workflows, Alertas e Integraciones
• fuente posible: OpenClaw, futuro PostgreSQL
• uso futuro en APIs: inventario y estado de agentes
• uso futuro en dashboards: actividad y rendimiento por tenant
• uso futuro en agentes: autoobservacion y coordinacion futura

Integraciones

• proposito: catalogar conexiones entre sistemas origen y la plataforma
• alcance: global o tenant segun ownership
• relacion: se conecta con todos los dominios que reciben o emiten datos
• fuente posible: WooCommerce, SGC / ERP, OpenClaw, APIs externas, archivos importados
• uso futuro en APIs: inventario y estado de integraciones
• uso futuro en dashboards: salud de syncs y cobertura de fuentes
• uso futuro en agentes: diagnostico y remediacion guiada

Fuentes de datos

Realidad actual comprobada

• OpenClaw existe hoy como runtime operativo y fuente potencial futura de workflows, agentes y logs funcionales, pero no hay Data Foundation implementada todavia
• Prometheus, Thanos y Grafana existen hoy para observabilidad tecnica
• el portal documental y la governance existen hoy como autoridad de contexto
• no existe PostgreSQL real implementado en el VPS para esta capa

Futuro previsto

• WooCommerce como fuente operativa por tenant para catalogo, pedidos y ventas
• SGC / ERP como fuente operativa por tenant para catalogo, stock, finanzas y proveedores
• PostgreSQL como tecnologia objetivo de persistencia
• OpenClaw como productor y consumidor de datos funcionales gobernados
• archivos importados como mecanismo controlado de carga inicial o contingencia
• APIs externas como complemento de integraciones por tenant

Pendiente de validar

• detalle exacto de los datos disponibles en cada WooCommerce
• detalle exacto del modelo real de SGC / ERP
• estrategia final de sync incremental por fuente
• estructura fisica final de PostgreSQL
• granularidad final de datos de OpenClaw a persistir
• si Grafana consumira directo de PostgreSQL, vistas o una capa adicional

Inventario por fuente

WooCommerce

• realidad actual comprobada: nombrado como fuente futura del tenant; no hay sync implementado en esta etapa
• futuro previsto: clientes, productos, categorias, pedidos y ventas
• pendiente de validar: alcance exacto de campos, frecuencia de sync y tenants habilitados

SGC / ERP

• realidad actual comprobada: nombrado como fuente futura del tenant; no hay conexion implementada en esta etapa
• futuro previsto: productos, SKU, proveedores, finanzas y capital por marca
• pendiente de validar: modelo real, metodos de acceso y ownership operativo

OpenClaw

• realidad actual comprobada: runtime activo en produccion, documentado en governance y knowledge platform
• futuro previsto: workflows, agentes, alertas funcionales y metadata de uso
• pendiente de validar: que subset funcional ira a la fundacion de datos

PostgreSQL futuro

• realidad actual comprobada: no implementado hoy
• futuro previsto: capa principal de persistencia multi-tenant
• pendiente de validar: modelo fisico, sizing, backup y seguridad final

Prometheus / Thanos

• realidad actual comprobada: stack tecnico activo para observabilidad
• futuro previsto: seguir como capa tecnica separada
• pendiente de validar: ningun uso como fuente principal de negocio

Grafana

• realidad actual comprobada: dashboards tecnicos publicados y activos
• futuro previsto: consumir datos de negocio multi-tenant en etapas futuras
• pendiente de validar: estrategia exacta de datasource para negocio

Archivos importados

• realidad actual comprobada: no hay pipeline formal implementado en esta etapa
• futuro previsto: carga controlada y auditada con sync_batch_id
• pendiente de validar: formatos, validaciones y ownership de importacion

APIs externas

• realidad actual comprobada: sin capa de integracion documental cerrada todavia
• futuro previsto: enriquecimiento y sincronizacion por tenant
• pendiente de validar: contratos, limites, permisos y estrategia de auditoria

Data lineage objetivo

Flujo comercial base

flowchart TD
    woocommerce[WooCommerce]
    foundation[Data Foundation]
    api[API Platform]
    grafana[Grafana]
    agents[Agentes]

    woocommerce --> foundation
    foundation --> api
    foundation --> grafana
    foundation --> agents
    api --> grafana
    api --> agents

Flujo ERP y conocimiento

flowchart TD
    erp[SGC / ERP]
    foundation[Data Foundation]
    knowledge[Business Knowledge Platform]
    dashboards[Business Dashboards]

    erp --> foundation
    foundation --> knowledge
    knowledge --> dashboards

Flujo de integraciones y alertas

flowchart TD
    imports[Archivos importados y APIs externas]
    foundation[Data Foundation]
    alerts[Alertas Multi-Tenant]
    openclaw[OpenClaw Multi-Tenant]

    imports --> foundation
    foundation --> alerts
    foundation --> openclaw

Seguridad y permisos

Reglas rectoras:

• tenant_id obligatorio en toda tabla multi-tenant
• Row Level Security futuro en PostgreSQL
• separacion de credenciales por tenant
• no acceso cruzado entre tenants
• auditoria de lectura y escritura
• principio de minimo permiso

Lineamientos:

• los datos globales no habilitan lectura libre de datos de tenant
• toda credencial futura debe quedar clasificada como global o tenant
• una API, dashboard o agente no debe inferir tenant por default si el contrato exige declararlo
• los procesos cross-tenant deben ser excepcionales, aprobados y trazables

Integracion futura por etapas

ETAPA 15 - API Platform

La Data Foundation provee la estructura base para filtrar por tenant_id, definir vistas seguras y exponer contratos auditables.

ETAPA 16 - API Documentation

La Data Foundation fija nombres, dominios, campos minimos y fuentes para que los contratos OpenAPI no nazcan ambiguos.

ETAPA 12 - Grafana Multi-Tenant

La Data Foundation separa los datos de negocio que Grafana debera consumir sin mezclar tenants ni depender de Prometheus como fuente principal.

ETAPA 13 - OpenClaw Multi-Tenant

La Data Foundation ofrece el soporte para que workflows, agentes y logs funcionales se filtren por tenant_id.

ETAPA 17 - Alertas Multi-Tenant

La Data Foundation entrega hechos de negocio auditables para disparar alertas por tenant.

ETAPA 18 - Business Knowledge Platform

La Data Foundation alimenta entidades y relaciones de negocio con trazabilidad de fuente y ownership.

ETAPA 19 - Business Dashboards

La Data Foundation consolida la base transaccional y analitica para tableros de negocio por tenant y lecturas globales autorizadas.

ETAPA 20 - Agents Layer

La Data Foundation provee contexto estructurado, aislado y auditable para agentes globales y agentes por tenant.

Decisiones ya tomadas

• esta etapa es solo documental y arquitectonica
• PostgreSQL sigue siendo la tecnologia objetivo recomendada
• la opcion inicial recomendada es tablas compartidas con tenant_id obligatorio
• la seguridad futura debe usar Row Level Security
• los datos de negocio deben permanecer separados de la observabilidad tecnica
• toda capa consumidora futura debe conservar tenant_id, source_system y trazabilidad minima

Decisiones pendientes

• apertura formal de implementacion de PostgreSQL
• evolucion del sandbox privado a runtime validado en VPS sin perder aislamiento ni no exposicion
• diseno fisico final de tablas, indices y particiones
• politica final de lectura global autorizada
• estrategia final de sync por fuente
• owners humanos finales por tenant
• contratos finales de APIs, dashboards, alertas y agentes

Regla final

Ninguna implementacion futura de datos se considera aprobada si no respeta al mismo tiempo:

• MULTI-TENANT-FOUNDATION.md
• este documento
• el estandar documental multi-tenant
• la separacion entre realidad actual y futuro previsto