rckrdmrd 74b5ed7f38 feat: Complete documentation update and orchestration configuration

- Update vision, architecture and technical documentation
- Update module definitions (PMC-001 to PMC-008)
- Update requirements documentation
- Add CONTEXT-MAP.yml and ENVIRONMENT-INVENTORY.yml
- Add orchestration guidelines and references

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-07 05:38:31 -06:00

13 KiB

Raw Blame History

id	title	type	epic	status	project	version	created_date	updated_date
PMC-007-ADMIN	PMC-007: Módulo de Admin	Module Definition	PMC-007	Draft	platform_marketing_content	1.0.0	2026-01-04	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

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

Entidades del Dominio

User

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

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)

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

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

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

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

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

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

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

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

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

13 KiB Raw Blame History