---
id: "PMC-006-ASSETS"
title: "PMC-006: Módulo de Assets (DAM)"
type: "Module Definition"
epic: "PMC-006"
status: "Draft"
project: "platform_marketing_content"
version: "1.0.0"
created_date: "2026-01-04"
updated_date: "2026-01-04"
---
# PMC-006: Módulo de Assets (DAM)

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

---

## Descripción General

El módulo de Assets implementa un Digital Asset Management (DAM) simplificado para almacenar, organizar y gestionar todos los recursos digitales generados o subidos a la plataforma: imágenes, copys, videos, modelos IA, y documentos.

---

## Objetivos

1. Centralizar todos los activos digitales del tenant
2. Organizar assets por cliente, campaña, tipo
3. Gestionar versiones y estados de aprobación
4. Facilitar búsqueda y descubrimiento de assets
5. Controlar acceso y permisos por rol

---

## Entidades del Dominio

### Asset

```yaml
Entidad: Asset
Descripción: Recurso digital almacenado en la plataforma
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - name: string
  - description: text
  - type: enum [image, copy, video, document, model, template]
  - mime_type: string
  - file_path: string (ruta en storage)
  - file_size: bigint (bytes)
  - dimensions: JSONB (width, height para imágenes/videos)
  - duration: integer (segundos, para video/audio)
  - status: enum [draft, pending_review, approved, rejected, archived]
  - visibility: enum [private, team, client]
  - source: enum [generated, uploaded, imported]
  - generation_job_id: UUID (FK, si fue generado)
  - metadata: JSONB
    - prompt: string (si fue generado)
    - model_used: string
    - seed: number
    - parameters: object
  - tags: array[string]
  - created_by: UUID (FK a User)
  - created_at: timestamp
  - updated_at: timestamp
  - deleted_at: timestamp (soft delete)

Relaciones:
  - N:1 con Tenant
  - N:1 con User (creator)
  - N:1 con GenerationJob
  - N:N con Campaign
  - N:N con Collection
  - 1:N con AssetVersion
```

### AssetVersion

```yaml
Entidad: AssetVersion
Descripción: Versión histórica de un asset
Atributos:
  - id: UUID (PK)
  - asset_id: UUID (FK)
  - version_number: integer
  - file_path: string
  - file_size: bigint
  - changes_description: text
  - created_by: UUID (FK)
  - created_at: timestamp

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

### Collection

```yaml
Entidad: Collection
Descripción: Agrupación lógica de assets
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - name: string
  - description: text
  - type: enum [manual, smart, campaign, brand]
  - smart_filters: JSONB (criterios para smart collections)
  - cover_asset_id: UUID (FK, opcional)
  - is_public: boolean
  - created_by: UUID (FK)
  - created_at: timestamp
  - updated_at: timestamp

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

### AssetComment

```yaml
Entidad: AssetComment
Descripción: Comentario o feedback sobre un asset
Atributos:
  - id: UUID (PK)
  - asset_id: UUID (FK)
  - user_id: UUID (FK)
  - content: text
  - position: JSONB (x, y para comentarios en imagen)
  - is_resolved: boolean
  - parent_id: UUID (FK, para respuestas)
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Asset
  - N:1 con User
  - Self-referencial (parent/children)
```

### Download

```yaml
Entidad: Download
Descripción: Registro de descargas de assets
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - asset_id: UUID (FK, opcional - puede ser colección)
  - collection_id: UUID (FK, opcional)
  - user_id: UUID (FK)
  - download_type: enum [single, batch, collection]
  - format: string (original, converted)
  - ip_address: string
  - user_agent: string
  - created_at: timestamp

Relaciones:
  - N:1 con Asset
  - N:1 con Collection
  - N:1 con User
```

---

## Funcionalidades

### F-006.1: Gestión de Assets

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-006.1.1 | Upload | Subir archivos manualmente | Alta |
| F-006.1.2 | Ver asset | Detalle con preview y metadata | Alta |
| F-006.1.3 | Editar metadata | Nombre, descripción, tags | Alta |
| F-006.1.4 | Eliminar | Soft delete con papelera | Alta |
| F-006.1.5 | Restaurar | Recuperar de papelera | Media |

