rckrdmrd 74b5ed7f38 feat: Complete documentation update and orchestration configuration

- 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>

2026-01-07 05:38:31 -06:00

10 KiB

Raw Blame History

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

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

Entidades del Dominio

Project

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

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)

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

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

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

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)

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)

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)

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

Con Automatización (PMC-005)

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

UI/UX Consideraciones

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

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

10 KiB Raw Blame History