Multitenancy Contract

Estado: contrato base

Fecha: 2026-05-05

Objetivo

OPS Center debe poder crecer como SaaS sin reescribir el producto cuando entren clientes externos. La regla principal es que toda funcionalidad nueva debe declarar desde el inicio si pertenece a plataforma, cuenta o workspace.

Capas

Capa	Tabla base	Propiedad	Uso
Plataforma	app_users, account_plans, ops_settings globales	Superadmin OPS	Operacion global, planes, salud, migraciones y soporte
Cuenta	accounts	Empresa cliente	Plan comercial, limites, billing futuro y conjunto de workspaces
Workspace	workspaces, workspace_members	Equipo operativo	Tareas, proyectos, agentes, credenciales, targets, skills, planes y colas
Usuario	app_users + membresias	Persona	Sesion, preferencias, tema, permisos por workspace

Regla De Aislamiento

Toda tabla con datos operativos debe incluir workspace_id y toda query de API debe filtrar por el workspace resuelto en la peticion.

El workspace se resuelve por este orden:

1. Header X-OPS-Workspace-Id.
2. workspace_id en query/body cuando el endpoint lo permite.
3. Workspace por defecto del usuario autenticado.
4. Workspace por defecto de plataforma solo para llamadas de servicio internas.

Un usuario solo puede operar workspaces donde tenga una membresia activa en workspace_members.

Datos Por Workspace

Estas entidades deben permanecer aisladas por workspace:

• tareas, historial, comentarios y tiempos
• departamentos y proyectos
• planes operativos y project plans
• workflows y task templates
• skills y perfiles de ejecucion
• credenciales de agentes
• deployment targets
• alertas, auditoria y readiness operacional

Si una entidad necesita compartirse entre workspaces, debe tener una decision explicita de producto y permisos de lectura separados. No se debe compartir por accidente mediante ausencia de filtro.

Datos Por Cuenta

La cuenta agrupa workspaces y limita uso:

• plan activo (plan_slug)
• maximo de usuarios
• maximo de workspaces
• estado activo/inactivo
• metadata comercial futura

Los planes actuales son solo, team, studio y custom. Por ahora no hay billing automatico; el plan funciona como contrato de limites.

Roles

Roles de plataforma:

• admin: puede administrar cuentas, usuarios, workspaces y configuracion global.
• operator: puede usar el sistema operativo donde tenga acceso.

Roles de workspace:

• owner: control total del workspace y miembros.
• admin: configuracion, miembros operativos, credenciales y deploy targets.
• operator: tareas, colas, ejecucion y uso diario.
• viewer: lectura.

La UI puede ocultar acciones, pero la autorizacion valida vive siempre en la API.

Credenciales Y Servidores

Las credenciales no deben exponerse al navegador despues de guardarse. La UI solo puede mostrar alias, proveedor, scope, estado, ultimo uso y fecha de expiracion.

Scopes permitidos:

• personal: pertenece a un usuario dentro de un workspace.
• workspace: disponible para automatizaciones del workspace.

Los deployment targets siempre pertenecen a un workspace y pueden referenciar una credencial del mismo workspace. No debe permitirse asociar una credencial de otro workspace.

Preferencias Y Temas

Las preferencias visuales deben resolverse por prioridad:

1. Preferencia del usuario.
2. Preferencia del workspace.
3. Tema por defecto de plataforma.
4. Fallback del producto.

Los componentes no deben depender de colores directos; deben leer tokens CSS. Esto permite cambiar tema sin duplicar pantallas.

Checklist Para Nuevas Funciones

Antes de cerrar una funcion nueva:

1. La entidad declara capa: plataforma, cuenta o workspace.
2. Las tablas operativas tienen workspace_id.
3. Los endpoints usan requireWorkspaceRole o una autorizacion equivalente.
4. Las queries filtran por workspace_id.
5. Las relaciones cruzadas validan que ambas entidades pertenecen al mismo workspace.
6. Los secrets no vuelven al cliente.
7. Existe auditoria para acciones sensibles.
8. El smoke SaaS sigue pasando.

Smoke Obligatorio

npm run smoke:saas debe validar:

• creacion de cuenta y workspace temporal
• owner/admin asignado
• invitacion aceptada por usuario nuevo
• visibilidad limitada al workspace asignado
• rechazo al workspace ajeno
• creacion de tarea en workspace propio
• ausencia de esa tarea en el workspace ajeno
• ocultacion de detalle de tarea si se consulta desde otro workspace
• readiness SaaS del tenant

Decision De Arquitectura

La primera version SaaS usa una sola base de datos PostgreSQL con aislamiento por account_id y workspace_id.

No se adopta base de datos por cliente en esta fase porque aumentaria coste operativo y ralentizaria el desarrollo inicial. Si un cliente exige aislamiento fisico o requisitos regulatorios, el contrato actual permite evolucionar a esquemas o bases separadas manteniendo las mismas capas logicas.