# 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 |
