platform-marketing-content/docs/02-definicion-modulos/PMC-004-GENERATION.md

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

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

---

## Descripción General

El módulo de Generation es el núcleo de la plataforma. Gestiona la generación de contenido mediante IA, incluyendo imágenes con Stable Diffusion/ComfyUI y textos con LLMs. Orquesta workflows, colas de tareas, y la integración con modelos personalizados (LoRAs).

---

## Objetivos

1. Generar imágenes de alta calidad para marketing
2. Generar copys y textos publicitarios
3. Ejecutar workflows predefinidos de ComfyUI
4. Gestionar modelos personalizados (LoRAs, checkpoints)
5. Mantener consistencia de marca en generaciones
6. Procesar tareas en cola con prioridades

---

## Entidades del Dominio

### GenerationJob

```yaml
Entidad: GenerationJob
Descripción: Tarea de generación en cola
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - campaign_id: UUID (FK, opcional)
  - product_id: UUID (FK, opcional)
  - user_id: UUID (FK, quien solicitó)
  - type: enum [image, text, image_batch, mixed]
  - status: enum [queued, processing, completed, failed, cancelled]
  - priority: integer (1-10, mayor = más urgente)
  - workflow_id: UUID (FK a WorkflowTemplate)
  - input_params: JSONB (parámetros de entrada)
  - output_assets: array[UUID] (assets generados)
  - error_message: text
  - progress: integer (0-100)
  - started_at: timestamp
  - completed_at: timestamp
  - created_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con Campaign
  - N:1 con Product
  - N:1 con User
  - N:1 con WorkflowTemplate
  - 1:N con Asset (outputs)
```

### WorkflowTemplate

```yaml
Entidad: WorkflowTemplate
Descripción: Plantilla de workflow de generación
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK, null = global)
  - name: string
  - description: text
  - type: enum [product_photo, social_post, banner, avatar, variation, custom]
  - category: string (para organización)
  - comfyui_workflow: JSONB (definición del workflow)
  - input_schema: JSONB (parámetros esperados)
  - output_config: JSONB
    - format: string (png, jpg, webp)
    - dimensions: array[string]
    - quantity_default: number
  - models_required: array[string] (checkpoints, LoRAs requeridos)
  - estimated_time_seconds: integer
  - is_active: boolean
  - is_system: boolean (plantilla del sistema vs personalizada)
  - created_at: timestamp
  - updated_at: timestamp

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

### CustomModel

```yaml
Entidad: CustomModel
Descripción: Modelo personalizado (LoRA, checkpoint, embedding)
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - brand_id: UUID (FK, opcional)
  - name: string
  - type: enum [lora, checkpoint, embedding, controlnet]
  - purpose: string (product, avatar, style, character)
  - description: text
  - file_path: string (ruta en storage)
  - file_size: bigint
  - status: enum [training, ready, failed, archived]
  - training_params: JSONB
    - base_model: string
    - steps: number
    - learning_rate: number
    - training_images: array[string]
  - trigger_word: string (palabra para activar en prompt)
  - preview_images: array[string]
  - metadata: JSONB
  - created_at: timestamp
  - updated_at: timestamp

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

### TextGeneration

```yaml
Entidad: TextGeneration
Descripción: Generación de texto/copy
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - job_id: UUID (FK a GenerationJob, opcional)
  - campaign_id: UUID (FK, opcional)
  - type: enum [copy, title, description, hashtags, cta, full_post]
  - prompt: text (instrucción al LLM)
  - context: JSONB (datos de marca, producto, brief)
  - output: text
  - variations: array[text] (si se generaron múltiples)
  - model_used: string
  - tokens_used: integer
  - status: enum [pending, completed, failed]
  - created_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con GenerationJob
  - N:1 con Campaign
```

---

## Funcionalidades

### F-004.1: Generación de Imágenes

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-004.1.1 | Text-to-Image | Generar imagen desde prompt | Alta |
| F-004.1.2 | Image-to-Image | Transformar imagen existente | Alta |
| F-004.1.3 | Inpainting | Editar partes de una imagen | Media |
| F-004.1.4 | Upscaling | Aumentar resolución | Alta |
| F-004.1.5 | Batch generation | Generar múltiples variaciones | Alta |

### F-004.2: Generación de Texto

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-004.2.1 | Copy generation | Generar textos publicitarios | Alta |
| F-004.2.2 | Hashtag generation | Sugerir hashtags relevantes | Media |
| F-004.2.3 | Title generation | Crear títulos/headlines | Alta |
| F-004.2.4 | Tone adaptation | Ajustar tono según brief | Alta |

### F-004.3: Workflows

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-004.3.1 | Plantillas predefinidas | Workflows listos para usar | Alta |
| F-004.3.2 | Ejecutar workflow | Correr workflow con parámetros | Alta |
| F-004.3.3 | Crear plantillas | Admin puede crear nuevos workflows | Media |
| F-004.3.4 | Previsualizar | Ver ejemplo antes de ejecutar | Media |

