---
id: "PMC-007-ADMIN"
title: "PMC-007: Módulo de Admin"
type: "Module Definition"
epic: "PMC-007"
status: "Draft"
project: "platform_marketing_content"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# PMC-007: Módulo de Admin

**Versión:** 1.0.0
**Fecha:** 2025-12-08
**Estado:** Definición
**Prioridad:** Media

---

## Descripción General

El módulo de Admin proporciona las funcionalidades de administración del sistema SaaS: gestión de usuarios, roles, permisos, planes de suscripción, configuración global y herramientas de supervisión.

---

## Objetivos

1. Gestionar usuarios y sus roles dentro del tenant
2. Controlar permisos de acceso por módulo/acción
3. Administrar planes y suscripciones (preparación SaaS)
4. Configurar parámetros globales del sistema
5. Monitorear uso y salud del sistema

---

## Entidades del Dominio

### User

```yaml
Entidad: User
Descripción: Usuario del sistema
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - email: string (único por tenant)
  - password_hash: string
  - first_name: string
  - last_name: string
  - avatar_url: string
  - status: enum [pending, active, suspended, deactivated]
  - role_id: UUID (FK)
  - preferences: JSONB
    - language: string
    - timezone: string
    - theme: string
    - notifications: object
  - last_login_at: timestamp
  - email_verified_at: timestamp
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con Role
  - 1:N con Project (como owner)
  - 1:N con Asset (como creator)
  - 1:N con GenerationJob
```

### Role

```yaml
Entidad: Role
Descripción: Rol con conjunto de permisos
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK, null = rol de sistema)
  - name: string
  - description: text
  - permissions: array[string] (lista de permisos)
  - is_system: boolean (no editable si true)
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant (opcional)
  - 1:N con User

Roles de Sistema:
  - super_admin: Acceso total, sin límites
  - tenant_admin: Admin del tenant
  - creative: Crear contenido, gestionar campañas
  - analyst: CRM, reportes
  - viewer: Solo lectura
```

### Permission (definición estática)

```yaml
Permisos del Sistema:
  # Tenants
  - tenants.view
  - tenants.create
  - tenants.edit
  - tenants.delete

  # Users
  - users.view
  - users.create
  - users.edit
  - users.delete
  - users.invite

  # CRM
  - clients.view
  - clients.create
  - clients.edit
  - clients.delete
  - brands.view
  - brands.create
  - brands.edit
  - brands.delete
  - products.view
  - products.create
  - products.edit
  - products.delete

  # Projects
  - projects.view
  - projects.create
  - projects.edit
  - projects.delete
  - campaigns.view
  - campaigns.create
  - campaigns.edit
  - campaigns.delete
  - campaigns.approve

  # Generation
  - generation.execute
  - generation.view_queue
  - generation.manage_queue
  - models.view
  - models.create
  - models.delete
  - models.train

  # Assets
  - assets.view
  - assets.upload
  - assets.edit
  - assets.delete
  - assets.approve
  - assets.download

  # Automation
  - automation.view
  - automation.configure
  - automation.execute

  # Admin
  - admin.users
  - admin.roles
  - admin.settings
  - admin.billing
  - admin.audit
```

### Invitation

```yaml
Entidad: Invitation
Descripción: Invitación pendiente para unirse al tenant
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - email: string
  - role_id: UUID (FK)
  - invited_by: UUID (FK a User)
  - token: string (único)
  - status: enum [pending, accepted, expired, cancelled]
  - expires_at: timestamp
  - accepted_at: timestamp
  - created_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con Role
  - N:1 con User (inviter)
```

### AuditLog

```yaml
Entidad: AuditLog
Descripción: Registro de acciones importantes
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - user_id: UUID (FK)
  - action: string (ej: user.created, asset.deleted)
  - entity_type: string
  - entity_id: UUID
  - old_values: JSONB
  - new_values: JSONB
  - ip_address: string
  - user_agent: string
  - created_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con User
```

### Setting

```yaml
Entidad: Setting
Descripción: Configuración del sistema/tenant
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK, null = global)
  - key: string
  - value: JSONB
  - type: enum [string, number, boolean, json]
  - category: string
  - is_secret: boolean
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant (opcional)
```

---

## Funcionalidades

### F-007.1: Gestión de Usuarios

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-007.1.1 | Listar usuarios | Ver todos los usuarios del tenant | Alta |
| F-007.1.2 | Invitar usuario | Enviar invitación por email | Alta |
| F-007.1.3 | Editar usuario | Modificar datos y rol | Alta |
| F-007.1.4 | Suspender usuario | Bloquear acceso temporalmente | Media |
| F-007.1.5 | Eliminar usuario | Desactivar cuenta | Media |

### F-007.2: Gestión de Roles

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-007.2.1 | Listar roles | Ver roles disponibles | Alta |
| F-007.2.2 | Crear rol | Definir rol personalizado | Media |
| F-007.2.3 | Editar permisos | Modificar permisos de rol | Media |
| F-007.2.4 | Eliminar rol | Solo si no tiene usuarios | Baja |

### F-007.3: Configuración

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-007.3.1 | Settings generales | Nombre, branding, etc. | Alta |
| F-007.3.2 | Settings de generación | Modelos por defecto, calidad | Media |
| F-007.3.3 | Integraciones | Configurar n8n, APIs externas | Media |
| F-007.3.4 | Notificaciones | Templates de email, webhooks | Media |

### F-007.4: Auditoría

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-007.4.1 | Ver logs | Historial de acciones | Media |
| F-007.4.2 | Filtrar logs | Por usuario, acción, fecha | Media |
| F-007.4.3 | Exportar logs | Descargar en CSV | Baja |

### F-007.5: Monitoreo (Super Admin)

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-007.5.1 | Dashboard sistema | Métricas globales | Media |
| F-007.5.2 | Estado de servicios | GPU, queue, storage | Alta |
| F-007.5.3 | Uso por tenant | Consumo de recursos | Media |

---

## Roles del Sistema

### Matriz de Permisos por Rol

```yaml
super_admin:
  description: "Administrador del sistema completo"
  permissions: ["*"] # Todos los permisos
  notes: "Solo para el owner/CTO. Sin límites de uso."

tenant_admin:
  description: "Administrador del tenant/agencia"
  permissions:
    - users.*
    - roles.view
    - clients.*
    - brands.*
    - products.*
    - projects.*
    - campaigns.*
    - generation.*
    - assets.*
    - automation.view
    - automation.configure
    - admin.users
    - admin.settings
    - admin.audit

creative:
  description: "Creativo/Media Buyer"
  permissions:
    - clients.view
    - brands.view
    - products.view
    - products.create
    - projects.view
    - projects.create
    - projects.edit
    - campaigns.*
    - generation.execute
    - generation.view_queue
    - models.view
    - assets.view
    - assets.upload
    - assets.edit

analyst:
  description: "Analista/CRM"
  permissions:
    - clients.*
    - brands.view
    - products.view
    - projects.view
    - campaigns.view
    - assets.view
    - assets.download
    - automation.view

viewer:
  description: "Solo lectura"
  permissions:
    - clients.view
    - brands.view
    - products.view
    - projects.view
    - campaigns.view
    - assets.view

client_portal:
  description: "Cliente externo (portal)"
  permissions:
    - campaigns.view # Solo sus campañas
    - assets.view    # Solo sus assets
    - assets.download
```

---

## API Endpoints

```yaml
Base: /api/v1/admin

# Users
GET    /users                   # Listar usuarios
GET    /users/:id               # Detalle de usuario
POST   /users/invite            # Invitar usuario
PUT    /users/:id               # Actualizar usuario
PATCH  /users/:id/status        # Cambiar estado
DELETE /users/:id               # Desactivar usuario

# Invitations
GET    /invitations             # Listar invitaciones
POST   /invitations/:id/resend  # Reenviar
DELETE /invitations/:id         # Cancelar

# Roles
GET    /roles                   # Listar roles
GET    /roles/:id               # Detalle de rol
POST   /roles                   # Crear rol
PUT    /roles/:id               # Actualizar rol
DELETE /roles/:id               # Eliminar rol

# Settings
GET    /settings                # Listar settings
GET    /settings/:key           # Obtener setting
PUT    /settings/:key           # Actualizar setting
DELETE /settings/:key           # Eliminar setting (custom)

# Audit
GET    /audit                   # Listar logs
GET    /audit/export            # Exportar logs

# System (Super Admin only)
GET    /system/status           # Estado del sistema
GET    /system/metrics          # Métricas globales
GET    /system/tenants          # Listar todos los tenants
GET    /system/tenants/:id/usage # Uso de un tenant
```

