Saltar a contenido

Multi-Tenant Foundation

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

Objetivo

Definir la base contractual para operar multiples empresas en una sola plataforma OpenClaw sin mezclar datos, credenciales, workflows, dashboards, APIs ni documentacion.

Esta etapa crea reglas y estructura documental. No implementa APIs, dashboards, agentes, bases nuevas ni cambios de infraestructura productiva.

Regla madre

Todo elemento nuevo debe declarar explicitamente:

  • scope: global o tenant
  • tenant_id: null, global, alpuntodeventa, ladirecta o identificador futuro aprobado
  • owner
  • estado
  • fuente_de_verdad

Definiciones base

Que es un tenant

Un tenant es una empresa o unidad operativa aislada logicamente dentro de la plataforma. En esta foundation los tenants iniciales aprobados son:

  • alpuntodeventa
  • ladirecta

Todo tenant futuro debe tener identificador estable, ficha documental propia y reglas de acceso separadas antes de recibir datos o automatizaciones.

Que es global

Un activo global pertenece a la plataforma compartida y no a una empresa particular.

Ejemplos:

  • VPS
  • Docker
  • Nginx Proxy Manager
  • Portainer
  • observabilidad tecnica
  • portal documental
  • governance

Que es compartido

Compartido es todo activo reutilizado por varios tenants pero gobernado como scope=global.

Ejemplos:

  • runtime de OpenClaw
  • Knowledge Portal
  • Grafana tecnico
  • Git Sync
  • runbooks operativos

Compartido no significa mezcla libre de datos. Significa infraestructura comun con controles de separacion aguas arriba y aguas abajo.

Que es privado por tenant

Privado por tenant es cualquier activo, dato o configuracion cuyo uso, visibilidad o efecto deba limitarse a una empresa especifica.

Ejemplos futuros:

  • credenciales de integracion
  • workflows comerciales
  • dashboards de negocio
  • APIs del tenant
  • agentes del tenant
  • datasets operativos del tenant

Reglas de tenant_id

  • tenant_id=global se usa para activos compartidos de plataforma.
  • tenant_id=null solo se permite en plantillas o contratos abstractos.
  • tenant_id=alpuntodeventa y tenant_id=ladirecta identifican tenants iniciales aprobados.
  • Todo tenant futuro debe usar un slug estable en minusculas y sin espacios.
  • Ningun activo con scope=tenant puede omitir tenant_id.
  • Ningun dato productivo multi-tenant puede crearse con tenant_id ambiguo.

Reglas de scope

  • scope=global para activos de plataforma, gobierno y operaciones comunes.
  • scope=tenant para activos con dueño, permisos o datos de una sola empresa.
  • Si existe duda, el activo se clasifica como tenant hasta justificar por que debe ser global.
  • Un activo global no puede exponer datos de tenant sin filtro explicito por tenant_id.

Reglas de owner

  • Todo activo debe tener owner humano o owner de equipo claramente nombrado.
  • El owner responde por exactitud documental, permisos, ciclo de vida y aprobacion de cambios.
  • Si un activo afecta mas de un tenant, el owner global coordina cambios y deja trazabilidad.
  • No se aceptan activos sin owner definido.

Reglas de separacion de datos

  • Ningun dataset de un tenant puede mezclarse con otro sin campo tenant_id.
  • Ninguna consulta, exportacion o vista futura puede omitir filtro por tenant_id cuando el activo sea scope=tenant.
  • Toda integracion futura debe documentar origen, destino y nivel de aislamiento.
  • La observabilidad tecnica sigue separada de los futuros datos de negocio.
  • La base documental debe distinguir siempre entre contenido global y contenido de tenant.

Reglas de credenciales

  • No se guardan secretos reales en docs/.
  • Toda credencial futura debe declararse como scope=global o scope=tenant.
  • Las credenciales de tenant no pueden reutilizarse implicitamente en otro tenant.
  • Toda referencia documental a credenciales debe indicar owner, uso y ubicacion segura, sin exponer el valor.
  • Un workflow o agente solo puede usar credenciales compatibles con su alcance.

Reglas de workflows

  • Todo workflow futuro debe declarar scope, tenant_id, owner, entradas, salidas y credenciales usadas.
  • Un workflow de tenant no puede leer ni escribir datos de otro tenant.
  • Un workflow global solo puede operar sobre multiples tenants si la accion y el permiso quedan documentados explicitamente.

Reglas de agentes

  • No se crean agentes en esta etapa.
  • Todo agente futuro debe declararse como global o tenant.
  • Un agente de tenant no puede acceder a conocimiento, credenciales o acciones de otro tenant.
  • Un agente global debe justificar por que necesita visibilidad cross-tenant.

Reglas de dashboards

  • No se crean dashboards de negocio en esta etapa.
  • Todo dashboard futuro debe declarar scope, tenant_id, owner, datasource y permisos.
  • Los dashboards tecnicos siguen siendo globales salvo aprobacion explicita en contrario.
  • Los dashboards de negocio deben nacer de fuentes de negocio, no de Prometheus.

Reglas de APIs

  • No se crean APIs en esta etapa.
  • Toda API futura debe declarar scope, tenant_id, OpenAPI, permisos, owner y fuente de verdad.
  • Ninguna API multi-tenant puede quedar sin contrato de filtrado por tenant_id.
  • Todo endpoint cross-tenant requiere justificacion formal de gobierno.

Reglas de documentacion

  • Toda documentacion nueva debe indicar alcance y owner.
  • Los documentos globales viven en rutas globales.
  • Los documentos por tenant viven bajo docs/tenants/<tenant_id>/.
  • Toda plantilla o ejemplo debe evitar secretos, datos sensibles y accesos reales.
  • Cuando un activo impacta a un tenant especifico, su ficha debe enlazar al TENANT.md correspondiente.

Modelo estructural

flowchart TD
    platform[Global Platform<br/>scope=global<br/>tenant_id=global]
    apv[alpuntodeventa<br/>scope=tenant]
    ld[ladirecta<br/>scope=tenant]

    platform --> apv
    platform --> ld
flowchart TD
    tenant[Tenant]
    data[Datos]
    api[APIs]
    dashboards[Dashboards]
    agents[Agentes]

    tenant --> data
    data --> api
    api --> dashboards
    dashboards --> agents

Criterio de crecimiento

  • primero se documenta el tenant
  • despues se aprueban datos e integraciones
  • despues se aprueban APIs
  • despues se aprueban dashboards
  • despues se aprueban agentes

Ninguna capa futura puede saltarse las declaraciones obligatorias de alcance, owner y fuente de verdad.