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

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

---

## Descripción General

El módulo de Projects gestiona proyectos y campañas de marketing. Cada proyecto agrupa múltiples campañas, y cada campaña contiene un brief estructurado que guía la generación de contenido.

---

## Objetivos

1. Organizar el trabajo por proyectos y campañas
2. Estructurar briefs creativos para generación de contenido
3. Gestionar estados y flujos de aprobación
4. Vincular proyectos con clientes y marcas del CRM
5. Coordinar entregas de assets generados

---

## Entidades del Dominio

### Project

```yaml
Entidad: Project
Descripción: Contenedor de campañas para un cliente/iniciativa
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - client_id: UUID (FK)
  - name: string
  - description: text
  - code: string (identificador corto, ej: "PRJ-2025-001")
  - status: enum [draft, active, on_hold, completed, cancelled]
  - start_date: date
  - end_date: date
  - budget: decimal
  - currency: string
  - owner_id: UUID (FK a User, responsable)
  - team_members: array[UUID] (usuarios asignados)
  - settings: JSONB
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant
  - N:1 con Client
  - N:1 con User (owner)
  - 1:N con Campaign
  - 1:N con Asset (assets del proyecto)
```

### Campaign

```yaml
Entidad: Campaign
Descripción: Campaña de marketing con brief y assets
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - project_id: UUID (FK)
  - brand_id: UUID (FK)
  - name: string
  - description: text
  - type: enum [social_media, performance_ads, catalog, landing, email, other]
  - status: enum [draft, briefing, in_production, review, approved, published, archived]
  - brief: JSONB (ver estructura abajo)
  - channels: array[string] (instagram, facebook, tiktok, google_ads, etc.)
  - start_date: date
  - end_date: date
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Project
  - N:1 con Brand
  - N:1 con Tenant
  - 1:N con GenerationJob
  - 1:N con Asset
```

### Brief (JSONB Structure)

```yaml
Estructura: Campaign.brief
Campos:
  objective:
    description: string (objetivo de la campaña)
    kpis: array[string] (métricas de éxito)

  audience:
    demographics: string
    psychographics: string
    pain_points: array[string]
    desires: array[string]

  messaging:
    main_message: string
    tone_of_voice: string (override del brand)
    call_to_action: string
    hashtags: array[string]

  visual:
    style: string (fotográfico, ilustrado, minimalista, etc.)
    mood: string (energético, sereno, profesional, etc.)
    color_palette: array[string] (override o adicionales)
    references: array[string] (URLs de referencias visuales)

  constraints:
    forbidden_words: array[string]
    forbidden_elements: array[string]
    legal_disclaimers: array[string]
    brand_guidelines_url: string

  deliverables:
    formats: array[object]
      - type: string (post, story, banner, etc.)
        dimensions: string (1080x1080, 1080x1920, etc.)
        quantity: number
    total_images: number
    total_copies: number
    variations_per_piece: number
```

### CampaignAsset

```yaml
Entidad: CampaignAsset (tabla pivote)
Descripción: Relación entre campaña y assets generados
Atributos:
  - id: UUID (PK)
  - campaign_id: UUID (FK)
  - asset_id: UUID (FK)
  - status: enum [pending, approved, rejected, revision_requested]
  - feedback: text
  - approved_by: UUID (FK a User)
  - approved_at: timestamp
  - created_at: timestamp
```

---

## Funcionalidades

### F-003.1: Gestión de Proyectos

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-003.1.1 | CRUD Proyectos | Alta, edición, listado, archivado | Alta |
| F-003.1.2 | Dashboard proyecto | Vista general con campañas y progreso | Alta |
| F-003.1.3 | Asignar equipo | Agregar/quitar miembros al proyecto | Media |
| F-003.1.4 | Timeline | Visualización de fechas y milestones | Media |

### F-003.2: Gestión de Campañas

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-003.2.1 | CRUD Campañas | Alta, edición, listado | Alta |
| F-003.2.2 | Editor de brief | Formulario estructurado | Alta |
| F-003.2.3 | Plantillas de brief | Briefs predefinidos por tipo | Media |
| F-003.2.4 | Duplicar campaña | Clonar con modificaciones | Media |

### F-003.3: Flujo de Trabajo

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-003.3.1 | Cambio de estado | Transiciones controladas | Alta |
| F-003.3.2 | Notificaciones | Alertar cambios de estado | Media |
| F-003.3.3 | Aprobación de assets | Aprobar/rechazar contenido | Alta |
| F-003.3.4 | Solicitar revisión | Pedir cambios con feedback | Alta |

### F-003.4: Generación de Contenido

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-003.4.1 | Lanzar generación | Desde brief, iniciar jobs | Alta |
| F-003.4.2 | Seleccionar plantillas | Elegir workflows de generación | Alta |
| F-003.4.3 | Monitor de progreso | Ver estado de generaciones | Alta |
| F-003.4.4 | Regenerar | Volver a generar con ajustes | Media |

