397 lines
12 KiB
Markdown
397 lines
12 KiB
Markdown
# 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
|
|
|
|
1. Platform Admin autenticado con permisos de plataforma
|
|
2. 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
|
|
|
|
```gherkin
|
|
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
|
|
|
|
```gherkin
|
|
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
|
|
|
|
```gherkin
|
|
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
|
|
|
|
```gherkin
|
|
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
|
|
|
|
```gherkin
|
|
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
|
|
|
|
```typescript
|
|
// 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 |
|