### F-004.4: Modelos Personalizados

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-004.4.1 | Registrar LoRA | Subir modelo entrenado | Alta |
| F-004.4.2 | Entrenar LoRA | Iniciar entrenamiento (básico) | Media |
| F-004.4.3 | Asociar a marca | Vincular modelo con brand | Alta |
| F-004.4.4 | Selector de modelos | Elegir LoRAs en generación | Alta |

### F-004.5: Cola de Tareas

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-004.5.1 | Encolar job | Agregar tarea a la cola | Alta |
| F-004.5.2 | Priorizar | Ajustar prioridad de jobs | Media |
| F-004.5.3 | Monitor | Ver estado de cola | Alta |
| F-004.5.4 | Cancelar | Cancelar job pendiente | Media |
| F-004.5.5 | Reintentar | Re-ejecutar job fallido | Media |

---

## Workflows Predefinidos (MVP)

### WF-001: Fotografía Sintética de Producto

```yaml
Nombre: product_photo_synthetic
Descripción: Genera fotos de producto en contextos comerciales
Inputs:
  - product_description: string
  - reference_images: array[string] (opcional)
  - background: string (white, lifestyle, custom)
  - style: string (minimalist, premium, casual)
  - brand_colors: array[string]
  - lora_id: UUID (opcional)

Outputs:
  - 5 variaciones del producto
  - Formato: PNG 1024x1024
  - Fondo transparente disponible

ComfyUI Nodes:
  - SDXL Base
  - ControlNet (si hay referencia)
  - IP-Adapter (consistencia)
  - Background Removal
  - Upscaler
```

### WF-002: Post para Redes Sociales

```yaml
Nombre: social_media_post
Descripción: Genera imagen + copy para redes
Inputs:
  - brief: object (objetivo, audiencia, tono)
  - product_id: UUID (opcional)
  - channel: string (instagram, facebook, linkedin)
  - format: string (post, story, carousel)
  - brand_id: UUID

Outputs:
  - 3-5 variaciones de imagen
  - Copy sugerido por variación
  - Hashtags recomendados

Proceso:
  1. Cargar identidad de marca
  2. Generar imagen base con SDXL + LoRA
  3. Aplicar composición según formato
  4. Generar copy con LLM
  5. Combinar outputs
```

### WF-003: Variaciones de Anuncio

```yaml
Nombre: ad_variations
Descripción: Genera múltiples versiones para A/B testing
Inputs:
  - base_image: string (URL o asset_id)
  - variations_count: number
  - variation_type: string (color, background, composition)

Outputs:
  - N variaciones según configuración
  - Metadatos de diferencias

Uso:
  - Testing de creatividades
  - Adaptaciones por canal
```

### WF-004: Avatar/Influencer Virtual

```yaml
Nombre: virtual_avatar
Descripción: Genera imágenes consistentes de un personaje
Inputs:
  - character_lora_id: UUID
  - pose: string (standing, sitting, action)
  - outfit: string
  - background: string
  - expression: string

Outputs:
  - Imagen del avatar
  - Consistencia facial garantizada

Técnicas:
  - IP-Adapter para consistencia
  - ControlNet OpenPose para poses
  - LoRA específico del personaje
```

---

## Arquitectura de Integración ComfyUI

```yaml
Componentes:
  Backend (NestJS):
    - GenerationService: Lógica de negocio
    - QueueService: Gestión de cola (Bull)
    - ComfyUIClient: Cliente HTTP para ComfyUI

  ComfyUI Server:
    - API REST nativa o ComfyDeploy
    - Websocket para progreso
    - Storage compartido para outputs

Flujo:
  1. Backend recibe solicitud de generación
  2. Valida permisos y límites del tenant
  3. Construye payload del workflow
  4. Encola job en Bull/Redis
  5. Worker toma job y llama a ComfyUI
  6. ComfyUI ejecuta workflow
  7. Worker recibe resultado y crea Asset
  8. Notifica completion via websocket
```

### Ejemplo de Llamada a ComfyUI

```typescript
interface ComfyUIRequest {
  workflow_id: string;
  inputs: {
    positive_prompt: string;
    negative_prompt: string;
    seed: number;
    steps: number;
    cfg_scale: number;
    width: number;
    height: number;
    lora_name?: string;
    lora_strength?: number;
    controlnet_image?: string;
  };
  webhook_url: string;
}

// Respuesta
interface ComfyUIResponse {
  job_id: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  outputs?: {
    images: string[]; // URLs
  };
  error?: string;
}
```

---

## API Endpoints

