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

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

---

## Descripción General

El módulo CRM (Customer Relationship Management) gestiona clientes, marcas, productos y la relación entre estos elementos. Está diseñado para integrarse directamente con el motor de generación de contenido IA.

---

## Objetivos

1. Gestionar clientes y contactos de la agencia
2. Organizar marcas y productos por cliente
3. Almacenar identidad visual y lineamientos de marca
4. Registrar oportunidades comerciales
5. Conectar datos de CRM con generación de contenido

---

## Entidades del Dominio

### Client

```yaml
Entidad: Client
Descripción: Empresa/organización cliente de la agencia
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - name: string
  - legal_name: string
  - tax_id: string (RFC/NIF)
  - industry: string
  - size: enum [micro, small, medium, large, enterprise]
  - website: string
  - status: enum [prospect, active, inactive, churned]
  - notes: text
  - metadata: JSONB
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Tenant
  - 1:N con Contact
  - 1:N con Brand
  - 1:N con Opportunity
  - 1:N con Project
```

### Contact

```yaml
Entidad: Contact
Descripción: Persona de contacto en un cliente
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - client_id: UUID (FK)
  - first_name: string
  - last_name: string
  - email: string
  - phone: string
  - position: string
  - department: string
  - is_primary: boolean
  - status: enum [active, inactive]
  - metadata: JSONB
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Client
  - N:1 con Tenant
```

### Brand

```yaml
Entidad: Brand
Descripción: Marca de un cliente con su identidad visual
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - client_id: UUID (FK)
  - name: string
  - description: text
  - status: enum [active, inactive]
  - identity: JSONB
    - logo_url: string
    - logo_variations: array
    - primary_color: string
    - secondary_colors: array
    - typography: object
    - tone_of_voice: string (formal, casual, playful, etc.)
    - keywords: array
    - forbidden_words: array
    - visual_style: string
  - lora_models: array[UUID] (referencias a modelos entrenados)
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Client
  - N:1 con Tenant
  - 1:N con Product
  - 1:N con Campaign
  - N:N con CustomModel (LoRAs)
```

### Product

```yaml
Entidad: Product
Descripción: Producto o servicio de una marca
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - brand_id: UUID (FK)
  - name: string
  - sku: string
  - description: text
  - category: string
  - status: enum [active, discontinued, coming_soon]
  - attributes: JSONB
    - price: decimal
    - features: array
    - target_audience: string
    - use_cases: array
  - reference_images: array[string] (URLs)
  - lora_model_id: UUID (modelo específico del producto)
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Brand
  - N:1 con Tenant
  - 1:N con Asset (imágenes generadas)
```

### Opportunity

```yaml
Entidad: Opportunity
Descripción: Oportunidad de negocio/deal
Atributos:
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - client_id: UUID (FK)
  - contact_id: UUID (FK, opcional)
  - name: string
  - description: text
  - value: decimal
  - currency: string
  - stage: enum [lead, qualified, proposal, negotiation, won, lost]
  - probability: integer (0-100)
  - expected_close_date: date
  - actual_close_date: date
  - lost_reason: string
  - notes: text
  - created_at: timestamp
  - updated_at: timestamp

Relaciones:
  - N:1 con Client
  - N:1 con Contact
  - N:1 con Tenant
  - 1:N con Project (al convertirse)
```

---

## Funcionalidades

### F-002.1: Gestión de Clientes

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-002.1.1 | CRUD Clientes | Alta, edición, listado, eliminación | Alta |
| F-002.1.2 | Búsqueda y filtros | Por nombre, industria, estado | Alta |
| F-002.1.3 | Vista de cliente | Dashboard con marcas, contactos, proyectos | Alta |
| F-002.1.4 | Historial | Timeline de actividades y cambios | Media |

### F-002.2: Gestión de Contactos

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-002.2.1 | CRUD Contactos | Gestión de personas de contacto | Alta |
| F-002.2.2 | Contacto primario | Marcar contacto principal por cliente | Media |
| F-002.2.3 | Directorio | Vista consolidada de todos los contactos | Media |

### F-002.3: Gestión de Marcas

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-002.3.1 | CRUD Marcas | Alta y gestión de marcas | Alta |
| F-002.3.2 | Identidad visual | Definir colores, tipografía, tono | Alta |
| F-002.3.3 | Brand guidelines | Subir y almacenar guías de marca | Media |
| F-002.3.4 | Asociar LoRAs | Vincular modelos entrenados a marca | Alta |

### F-002.4: Gestión de Productos

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-002.4.1 | CRUD Productos | Alta y gestión de productos | Alta |
| F-002.4.2 | Imágenes referencia | Subir fotos del producto real | Alta |
| F-002.4.3 | Catálogo | Vista de productos por marca | Media |
| F-002.4.4 | Trigger generación | Botón "Generar pack de imágenes" | Alta |

