---
id: "RF-PMC-001"
title: "Tenants Module"
type: "Requirement"
status: "Done"
priority: "Alta"
module: "tenants"
project: "platform_marketing_content"
version: "1.0"
rf_count: 15
created_date: "2025-12-08"
updated_date: "2026-01-04"
---

# Requerimientos Funcionales - PMC-001 Tenants

**Módulo:** Tenants
**Versión:** 1.0.0
**Fecha:** 2025-12-08

---

## RF-PMC-001-001: Crear Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-001 |
| **Nombre** | Crear Tenant |
| **Prioridad** | P1 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir crear un nuevo tenant con datos básicos.

**Precondiciones:**
- Usuario autenticado como Super Admin

**Datos de entrada:**
- name: string (requerido, 3-100 caracteres)
- slug: string (requerido, único, formato URL-safe)
- plan_id: UUID (requerido)
- settings: object (opcional)
- branding: object (opcional)

**Flujo principal:**
1. Super Admin accede a gestión de tenants
2. Selecciona "Crear tenant"
3. Completa formulario con datos requeridos
4. Sistema valida unicidad del slug
5. Sistema crea tenant con status "active"
6. Sistema crea usuario admin inicial (opcional)
7. Sistema retorna tenant creado

**Postcondiciones:**
- Tenant existe en base de datos
- Tenant tiene plan asignado
- RLS configurado para nuevo tenant

**Criterios de aceptación:**
- [ ] Validación de slug único funciona
- [ ] Tenant se crea con status "active"
- [ ] Plan se asocia correctamente

---

## RF-PMC-001-002: Editar Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-002 |
| **Nombre** | Editar Tenant |
| **Prioridad** | P2 |
| **Actor** | Super Admin, Tenant Admin |

**Descripción:**
El sistema debe permitir modificar datos de un tenant existente.

**Precondiciones:**
- Usuario autenticado con permisos de edición
- Tenant existe

**Datos de entrada:**
- name: string (opcional)
- settings: object (opcional)
- branding: object (opcional)
- limits: object (opcional, solo Super Admin)

**Flujo principal:**
1. Usuario accede a configuración del tenant
2. Modifica campos permitidos según rol
3. Sistema valida datos
4. Sistema actualiza tenant
5. Sistema registra cambio en audit log

**Restricciones:**
- Tenant Admin no puede modificar limits ni plan
- Slug no es editable después de creación

**Criterios de aceptación:**
- [ ] Campos se actualizan correctamente
- [ ] Permisos por rol se respetan
- [ ] Audit log registra cambios

---

## RF-PMC-001-003: Suspender Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-003 |
| **Nombre** | Suspender Tenant |
| **Prioridad** | P2 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir suspender un tenant, bloqueando acceso de usuarios.

**Precondiciones:**
- Usuario autenticado como Super Admin
- Tenant existe con status "active"

**Flujo principal:**
1. Super Admin selecciona tenant a suspender
2. Sistema solicita confirmación
3. Sistema cambia status a "suspended"
4. Sistema invalida todas las sesiones del tenant
5. Sistema notifica a admins del tenant

**Postcondiciones:**
- Usuarios del tenant no pueden hacer login
- Datos permanecen intactos
- Jobs pendientes se pausan

**Criterios de aceptación:**
- [ ] Status cambia a "suspended"
- [ ] Login bloqueado para usuarios del tenant
- [ ] Sesiones existentes invalidadas

---

## RF-PMC-001-004: Reactivar Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-004 |
| **Nombre** | Reactivar Tenant |
| **Prioridad** | P2 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir reactivar un tenant suspendido.

**Precondiciones:**
- Tenant existe con status "suspended"

**Flujo principal:**
1. Super Admin selecciona tenant suspendido
2. Selecciona "Reactivar"
3. Sistema cambia status a "active"
4. Sistema notifica a admins del tenant

**Postcondiciones:**
- Usuarios pueden hacer login
- Jobs pausados se reactivan

**Criterios de aceptación:**
- [ ] Status cambia a "active"
- [ ] Login permitido nuevamente

---

## RF-PMC-001-005: Eliminar Tenant (Soft Delete)

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-005 |
| **Nombre** | Eliminar Tenant |
| **Prioridad** | P3 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir eliminar un tenant mediante soft delete.

**Precondiciones:**
- Tenant existe