### F-006.2: Organización

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-006.2.1 | Colecciones | Agrupar assets manualmente | Alta |
| F-006.2.2 | Smart collections | Colecciones automáticas por criterios | Media |
| F-006.2.3 | Tags | Etiquetar assets | Alta |
| F-006.2.4 | Filtros | Filtrar por tipo, estado, fecha, etc. | Alta |

### F-006.3: Búsqueda

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-006.3.1 | Búsqueda texto | Por nombre, descripción, tags | Alta |
| F-006.3.2 | Filtros avanzados | Combinar múltiples criterios | Alta |
| F-006.3.3 | Búsqueda por similar | Encontrar imágenes similares | Baja |

### F-006.4: Versiones y Aprobación

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-006.4.1 | Versionar | Subir nueva versión de asset | Media |
| F-006.4.2 | Comparar versiones | Ver diferencias | Baja |
| F-006.4.3 | Aprobar/Rechazar | Cambiar estado de revisión | Alta |
| F-006.4.4 | Comentarios | Feedback sobre assets | Alta |

### F-006.5: Descargas y Exportación

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-006.5.1 | Descargar individual | Bajar un asset | Alta |
| F-006.5.2 | Descargar batch | Bajar múltiples como ZIP | Alta |
| F-006.5.3 | Convertir formato | Descargar en formato diferente | Media |
| F-006.5.4 | Enlace temporal | URL con expiración | Media |

---

## Tipos de Assets Soportados

```yaml
Imágenes:
  Formatos: PNG, JPG, JPEG, WebP, GIF, SVG
  Max size: 50MB
  Procesamiento:
    - Generación de thumbnails
    - Extracción de dimensiones
    - Optimización automática

Copys/Textos:
  Tipos: Copy publicitario, título, descripción, hashtags
  Almacenamiento: En BD + archivo .txt opcional
  Metadata: Tone, language, character count

Videos:
  Formatos: MP4, MOV, WebM
  Max size: 500MB
  Procesamiento:
    - Generación de thumbnail
    - Extracción de duración
    - Preview de baja resolución

Documentos:
  Formatos: PDF, DOC, DOCX
  Max size: 100MB
  Uso: Brand guidelines, briefs, contratos

Modelos IA:
  Tipos: LoRA (.safetensors), Checkpoint, Embedding
  Max size: 10GB
  Metadata: Base model, trigger word, training params

Templates:
  Tipos: Workflow ComfyUI, plantillas de brief
  Formato: JSON
```

---

## Storage Structure

```yaml
S3/MinIO Bucket Structure:
  {bucket}/
    ├── {tenant_slug}/
    │   ├── assets/
    │   │   ├── images/
    │   │   │   ├── {year}/
    │   │   │   │   ├── {month}/
    │   │   │   │   │   ├── {asset_id}/
    │   │   │   │   │   │   ├── original.{ext}
    │   │   │   │   │   │   ├── thumb_200.jpg
    │   │   │   │   │   │   ├── thumb_800.jpg
    │   │   │   │   │   │   └── versions/
    │   │   │   │   │   │       ├── v1.{ext}
    │   │   │   │   │   │       └── v2.{ext}
    │   │   ├── videos/
    │   │   ├── documents/
    │   │   └── copies/
    │   ├── models/
    │   │   ├── loras/
    │   │   ├── checkpoints/
    │   │   └── embeddings/
    │   └── temp/
    │       └── (archivos temporales, limpiados periódicamente)
```

---

## API Endpoints

