betting-analytics/docs/02-definicion-modulos/BA-007-TENANTS.md

id	title	type	epic	status	project	version	created_date	updated_date
BA-007-TENANTS	BA-007: Modulo de Tenants	Module Definition	BA-007	Draft	betting-analytics	1.0.0	2026-01-04	2026-01-04

BA-007: Modulo de Tenants

Version: 1.0.0 Fecha: 2026-01-04 Estado: Definicion Prioridad: Alta

---

Descripcion General

El modulo de Tenants proporciona la arquitectura multi-tenant que permite aislar datos y configuraciones entre diferentes organizaciones que utilicen la plataforma de Betting Analytics como SaaS.

---

Objetivos

1. Aislar completamente los datos entre tenants
2. Permitir configuracion personalizada por tenant
3. Gestionar limites y cuotas segun plan
4. Preparar arquitectura para comercializacion SaaS

---

Entidades del Dominio

Tenant

Entidad: Tenant
Descripcion: Organizacion que utiliza la plataforma
Atributos:
  - id: UUID (PK)
  - name: string
  - slug: string (unico, URL-friendly)
  - status: enum [active, suspended, trial, cancelled]
  - plan_id: UUID (FK a Plan)
  - settings: JSONB
  - limits: JSONB
  - created_at: timestamp
  - updated_at: timestamp
  - deleted_at: timestamp (soft delete)

Relaciones:
  - 1:N con User
  - 1:N con Prediction
  - 1:N con Model
  - N:1 con Plan

Plan

Entidad: Plan
Descripcion: Plan de suscripcion con limites
Atributos:
  - id: UUID (PK)
  - name: string (Free, Pro, Enterprise)
  - code: string
  - features: JSONB
  - limits: JSONB
    - predictions_per_month: number
    - models_max: number
    - history_days: number
    - users_max: number
  - price_monthly: decimal
  - price_yearly: decimal
  - is_active: boolean
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - 1:N con Tenant

---

Funcionalidades

F-007.1: Gestion de Tenants

ID	Funcionalidad	Descripcion	Prioridad
F-007.1.1	Crear tenant	Registro de nueva organizacion	Alta
F-007.1.2	Editar tenant	Modificar datos y configuracion	Alta
F-007.1.3	Suspender tenant	Desactivar acceso temporalmente	Media
F-007.1.4	Eliminar tenant	Soft delete con retencion	Baja

F-007.2: Aislamiento de Datos

ID	Funcionalidad	Descripcion	Prioridad
F-007.2.1	RLS PostgreSQL	Row-Level Security por tenant_id	Alta
F-007.2.2	Middleware	Inyeccion automatica de tenant_id	Alta
F-007.2.3	Query scoping	Filtrado automatico en queries	Alta

---

Reglas de Negocio

RN-007.1:
  Descripcion: Todo tenant debe tener un plan asignado
  Default: Plan "Free"

RN-007.2:
  Descripcion: El slug del tenant debe ser unico
  Validacion: Regex ^[a-z0-9-]+$

RN-007.3:
  Descripcion: Tenant suspendido no permite login
  Accion: Validar status en middleware

RN-007.4:
  Descripcion: Soft delete conserva datos 90 dias

---

API Endpoints

Base: /api/v1/tenants

Endpoints:
  POST /tenants:
    Descripcion: Crear tenant (Super Admin)
    Body: { name, slug, plan_id }
    Response: 201 Created

  GET /tenants:
    Descripcion: Listar tenants (Super Admin)
    Response: 200 OK (paginado)

  GET /tenants/:id:
    Descripcion: Obtener tenant por ID
    Response: 200 OK

  PUT /tenants/:id:
    Descripcion: Actualizar tenant
    Response: 200 OK

  PATCH /tenants/:id/status:
    Descripcion: Cambiar estado
    Body: { status }
    Response: 200 OK

  GET /tenants/current:
    Descripcion: Tenant del usuario actual
    Response: 200 OK

---

Consideraciones Tecnicas

Estrategia Multi-Tenant

Tipo: Single Database, Shared Schema
Aislamiento: Row-Level Security (RLS) PostgreSQL

Implementacion:
  1. Columna tenant_id en tablas principales
  2. Politicas RLS que filtran por tenant_id
  3. Middleware que extrae tenant del JWT
  4. SET app.current_tenant antes de queries

Ejemplo RLS

CREATE POLICY tenant_isolation ON predictions
  USING (tenant_id = current_setting('app.current_tenant')::uuid);

ALTER TABLE predictions ENABLE ROW LEVEL SECURITY;

---

Dependencias

Dependencias:
  - BA-001 (auth): Autenticacion de usuarios
  - BA-008 (payments): Gestion de planes/suscripciones

Catalogos:
  - shared/catalog/multi-tenancy/

---

Criterios de Aceptacion

• Tenant puede ser creado con datos minimos
• RLS impide acceso a datos de otros tenants
• Limites del plan se validan antes de operaciones
• Soft delete funciona correctamente
• API responde correctamente

---

Documento generado por: NEXUS Orchestration Fecha: 2026-01-04