**Flujo principal:**
1. Super Admin selecciona tenant a eliminar
2. Sistema solicita confirmación con texto de verificación
3. Sistema marca tenant como eliminado (deleted_at)
4. Sistema invalida sesiones
5. Sistema programa limpieza de datos (90 días)

**Postcondiciones:**
- Tenant marcado con deleted_at
- Datos retenidos por 90 días
- Acceso completamente bloqueado

**Criterios de aceptación:**
- [ ] Soft delete funciona correctamente
- [ ] Datos no se eliminan inmediatamente
- [ ] Tenant no aparece en listados

---

## RF-PMC-001-006: Listar Tenants

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-006 |
| **Nombre** | Listar Tenants |
| **Prioridad** | P1 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir listar todos los tenants con filtros y paginación.

**Datos de entrada (query params):**
- status: string (filtro por estado)
- plan_id: UUID (filtro por plan)
- search: string (búsqueda por nombre)
- page: number
- limit: number (max 100)

**Datos de salida:**
- Lista de tenants con datos básicos
- Total de registros
- Información de paginación

**Criterios de aceptación:**
- [ ] Paginación funciona correctamente
- [ ] Filtros se aplican correctamente
- [ ] Búsqueda por nombre funciona

---

## RF-PMC-001-007: Ver Detalle de Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-007 |
| **Nombre** | Ver Detalle de Tenant |
| **Prioridad** | P1 |
| **Actor** | Super Admin, Tenant Admin |

**Descripción:**
El sistema debe mostrar información detallada de un tenant.

**Datos de salida:**
- Datos básicos del tenant
- Plan asociado con límites
- Configuración (settings)
- Branding
- Estadísticas de uso
- Usuarios activos (count)

**Criterios de aceptación:**
- [ ] Todos los datos se muestran correctamente
- [ ] Tenant Admin solo ve su propio tenant

---

## RF-PMC-001-008: Configurar Branding

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-008 |
| **Nombre** | Configurar Branding |
| **Prioridad** | P3 |
| **Actor** | Tenant Admin |

**Descripción:**
El sistema debe permitir personalizar el branding del tenant.

**Datos de entrada:**
- logo_url: string (URL o upload)
- primary_color: string (hex color)
- secondary_color: string (hex color)
- favicon_url: string (opcional)

**Flujo principal:**
1. Admin accede a configuración de branding
2. Sube logo o proporciona URL
3. Selecciona colores
4. Sistema valida formatos
5. Sistema actualiza branding
6. Cambios se reflejan en UI

**Criterios de aceptación:**
- [ ] Logo se almacena/referencia correctamente
- [ ] Colores se aplican en UI
- [ ] Preview disponible antes de guardar

---

## RF-PMC-001-009: Configurar Límites Personalizados

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-009 |
| **Nombre** | Configurar Límites Personalizados |
| **Prioridad** | P2 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir sobreescribir límites del plan para un tenant específico.

**Datos de entrada:**
- generations_per_month: number (null = usar plan)
- storage_gb: number (null = usar plan)
- users_max: number (null = usar plan)
- custom_limits: object

**Flujo principal:**
1. Super Admin accede a límites del tenant
2. Modifica valores específicos
3. Sistema valida que valores sean >= 0
4. Sistema guarda límites personalizados
5. Límites se aplican sobre los del plan

**Criterios de aceptación:**
- [ ] Límites personalizados sobreescriben plan
- [ ] Valores null usan defaults del plan
- [ ] Cambios se aplican inmediatamente

---

## RF-PMC-001-010: Obtener Tenant Actual

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-010 |
| **Nombre** | Obtener Tenant Actual |
| **Prioridad** | P1 |
| **Actor** | Usuario autenticado |

**Descripción:**
El sistema debe proporcionar los datos del tenant del usuario actual.

**Flujo principal:**
1. Usuario hace request a /tenants/current
2. Sistema extrae tenant_id del JWT
3. Sistema retorna datos del tenant

**Datos de salida:**
- Datos básicos del tenant
- Plan con límites efectivos
- Branding
- Settings relevantes para el usuario

**Criterios de aceptación:**
- [ ] Endpoint retorna tenant correcto
- [ ] Límites efectivos calculados correctamente

---