---

## Reglas de Negocio

```yaml
RN-007.1:
  Descripción: Email único por tenant
  Validación: No puede haber dos usuarios con mismo email en un tenant

RN-007.2:
  Descripción: Roles de sistema no editables
  Validación: is_system = true bloquea edición

RN-007.3:
  Descripción: No eliminar rol con usuarios asignados
  Validación: Verificar user_count = 0 antes de DELETE

RN-007.4:
  Descripción: Invitación expira en 7 días
  Validación: expires_at = created_at + 7 days

RN-007.5:
  Descripción: Super admin no puede ser suspendido
  Validación: Bloquear cambio de status si role = super_admin

RN-007.6:
  Descripción: Audit logs son inmutables
  Validación: Solo INSERT, no UPDATE ni DELETE
```

---

## Dependencias

```yaml
Dependencias de Módulos:
  - PMC-001 Tenants: Configuración de tenant
  - Todos los módulos: Para verificación de permisos

Dependencias del Catálogo:
  - @CATALOG_AUTH:
      path: shared/catalog/auth/
      uso: Sistema completo de autenticacion
      incluye:
        - JWT access + refresh tokens
        - Password hashing con bcrypt
        - Guards y decoradores
        - Recuperacion de contrasena
        - Verificacion de email
      adaptar:
        - Definir roles especificos PMC (super_admin, tenant_admin, creative, etc.)
        - Agregar tenant_id al JWT payload
        - Integrar con sistema de permisos RBAC
      docs: shared/catalog/auth/README.md

  - @CATALOG_SESSION:
      path: shared/catalog/session-management/
      uso: Gestion de sesiones activas
      incluye:
        - Maximo N sesiones concurrentes
        - Tracking de dispositivos
        - Logout selectivo/global
        - Auto-cleanup de expiradas
      adaptar:
        - Limite de sesiones por plan de suscripcion
        - Integrar con audit log
      docs: shared/catalog/session-management/README.md

  - @CATALOG_FLAGS:
      path: shared/catalog/feature-flags/
      uso: Feature flags para rollout gradual (opcional)
      docs: shared/catalog/feature-flags/README.md

  - @CATALOG_NOTIFY:
      path: shared/catalog/notifications/
      uso: Envio de invitaciones y notificaciones
      docs: shared/catalog/notifications/README.md

Servicios Externos:
  - SMTP: Envío de invitaciones (via @CATALOG_NOTIFY)
  - OAuth providers (opcional): Google, Microsoft para SSO

Referencia de Implementacion:
  - Auth module: projects/gamilit/apps/backend/src/modules/auth/
  - Session service: projects/gamilit/apps/backend/src/modules/auth/services/session-management.service.ts
  - Roles/permissions: projects/gamilit/apps/backend/src/modules/admin/services/
```

---

## Flujos de Usuario

### Invitar Usuario

```
1. Admin navega a Users → Invite
2. Ingresa email y selecciona rol
3. Sistema genera token único
4. Sistema envía email con link
5. Usuario hace clic en link
6. Usuario completa registro (password, nombre)
7. Usuario queda activo en el tenant
```

### Cambiar Rol de Usuario

```
1. Admin navega a Users → [Usuario]
2. Selecciona nuevo rol
3. Sistema verifica que no sea el único admin
4. Sistema actualiza rol
5. Permisos se aplican inmediatamente
6. Se registra en audit log
```

---

## Criterios de Aceptación

- [ ] CRUD completo de usuarios funciona
- [ ] Sistema de invitaciones por email funciona
- [ ] Roles controlan acceso a módulos correctamente
- [ ] Permisos se verifican en cada endpoint
- [ ] Settings se guardan y cargan correctamente
- [ ] Audit logs registran acciones importantes
- [ ] Dashboard de sistema muestra métricas
- [ ] Super admin tiene acceso a todo

---

## Referencias

- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)
- [@CATALOG_AUTH](../../../shared/catalog/modules/auth/)
- [PMC-001-TENANTS.md](./PMC-001-TENANTS.md)

---

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