erp-core/docs/04-modelado/requerimientos-funcionales/mgn-015/RF-MGN-015-006-modo-single-tenant.md

RF-MGN-015-006: Modo Single-Tenant

Módulo: MGN-015 - Billing y Suscripciones Prioridad: P1 Story Points: 5 Estado: Definido Fecha: 2025-11-24

Descripción

El sistema debe soportar un modo de operación "single-tenant" para instalaciones on-premise donde un cliente adquiere el sistema completo para uso exclusivo. En este modo, el sistema de billing se simplifica: existe un único tenant con plan especial que tiene todas las funcionalidades habilitadas y sin límites.

Actores

• Actor Principal: Administrador de Sistema (on-premise)
• Actores Secundarios: Usuario Final (sin interacción con billing)

Precondiciones

1. Instalación limpia del sistema
2. Configuración de ambiente: DEPLOYMENT_MODE=single_tenant
3. Script de inicialización ejecutado

Flujo Principal - Inicialización Single-Tenant

1. Administrador ejecuta script de setup inicial
2. Sistema detecta modo single-tenant en configuración
3. Sistema crea:
   • Tenant único con configuración especial
   • Suscripción con plan "single_tenant" (sin vencimiento)
   • Usuario administrador inicial
4. Sistema deshabilita:
   • Registro público de nuevos tenants
   • Página de precios/planes
   • Módulos de billing para usuarios finales
5. Sistema habilita:
   • Todas las funcionalidades del ERP
   • Usuarios ilimitados
   • Empresas ilimitadas

Flujos Alternativos

FA-1: Personalización de Marca

1. Administrador accede a configuración de sistema
2. Puede personalizar: logo, colores, nombre
3. Sistema aplica branding personalizado
4. No aparece referencia a plataforma SaaS original

FA-2: Actualizaciones

1. Sistema puede recibir actualizaciones
2. Actualizaciones de billing se ignoran/minimizan
3. Funcionalidades de ERP se actualizan normalmente

FA-3: Migración a SaaS

1. Cliente desea migrar de single-tenant a SaaS
2. Administrador exporta datos del tenant
3. Se importan a instancia SaaS como nuevo tenant
4. Se configura plan y billing normalmente

Reglas de Negocio

• RN-1: Solo existe un tenant en modo single-tenant
• RN-2: Plan "single_tenant" no tiene límites (max_users = NULL)
• RN-3: Suscripción no tiene fecha de vencimiento
• RN-4: No se muestran opciones de upgrade/billing
• RN-5: Registro de nuevos tenants está deshabilitado
• RN-6: Todas las features están habilitadas
• RN-7: No hay integración con gateway de pagos

Criterios de Aceptación

• Sistema se puede instalar en modo single-tenant
• Plan single_tenant tiene todas las features habilitadas
• No hay límites de usuarios ni empresas
• Suscripción no tiene fecha de vencimiento
• UI no muestra opciones de billing a usuarios
• Registro público de tenants está deshabilitado
• Administrador puede personalizar branding
• Sistema funciona sin conexión a internet

Entidades Involucradas

• Principales:
  • billing.subscription_plans (plan "single_tenant")
  • billing.subscriptions (suscripción permanente)
• Relacionadas:
  • auth.tenants (tenant único)
  • Sistema de configuración (DEPLOYMENT_MODE)

Configuración

# .env para modo single-tenant
DEPLOYMENT_MODE=single_tenant
DISABLE_PUBLIC_REGISTRATION=true
DISABLE_BILLING_UI=true

# Personalización de marca
BRAND_NAME=Mi Empresa ERP
BRAND_LOGO_URL=/assets/custom-logo.png
BRAND_PRIMARY_COLOR=#1a365d

Plan Single-Tenant

{
  "code": "single_tenant",
  "name": "Licencia Empresarial",
  "price_monthly": 0,
  "price_yearly": 0,
  "max_users": null,
  "max_companies": null,
  "max_storage_gb": null,
  "features": {
    "inventory": true,
    "sales": true,
    "purchase": true,
    "financial": true,
    "crm": true,
    "projects": true,
    "hr": true,
    "manufacturing": true,
    "reports_basic": true,
    "reports_advanced": true,
    "api_access": true,
    "white_label": true,
    "custom_domain": true,
    "sso": true,
    "audit_log": true,
    "data_export": true
  },
  "is_public": false,
  "is_active": true
}

Diferencias SaaS vs Single-Tenant

Aspecto	SaaS Multi-Tenant	Single-Tenant
Tenants	Múltiples	Uno
Registro	Público/Abierto	Deshabilitado
Billing	Activo	Oculto
Límites	Según plan	Sin límites
Pagos	Automáticos	N/A
Actualizaciones	Automáticas	Manuales
Personalización	Limitada	Completa
Infraestructura	Compartida	Dedicada

Script de Inicialización

# setup-single-tenant.sh
#!/bin/bash

# Verificar modo
if [ "$DEPLOYMENT_MODE" != "single_tenant" ]; then
  echo "Error: DEPLOYMENT_MODE must be 'single_tenant'"
  exit 1
fi

# Crear tenant único
psql $DATABASE_URL <<EOF
  -- Crear tenant
  INSERT INTO auth.tenants (id, name, subdomain, plan, settings)
  VALUES (
    '00000000-0000-0000-0000-000000000001',
    'Sistema ERP',
    'main',
    'single_tenant',
    '{"mode": "single_tenant", "white_label": true}'::jsonb
  );

  -- Crear suscripción permanente
  INSERT INTO billing.subscriptions (
    tenant_id, plan_id, status, billing_cycle,
    current_period_start, current_period_end
  )
  SELECT
    '00000000-0000-0000-0000-000000000001',
    id,
    'active',
    'yearly',
    NOW(),
    '2099-12-31'::timestamp
  FROM billing.subscription_plans
  WHERE code = 'single_tenant';
EOF

echo "Single-tenant setup complete!"

Referencias

• RF-MGN-015-001 - Plan single_tenant
• Guía de Instalación On-Premise

Notas Técnicas

• Variable de entorno: DEPLOYMENT_MODE=single_tenant
• Plan especial: single_tenant con is_public = false
• Fecha fin: 2099-12-31 (efectivamente sin vencimiento)
• Middleware: Oculta rutas de billing si es single-tenant
• UI: Componente detecta modo y oculta elementos de billing

Dependencias

• RF Requeridos: RF-MGN-015-001 (Plan single_tenant debe existir)
• Independiente de: RF-MGN-015-002, 003, 004, 005 (no aplican)