```yaml
Base: /api/v1/assets

# Assets CRUD
POST   /assets/upload           # Subir archivo(s)
GET    /assets                  # Listar con filtros y paginación
GET    /assets/:id              # Detalle de asset
PUT    /assets/:id              # Actualizar metadata
DELETE /assets/:id              # Soft delete

# Bulk operations
POST   /assets/bulk/move        # Mover a colección
POST   /assets/bulk/tag         # Agregar tags
POST   /assets/bulk/delete      # Eliminar múltiples
POST   /assets/bulk/status      # Cambiar estado

# Versions
GET    /assets/:id/versions     # Listar versiones
POST   /assets/:id/versions     # Subir nueva versión
GET    /assets/:id/versions/:v  # Obtener versión específica

# Status & Approval
PATCH  /assets/:id/status       # Cambiar estado
POST   /assets/:id/approve      # Aprobar
POST   /assets/:id/reject       # Rechazar con feedback

# Comments
GET    /assets/:id/comments     # Listar comentarios
POST   /assets/:id/comments     # Agregar comentario
PUT    /assets/:id/comments/:cid # Editar comentario
DELETE /assets/:id/comments/:cid # Eliminar comentario

# Downloads
GET    /assets/:id/download     # Descargar asset
POST   /assets/download/batch   # Descargar múltiples (ZIP)
POST   /assets/:id/share        # Generar enlace temporal

# Collections
GET    /collections             # Listar colecciones
POST   /collections             # Crear colección
GET    /collections/:id         # Detalle de colección
PUT    /collections/:id         # Actualizar colección
DELETE /collections/:id         # Eliminar colección
POST   /collections/:id/assets  # Agregar assets
DELETE /collections/:id/assets  # Quitar assets

# Search
POST   /assets/search           # Búsqueda avanzada
GET    /assets/tags             # Listar tags usados
```

---

## Reglas de Negocio

```yaml
RN-006.1:
  Descripción: Assets generados heredan metadata del job
  Comportamiento: Copiar prompt, modelo, parámetros automáticamente

RN-006.2:
  Descripción: Thumbnails se generan automáticamente
  Tamaños: 200px y 800px de ancho, manteniendo aspect ratio

RN-006.3:
  Descripción: Soft delete retiene archivos 30 días
  Acción: Cron job limpia después del período

RN-006.4:
  Descripción: Versionado mantiene historial completo
  Límite: Máximo 10 versiones por asset

RN-006.5:
  Descripción: Links temporales expiran según configuración
  Default: 7 días, máximo 30 días

RN-006.6:
  Descripción: Storage cuenta contra cuota del tenant
  Validación: Verificar límite antes de upload
```

---

## UI/UX Consideraciones

```yaml
Vistas principales:
  - Grid view: Thumbnails en cuadrícula
  - List view: Lista con metadata
  - Detail view: Asset grande con panel de info

Componentes:
  - AssetUploader: Drag & drop, multi-file
  - AssetPreview: Lightbox con navegación
  - AssetFilters: Panel de filtros colapsable
  - CollectionPicker: Modal para agregar a colección
  - CommentPanel: Sidebar con comentarios

Acciones rápidas:
  - Quick preview (spacebar)
  - Quick download (d)
  - Quick approve (a)
  - Add to collection (c)
```

---

## Dependencias

```yaml
Dependencias de Módulos:
  - PMC-001 Tenants: Cuotas de storage
  - PMC-003 Projects: Vinculación con campañas
  - PMC-004 Generation: Assets generados

Servicios Externos:
  - S3/MinIO: Almacenamiento de archivos
  - Sharp: Procesamiento de imágenes
  - FFmpeg: Procesamiento de video (opcional)

Dependencias del Catálogo:
  - (ninguna directa)
```

---

## Consideraciones de Performance

```yaml
Optimizaciones:
  - Lazy loading de thumbnails
  - Paginación con cursor para grandes volúmenes
  - CDN para servir assets estáticos
  - Compresión de uploads grandes
  - Pre-signed URLs para uploads directos a S3

Índices BD:
  - tenant_id + type + status
  - tenant_id + created_at
  - tenant_id + tags (GIN index)
  - Full-text search en name, description
```

---

## Criterios de Aceptación

- [ ] Upload funciona con drag & drop y file picker
- [ ] Thumbnails se generan automáticamente
- [ ] Búsqueda y filtros funcionan correctamente
- [ ] Colecciones permiten organizar assets
- [ ] Versionado mantiene historial
- [ ] Flujo de aprobación funciona
- [ ] Descargas individuales y batch funcionan
- [ ] Links temporales se generan y expiran
- [ ] Comentarios se pueden agregar y resolver
- [ ] Storage se cuenta contra cuota

---

## Referencias

- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)
- [GLOSARIO.md](../00-vision-general/GLOSARIO.md) - Definición de DAM

---

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