## RF-PMC-001-011: Validar Cuota de Uso

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-011 |
| **Nombre** | Validar Cuota de Uso |
| **Prioridad** | P1 |
| **Actor** | Sistema |

**Descripción:**
El sistema debe validar cuotas antes de operaciones que consumen recursos.

**Operaciones validadas:**
- Generación de imágenes
- Entrenamiento de modelos
- Subida de archivos (storage)
- Creación de usuarios

**Flujo principal:**
1. Usuario solicita operación
2. Sistema obtiene límites del tenant
3. Sistema obtiene uso actual
4. Sistema compara uso vs límite
5. Si excede: rechaza con error específico
6. Si no excede: permite operación

**Criterios de aceptación:**
- [ ] Validación ocurre antes de cada operación
- [ ] Mensaje de error indica límite y uso actual
- [ ] Operaciones no se ejecutan si exceden límite

---

## RF-PMC-001-012: Aplicar RLS por Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-012 |
| **Nombre** | Aplicar RLS por Tenant |
| **Prioridad** | P1 |
| **Actor** | Sistema |

**Descripción:**
El sistema debe garantizar aislamiento de datos entre tenants mediante RLS.

**Implementación:**
1. Todas las tablas principales tienen columna tenant_id
2. Políticas RLS filtran por tenant_id
3. Middleware inyecta tenant_id en cada request
4. SET app.current_tenant ejecutado antes de queries

**Tablas afectadas:**
- clients, contacts, brands, products
- projects, campaigns
- assets, collections
- users, roles
- generation_jobs, custom_models
- automation_flows, automation_runs

**Criterios de aceptación:**
- [ ] Queries solo retornan datos del tenant actual
- [ ] INSERT automáticamente incluye tenant_id
- [ ] No es posible acceder a datos de otro tenant

---

## RF-PMC-001-013: Gestionar Planes

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-013 |
| **Nombre** | Gestionar Planes |
| **Prioridad** | P2 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir crear y gestionar planes de suscripción.

**Datos de entrada:**
- name: string
- code: string (único)
- features: object (funcionalidades habilitadas)
- limits: object (cuotas)
- price_monthly: decimal
- price_yearly: decimal
- is_active: boolean

**Operaciones:**
- Crear plan
- Editar plan
- Activar/desactivar plan
- Ver tenants por plan

**Criterios de aceptación:**
- [ ] CRUD de planes funciona
- [ ] Planes inactivos no asignables a nuevos tenants
- [ ] Cambio de plan en tenant actualiza límites

---

## RF-PMC-001-014: Cambiar Plan de Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-014 |
| **Nombre** | Cambiar Plan de Tenant |
| **Prioridad** | P2 |
| **Actor** | Super Admin |

**Descripción:**
El sistema debe permitir cambiar el plan de un tenant.

**Flujo principal:**
1. Super Admin selecciona tenant
2. Selecciona nuevo plan
3. Sistema valida compatibilidad
4. Sistema actualiza plan_id
5. Nuevos límites se aplican inmediatamente
6. Sistema notifica a admins del tenant

**Validaciones:**
- Si downgrade: verificar que uso actual no exceda nuevos límites
- Warning si usuarios exceden nuevo límite

**Criterios de aceptación:**
- [ ] Plan se actualiza correctamente
- [ ] Límites se aplican inmediatamente
- [ ] Warnings apropiados en downgrade

---

## RF-PMC-001-015: Ver Uso del Tenant

| Campo | Valor |
|-------|-------|
| **ID** | RF-PMC-001-015 |
| **Nombre** | Ver Uso del Tenant |
| **Prioridad** | P2 |
| **Actor** | Super Admin, Tenant Admin |

**Descripción:**
El sistema debe mostrar métricas de uso del tenant.

**Datos de salida:**
- Generaciones: usado/límite
- Storage: usado/límite (GB)
- Usuarios: activos/límite
- Entrenamientos: usado/límite
- Período de facturación actual

**Criterios de aceptación:**
- [ ] Métricas se calculan correctamente
- [ ] Porcentajes y gráficos visuales
- [ ] Alertas cuando se acerca al límite (>80%)

---

## Resumen

| Prioridad | Cantidad |
|-----------|----------|
| P1 | 6 |
| P2 | 6 |
| P3 | 3 |
| **Total** | **15** |

---

**Documento generado por:** Requirements-Analyst
**Fecha:** 2025-12-08