```yaml
Base: /api/v1/generation

# Jobs
POST   /jobs                    # Crear job de generación
GET    /jobs                    # Listar jobs del usuario
GET    /jobs/:id                # Detalle de job
DELETE /jobs/:id                # Cancelar job
POST   /jobs/:id/retry          # Reintentar job fallido

# Quick Generate (shortcuts)
POST   /generate/image          # Generación rápida de imagen
POST   /generate/text           # Generación rápida de texto
POST   /generate/batch          # Batch de imágenes

# Workflows
GET    /workflows               # Listar plantillas disponibles
GET    /workflows/:id           # Detalle de plantilla
POST   /workflows               # Crear plantilla (admin)
PUT    /workflows/:id           # Editar plantilla
POST   /workflows/:id/execute   # Ejecutar workflow

# Custom Models
GET    /models                  # Listar modelos del tenant
GET    /models/:id              # Detalle de modelo
POST   /models                  # Registrar modelo
DELETE /models/:id              # Eliminar modelo
POST   /models/train            # Iniciar entrenamiento

# Queue Management (admin)
GET    /queue/status            # Estado de la cola
GET    /queue/jobs              # Jobs en cola
POST   /queue/jobs/:id/priority # Cambiar prioridad
```

---

## Reglas de Negocio

```yaml
RN-004.1:
  Descripción: Generaciones limitadas por plan del tenant
  Validación: Verificar cuota antes de encolar
  Acción: Rechazar si límite alcanzado

RN-004.2:
  Descripción: LoRA de marca se aplica automáticamente
  Comportamiento: Si brand tiene LoRA y no se especifica otro, usar el de marca

RN-004.3:
  Descripción: Jobs prioritarios para planes premium
  Cálculo: priority_base + plan_bonus

RN-004.4:
  Descripción: Outputs se almacenan 30 días mínimo
  Política: Assets generados tienen retención mínima

RN-004.5:
  Descripción: Entrenamiento requiere mínimo 10 imágenes
  Validación: Verificar cantidad antes de iniciar

RN-004.6:
  Descripción: Negative prompts por defecto
  Comportamiento: Agregar prompts negativos estándar de calidad
```

---

## Dependencias

```yaml
Dependencias de Módulos:
  - PMC-001 Tenants: Límites y cuotas
  - PMC-002 CRM: Datos de marca y producto
  - PMC-003 Projects: Contexto de campaña
  - PMC-006 Assets: Almacenamiento de outputs

Dependencias del Catálogo:
  - @CATALOG_RATELIMIT:
      path: shared/catalog/rate-limiting/
      uso: Limitar generaciones por tenant/plan
      configuracion:
        - Starter: 10 generaciones/hora
        - Pro: 50 generaciones/hora
        - Business: 200 generaciones/hora
        - Enterprise: sin limite
      adaptar:
        - Usar Redis storage para produccion
        - Integrar con sistema de creditos/quotas
        - Configurar por tipo de operacion (imagen vs texto)
      docs: shared/catalog/rate-limiting/README.md

  - @CATALOG_WS:
      path: shared/catalog/websocket/
      uso: Progreso de generacion en tiempo real
      implementar:
        - Room por job (job:{jobId})
        - Emitir eventos: progress, completed, failed
        - Autenticacion de socket con JWT
      docs: shared/catalog/websocket/README.md

Servicios Externos:
  - ComfyUI: Motor de generación de imágenes (self-hosted)
  - OpenAI/Claude API: Generación de texto
  - Redis: Cola de tareas (BullMQ)
  - S3/MinIO: Almacenamiento de modelos y outputs

Referencia de Implementacion:
  - WebSocket gateway: projects/trading-platform/apps/api/src/websocket/
  - Rate limiting: projects/gamilit/apps/backend/src/common/guards/throttler.guard.ts
  - Bull queue patterns: Ver ADR-004-cola-tareas.md
```

---

## Consideraciones de Performance

```yaml
Optimizaciones:
  - Cola con workers paralelos según GPUs disponibles
  - Cache de modelos frecuentes en VRAM
  - Batch processing cuando sea posible
  - Compresión de outputs antes de storage

Monitoreo:
  - Tiempo promedio por tipo de workflow
  - Utilización de GPU
  - Cola depth y wait time
  - Tasa de errores
```

---

## Criterios de Aceptación

- [ ] Generación de imagen funciona con SDXL base
- [ ] Workflows predefinidos ejecutan correctamente
- [ ] LoRAs se cargan y aplican correctamente
- [ ] Cola procesa jobs en orden de prioridad
- [ ] Progreso se reporta via websocket
- [ ] Jobs fallidos permiten reintento
- [ ] Límites de tenant se respetan
- [ ] Outputs se almacenan como Assets
- [ ] Generación de texto produce copys coherentes

---

## Referencias

- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)
- [ComfyUI Documentation](https://github.com/comfyanonymous/ComfyUI)
- [ComfyDeploy](https://www.comfydeploy.com/)

---

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