# US-MGN004-001: Gestion de Tenants

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN004-001 |
| **Modulo** | MGN-004 Tenants |
| **RF Relacionado** | RF-TENANT-001 |
| **Prioridad** | P0 - Critica |
| **Story Points** | 13 |
| **Sprint** | TBD |

---

## Historia de Usuario

**Como** Platform Admin
**Quiero** gestionar los tenants de la plataforma (crear, ver, editar, suspender, eliminar)
**Para** administrar las organizaciones que usan el sistema ERP

---

## Criterios de Aceptacion

### AC-001: Listar tenants

```gherkin
Given soy Platform Admin autenticado
When accedo a GET /api/v1/platform/tenants
Then veo lista paginada de tenants
  And cada tenant muestra: nombre, slug, estado, fecha creacion
  And puedo filtrar por estado (created, trial, active, suspended)
  And puedo buscar por nombre o slug
```

### AC-002: Crear nuevo tenant

```gherkin
Given soy Platform Admin autenticado
When envio POST /api/v1/platform/tenants con:
  | name | slug | subdomain |
  | Empresa XYZ | empresa-xyz | xyz |
Then se crea el tenant con estado "created"
  And se crean los settings por defecto
  And se genera registro de auditoria
```

### AC-003: Validacion de slug unico

```gherkin
Given existe tenant con slug "empresa-abc"
When intento crear tenant con slug "empresa-abc"
Then el sistema responde con status 409
  And el mensaje indica que el slug ya existe
```

### AC-004: Ver detalle de tenant

```gherkin
Given soy Platform Admin autenticado
  And existe tenant "tenant-123"
When accedo a GET /api/v1/platform/tenants/tenant-123
Then veo toda la informacion del tenant
  And incluye: nombre, slug, subdominio, estado, fechas
  And incluye: subscripcion actual, uso de recursos
```

### AC-005: Actualizar tenant

```gherkin
Given soy Platform Admin autenticado
  And existe tenant "tenant-123" con nombre "Empresa Original"
When envio PATCH /api/v1/platform/tenants/tenant-123 con:
  | name | subdominio |
  | Empresa Nueva | nuevo |
Then el nombre cambia a "Empresa Nueva"
  And el subdominio cambia a "nuevo"
  And se actualiza updated_at y updated_by
```

### AC-006: Suspender tenant

```gherkin
Given soy Platform Admin autenticado
  And tenant "tenant-123" esta activo
When cambio estado a "suspended" con razon "Falta de pago"
Then el estado cambia a "suspended"
  And se registra suspended_at y suspension_reason
  And usuarios del tenant no pueden acceder
```

### AC-007: Reactivar tenant suspendido

```gherkin
Given soy Platform Admin autenticado
  And tenant "tenant-123" esta suspendido
When cambio estado a "active"
Then el estado cambia a "active"
  And se limpian campos de suspension
  And usuarios pueden acceder nuevamente
```

### AC-008: Programar eliminacion

```gherkin
Given soy Platform Admin autenticado
  And tenant "tenant-123" existe
When envio DELETE /api/v1/platform/tenants/tenant-123
Then el estado cambia a "pending_deletion"
  And se programa eliminacion en 30 dias
  And se notifica al owner del tenant
```

### AC-009: Restaurar tenant pendiente de eliminacion

```gherkin
Given soy Platform Admin autenticado
  And tenant "tenant-123" esta en "pending_deletion"
When envio POST /api/v1/platform/tenants/tenant-123/restore
Then el estado cambia a "active"
  And se cancela la eliminacion programada
```

### AC-010: Cambiar contexto a tenant (switch)

```gherkin
Given soy Platform Admin autenticado
When envio POST /api/v1/platform/switch-tenant/tenant-123
Then mi contexto cambia a tenant "tenant-123"
  And puedo ver datos de ese tenant
  And la accion queda auditada
```

---

## Tareas Tecnicas

| ID | Tarea | Estimacion |
|----|-------|------------|
| T-001 | Crear entidad Tenant con TypeORM | 1 SP |
| T-002 | Implementar TenantsService CRUD | 3 SP |
| T-003 | Implementar PlatformTenantsController | 2 SP |
| T-004 | Crear DTOs con validaciones | 1 SP |
| T-005 | Implementar transicion de estados | 2 SP |
| T-006 | Implementar switch tenant | 2 SP |
| T-007 | Tests unitarios | 2 SP |
| **Total** | | **13 SP** |

---

## Notas de Implementacion

- Estados validos: created -> trial -> active -> suspended -> pending_deletion -> deleted
- Solo Platform Admin puede gestionar tenants
- Switch tenant debe quedar en logs de auditoria
- Eliminacion real solo despues de 30 dias de grace period

---

## Mockup de Referencia

Ver RF-TENANT-001.md seccion Mockup.

---

## Dependencias

| Tipo | Descripcion |
|------|-------------|
| Backend | Schema core_tenants creado |
| Auth | JWT con claims de platform_admin |
| Audit | Sistema de auditoria funcionando |

---

## Definition of Done

- [ ] Endpoints implementados y documentados en Swagger
- [ ] Validaciones de DTOs completas
- [ ] Transiciones de estado implementadas
- [ ] Tests unitarios con >80% coverage
- [ ] Code review aprobado
- [ ] Logs de auditoria funcionando