### F-002.5: Pipeline de Ventas

| ID | Funcionalidad | Descripción | Prioridad |
|----|---------------|-------------|-----------|
| F-002.5.1 | CRUD Oportunidades | Gestión de deals | Media |
| F-002.5.2 | Kanban pipeline | Vista drag & drop por etapas | Media |
| F-002.5.3 | Convertir a proyecto | Crear proyecto desde oportunidad ganada | Media |

---

## Reglas de Negocio

```yaml
RN-002.1:
  Descripción: Cliente debe tener al menos un contacto
  Validación: Warning si no hay contactos, no bloquea

RN-002.2:
  Descripción: Marca requiere identidad visual mínima
  Validación: Al menos logo_url o primary_color definido

RN-002.3:
  Descripción: Producto hereda identidad de su marca
  Comportamiento: Si no tiene LoRA propio, usa el de la marca

RN-002.4:
  Descripción: Oportunidad ganada puede generar proyecto
  Acción: Botón "Crear proyecto" disponible en stage=won

RN-002.5:
  Descripción: Datos de marca se inyectan en generación
  Comportamiento: Al generar contenido, se cargan automáticamente colores, tono, keywords
```

---

## API Endpoints

```yaml
Base: /api/v1/crm

# Clients
POST   /clients
GET    /clients
GET    /clients/:id
PUT    /clients/:id
DELETE /clients/:id
GET    /clients/:id/brands
GET    /clients/:id/contacts
GET    /clients/:id/projects

# Contacts
POST   /contacts
GET    /contacts
GET    /contacts/:id
PUT    /contacts/:id
DELETE /contacts/:id

# Brands
POST   /brands
GET    /brands
GET    /brands/:id
PUT    /brands/:id
DELETE /brands/:id
GET    /brands/:id/products
POST   /brands/:id/loras          # Asociar LoRA
DELETE /brands/:id/loras/:loraId  # Desasociar LoRA

# Products
POST   /products
GET    /products
GET    /products/:id
PUT    /products/:id
DELETE /products/:id
POST   /products/:id/generate     # Trigger generación

# Opportunities
POST   /opportunities
GET    /opportunities
GET    /opportunities/:id
PUT    /opportunities/:id
DELETE /opportunities/:id
POST   /opportunities/:id/convert # Convertir a proyecto
```

---

## Integraciones

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

```yaml
Trigger: POST /products/:id/generate
Payload:
  product_id: UUID
  brand_id: UUID
  workflow_template: string
  options:
    quantity: number
    formats: array

Comportamiento:
  1. Cargar datos de producto (nombre, descripción, referencias)
  2. Cargar identidad de marca (colores, tono, LoRAs)
  3. Encolar job de generación con parámetros combinados
```

### Con Proyectos (PMC-003)

```yaml
Trigger: POST /opportunities/:id/convert
Crea:
  - Proyecto vinculado al cliente
  - Campaña inicial (opcional)
  - Copia brief de la oportunidad
```

---

## Dependencias

```yaml
Dependencias de Módulos:
  - PMC-001 Tenants: Aislamiento de datos
  - PMC-003 Projects: Conversión de oportunidades
  - PMC-004 Generation: Trigger de generación
  - PMC-006 Assets: Almacenamiento de logos y referencias

Servicios Externos:
  - Storage (S3/MinIO): Logos, imágenes de referencia
```

---

## UI/UX Consideraciones

```yaml
Vistas principales:
  - Lista de clientes con filtros y búsqueda
  - Ficha de cliente con tabs (info, contactos, marcas, proyectos)
  - Lista de marcas con preview de identidad
  - Ficha de producto con galería de referencias
  - Pipeline kanban de oportunidades

Acciones rápidas:
  - Desde producto: "Generar contenido"
  - Desde cliente: "Nueva marca", "Nuevo proyecto"
  - Desde oportunidad: "Convertir a proyecto"
```

---

## Criterios de Aceptación

- [ ] CRUD completo para Clients, Contacts, Brands, Products, Opportunities
- [ ] Identidad de marca se almacena y muestra correctamente
- [ ] Trigger de generación funciona desde producto
- [ ] Pipeline de oportunidades permite drag & drop
- [ ] Conversión de oportunidad crea proyecto
- [ ] Búsqueda y filtros funcionan en todas las listas
- [ ] RLS aísla datos por tenant

---

## Referencias

- [VISION-GENERAL.md](../00-vision-general/VISION-GENERAL.md)
- [ARQUITECTURA-TECNICA.md](../00-vision-general/ARQUITECTURA-TECNICA.md)

---

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