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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
• ComfyUI Documentation
• ComfyDeploy

---

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