388 lines
9.3 KiB
Markdown
388 lines
9.3 KiB
Markdown
# 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
|