---

## Máquina de Estados

### Project Status

```
draft ─────────────────────► active
  │                            │
  │                            ├───► on_hold ───► active
  │                            │
  │                            └───► completed
  │
  └────────────────────────────────► cancelled
```

### Campaign Status

```
draft ───► briefing ───► in_production ───► review ───► approved ───► published
  │           │              │                │            │
  │           │              └────────────────┘            │
  │           │              (revision_requested)          │
  │           │                                            │
  └───────────┴────────────────────────────────────────────┴───► archived
```

---

## Reglas de Negocio

```yaml
RN-003.1:
  Descripción: Proyecto requiere cliente asignado
  Validación: client_id NOT NULL

RN-003.2:
  Descripción: Campaña requiere brief mínimo para pasar a producción
  Validación: brief.objective y brief.deliverables definidos

RN-003.3:
  Descripción: Solo owner o admin puede cambiar estado del proyecto
  Autorización: Verificar rol del usuario

RN-003.4:
  Descripción: Assets aprobados no pueden eliminarse
  Validación: Bloquear DELETE si status=approved

RN-003.5:
  Descripción: Brief hereda identidad de la marca
  Comportamiento: Cargar colores, tono, etc. de Brand al crear campaña

RN-003.6:
  Descripción: Campaña solo puede publicarse si tiene assets aprobados
  Validación: Al menos 1 asset con status=approved
```

---

## API Endpoints

```yaml
Base: /api/v1/projects

# Projects
POST   /projects
GET    /projects
GET    /projects/:id
PUT    /projects/:id
DELETE /projects/:id
PATCH  /projects/:id/status
GET    /projects/:id/campaigns
GET    /projects/:id/assets
POST   /projects/:id/team        # Agregar miembro
DELETE /projects/:id/team/:userId

# Campaigns
POST   /campaigns
GET    /campaigns
GET    /campaigns/:id
PUT    /campaigns/:id
DELETE /campaigns/:id
PATCH  /campaigns/:id/status
PUT    /campaigns/:id/brief
GET    /campaigns/:id/assets
POST   /campaigns/:id/generate   # Lanzar generación

# Campaign Assets
POST   /campaigns/:id/assets/:assetId/approve
POST   /campaigns/:id/assets/:assetId/reject
POST   /campaigns/:id/assets/:assetId/request-revision

# Brief Templates
GET    /brief-templates
GET    /brief-templates/:id
POST   /brief-templates          # Admin only
PUT    /brief-templates/:id
DELETE /brief-templates/:id
```

---

## Integraciones

### Con CRM (PMC-002)

```yaml
Relación: Proyecto vinculado a Cliente y Marca
Datos heredados:
  - Identidad visual de Brand
  - Información de productos
  - Contactos para notificaciones
```

### Con Motor de Generación (PMC-004)

```yaml
Trigger: POST /campaigns/:id/generate
Payload:
  campaign_id: UUID
  workflow_templates: array[string]
  options:
    use_brand_lora: boolean
    quality: string

Respuesta:
  job_ids: array[UUID]
  estimated_time: number
```

### Con DAM (PMC-006)

```yaml
Assets generados se almacenan en DAM
Vinculación automática campaign_id → asset
Metadatos del brief copiados al asset
```

### Con Automatización (PMC-005)

```yaml
Eventos disparados:
  - campaign.status_changed → Notificaciones
  - campaign.approved → Preparar entrega
  - assets.all_approved → Trigger siguiente paso
```

---

## UI/UX Consideraciones

```yaml
Vistas principales:
  - Lista de proyectos con filtros (cliente, estado, fecha)
  - Board kanban de campañas por estado
  - Editor de brief con preview
  - Galería de assets de campaña con acciones

Acciones rápidas:
  - "Nueva campaña" desde proyecto
  - "Generar contenido" desde campaña
  - "Aprobar todo" en vista de revisión
  - "Descargar pack" de assets aprobados

Componentes:
  - BriefEditor: Formulario estructurado con secciones colapsables
  - AssetReviewer: Galería con zoom, comparación, acciones
  - ProgressTracker: Timeline visual de estado de campaña
```

---

## Criterios de Aceptación

- [ ] CRUD completo para Projects y Campaigns
- [ ] Editor de brief funcional con todas las secciones
- [ ] Transiciones de estado respetan reglas
- [ ] Generación se lanza correctamente desde campaña
- [ ] Flujo de aprobación de assets funciona
- [ ] Assets rechazados permiten regeneración
- [ ] Notificaciones se disparan en cambios de estado
- [ ] Plantillas de brief funcionan correctamente

---

## Referencias

- [VISION-GENERAL.md](../00-vision-general/VISION-GENERAL.md)
- [PMC-002-CRM.md](./PMC-002-CRM.md)
- [PMC-004-GENERATION.md](./PMC-004-GENERATION.md)

---

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