rckrdmrd/platform-marketing-content
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
74b5ed7f38
platform-marketing-content/docs/02-definicion-modulos/PMC-007-ADMIN.md
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

547 lines
13 KiB
Markdown
Raw Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink