rckrdmrd
74b5ed7f38
- 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>
461 lines
12 KiB
Markdown
461 lines
12 KiB
Markdown
---
|
|
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
|