RF-TENANT-001: Gestion de Tenants
Identificacion
| Campo |
Valor |
| ID |
RF-TENANT-001 |
| Modulo |
MGN-004 Tenants |
| Prioridad |
P0 - Critica |
| Estado |
Ready |
| Fecha |
2025-12-05 |
Descripcion
El sistema debe soportar una arquitectura multi-tenant donde cada organizacion (tenant) tiene su propio espacio aislado de datos. Los super administradores pueden crear, gestionar y eliminar tenants. Cada tenant tiene su propia configuracion, usuarios, roles y datos de negocio completamente aislados.
Actores
| Actor |
Descripcion |
| Platform Admin |
Administrador de la plataforma, gestiona todos los tenants |
| Tenant Admin |
Administrador de un tenant especifico |
| Sistema |
Procesos automaticos de gestion de tenants |
Precondiciones
- Platform Admin autenticado con permisos de plataforma
- Sistema de base de datos configurado con soporte para schemas/RLS
Flujo Principal
Crear Tenant
1. Platform Admin accede a Panel de Plataforma > Tenants
2. Click en "Nuevo Tenant"
3. Sistema muestra formulario:
- Nombre de la organizacion
- Slug (URL-friendly identifier)
- Email del admin inicial
- Plan de subscripcion
- Modulos a activar
4. Admin completa datos
5. Click en "Crear Tenant"
6. Sistema valida unicidad del slug
7. Sistema crea el tenant en base de datos
8. Sistema crea usuario admin inicial
9. Sistema asigna roles built-in al tenant
10. Sistema configura RLS policies
11. Sistema envia email de bienvenida al admin
12. Sistema muestra confirmacion
Listar Tenants
1. Platform Admin accede a Panel de Plataforma > Tenants
2. Sistema muestra tabla con:
- Nombre del tenant
- Slug
- Plan de subscripcion
- Estado (active, suspended, trial)
- Usuarios activos
- Fecha de creacion
- Ultimo acceso
3. Admin puede filtrar por estado, plan
4. Admin puede buscar por nombre o slug
Ver Detalle de Tenant
1. Platform Admin click en un tenant
2. Sistema muestra:
- Informacion basica
- Estadisticas de uso
- Lista de usuarios
- Modulos activos
- Historial de facturacion
- Logs de actividad
Suspender Tenant
1. Platform Admin click en "Suspender" de un tenant
2. Sistema muestra dialogo de confirmacion
3. Admin selecciona razon de suspension
4. Admin confirma
5. Sistema cambia estado a "suspended"
6. Sistema revoca todos los tokens activos
7. Sistema envia notificacion al admin del tenant
8. Usuarios del tenant no pueden acceder
Eliminar Tenant
1. Platform Admin click en "Eliminar" de un tenant
2. Sistema muestra advertencia severa
3. Admin debe escribir el slug del tenant para confirmar
4. Sistema programa eliminacion (grace period 30 dias)
5. Sistema notifica al admin del tenant
6. Despues del grace period, sistema elimina datos
Flujos Alternativos
FA1: Slug duplicado
1. En paso 6 del flujo crear
2. Sistema detecta slug ya existe
3. Sistema sugiere alternativas disponibles
4. Admin selecciona o modifica
5. Continua desde paso 5
FA2: Reactivar tenant suspendido
1. Platform Admin accede a tenant suspendido
2. Click en "Reactivar"
3. Sistema verifica estado de cuenta
4. Si hay problemas de pago, muestra opcion de resolver
5. Sistema cambia estado a "active"
6. Usuarios pueden acceder nuevamente
FA3: Cancelar eliminacion programada
1. Dentro del grace period
2. Platform Admin accede al tenant marcado para eliminacion
3. Click en "Cancelar eliminacion"
4. Sistema restaura estado anterior
5. Notifica al admin del tenant
Reglas de Negocio
| ID |
Regla |
| RN-001 |
Slug de tenant unico globalmente |
| RN-002 |
Slug: 3-50 caracteres, lowercase, alfanumerico con guiones |
| RN-003 |
Cada tenant debe tener al menos un admin |
| RN-004 |
Suspension inmediata, eliminacion con grace period |
| RN-005 |
Grace period de eliminacion: 30 dias |
| RN-006 |
Datos de tenant eliminado son irrecuperables |
| RN-007 |
Un tenant puede tener maximo segun plan (ej: 100 usuarios en plan basico) |
| RN-008 |
Tenant trial expira en 14 dias |
Estados del Tenant
┌─────────┐
│ trial │
└────┬────┘
│ (subscription)
▼
(reactivate) ┌─────────┐ (suspend)
┌─────────│ active │─────────┐
│ └────┬────┘ │
│ │ ▼
│ │ ┌───────────┐
│ │ │ suspended │
│ │ └─────┬─────┘
│ │ │
└──────────────┼──────────────┘
│ (delete)
▼
┌─────────────────┐
│ pending_deletion│
└────────┬────────┘
│ (30 days)
▼
┌──────────┐
│ deleted │
└──────────┘
Criterios de Aceptacion
Escenario 1: Crear tenant exitosamente
Given un Platform Admin autenticado
When crea un tenant con:
| name | Empresa ABC |
| slug | empresa-abc |
| email | admin@empresaabc.com |
| plan | professional |
Then el sistema crea el tenant
And crea usuario admin con email proporcionado
And asigna roles built-in al tenant
And envia email de bienvenida
And responde con status 201
Escenario 2: Listar tenants con filtros
Given 50 tenants en la plataforma
When Platform Admin filtra por status="active" y plan="professional"
Then el sistema retorna solo tenants activos con plan professional
And incluye metricas de cada tenant
Escenario 3: No crear tenant con slug duplicado
Given un tenant existente con slug "empresa-abc"
When se intenta crear otro con slug "empresa-abc"
Then el sistema responde con status 409
And sugiere slugs alternativos
Escenario 4: Suspender tenant
Given un tenant activo "empresa-abc" con 10 usuarios
When Platform Admin lo suspende por "falta_pago"
Then el estado cambia a "suspended"
And los 10 usuarios no pueden acceder
And se envia email al admin del tenant
Escenario 5: Grace period de eliminacion
Given un tenant marcado para eliminacion hace 25 dias
When han pasado 30 dias desde la marca
Then el sistema elimina permanentemente los datos
And el slug queda disponible para reusar
Mockup / Wireframe
+------------------------------------------------------------------+
| [Logo] Platform Admin - Tenants [+ Nuevo Tenant] |
+------------------------------------------------------------------+
| Buscar: [___________________] [Estado: Todos ▼] [Plan: Todos ▼] |
+------------------------------------------------------------------+
| | Nombre | Slug | Plan | Estado | Usuarios | ⚙ |
|---|----------------|-------------|--------|--------|----------|-----|
| | Empresa ABC | empresa-abc | Pro | Active | 45 | 👁✏🗑|
| | Comercial XYZ | comercial | Basic | Active | 12 | 👁✏🗑|
| | Demo Company | demo-co | Trial | Trial | 3 | 👁✏🗑|
| | Old Client | old-client | Basic | Susp. | 0 | 👁✏⚠ |
+------------------------------------------------------------------+
| Mostrando 1-4 de 50 [< Anterior] [Siguiente >]|
+------------------------------------------------------------------+
Modal: Crear Tenant
┌──────────────────────────────────────────────────────────────────┐
│ NUEVO TENANT │
├──────────────────────────────────────────────────────────────────┤
│ Nombre* [_______________________________] │
│ Slug* [_______________________________] │
│ URL: https://erp.com/empresa-abc │
│ │
│ ADMIN INICIAL │
│ Email* [_______________________________] │
│ Nombre [_______________________________] │
│ │
│ SUBSCRIPCION │
│ Plan [Professional ▼] │
│ Periodo trial [14 dias ▼] │
│ │
│ MODULOS │
│ ☑ Auth ☑ Users ☑ Roles │
│ ☑ Inventory ☑ Financial ☐ CRM │
│ ☑ Reports ☐ Advanced ☐ API │
│ │
│ [ Cancelar ] [ Crear Tenant ] │
└──────────────────────────────────────────────────────────────────┘
Notas Tecnicas
API Endpoints
// Crear tenant (Platform Admin only)
POST /api/v1/platform/tenants
{
"name": "Empresa ABC",
"slug": "empresa-abc",
"adminEmail": "admin@empresaabc.com",
"adminName": "Juan Perez",
"planId": "plan-professional",
"moduleIds": ["mod-auth", "mod-users", "mod-inventory"],
"trialDays": 14
}
// Response 201
{
"id": "tenant-uuid",
"name": "Empresa ABC",
"slug": "empresa-abc",
"status": "trial",
"plan": { "id": "...", "name": "Professional" },
"admin": { "id": "...", "email": "admin@empresaabc.com" },
"trialEndsAt": "2025-12-19T00:00:00Z",
"createdAt": "2025-12-05T10:00:00Z"
}
// Listar tenants
GET /api/v1/platform/tenants?status=active&plan=professional&page=1&limit=20
// Ver detalle
GET /api/v1/platform/tenants/:id
// Actualizar tenant
PATCH /api/v1/platform/tenants/:id
// Suspender tenant
POST /api/v1/platform/tenants/:id/suspend
{ "reason": "payment_failed", "notes": "Invoice #123 unpaid" }
// Reactivar tenant
POST /api/v1/platform/tenants/:id/reactivate
// Programar eliminacion
POST /api/v1/platform/tenants/:id/schedule-deletion
// Cancelar eliminacion
POST /api/v1/platform/tenants/:id/cancel-deletion
// Eliminar inmediatamente (solo desarrollo)
DELETE /api/v1/platform/tenants/:id?force=true
Validaciones
| Campo |
Regla |
| name |
Required, 3-100 chars |
| slug |
Required, 3-50 chars, lowercase, unique |
| adminEmail |
Required, valid email, unique |
| planId |
Required, plan existente |
Dependencias
| ID |
Descripcion |
| RF-AUTH-001 |
Para crear usuario admin |
| RF-ROLE-001 |
Para crear roles built-in |
| Database |
Soporte para RLS o schemas separados |
Estimacion
| Tarea |
Puntos |
| Backend: CRUD endpoints |
5 |
| Backend: Lifecycle (suspend/delete) |
4 |
| Backend: Tenant provisioning |
5 |
| Backend: Tests |
3 |
| Frontend: TenantsListPage |
4 |
| Frontend: TenantForm |
3 |
| Frontend: TenantDetail |
3 |
| Frontend: Tests |
2 |
| Total |
29 SP |
Historial
| Version |
Fecha |
Autor |
Cambios |
| 1.0 |
2025-12-05 |
System |
Creacion inicial |
