# MODELO DE DOMINIO: CRM

**Módulos:** MGN-009 (CRM Básico)
**Fecha:** 2025-11-24
**Referencia Odoo:** crm
**Referencia Gamilit:** No implementado

---

## Diagrama de Entidades (Texto UML)

```
[Lead]
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - company_id: UUID (FK)
  - name: String
  - contact_name: String
  - email: String
  - phone: String
  - partner_id: UUID (FK)
  - source: ENUM (website, referral, campaign, cold_call)
  - status: ENUM (new, qualified, converted, lost)
  - stage_id: UUID (FK)
  - assigned_to: UUID (FK user)
  - expected_revenue: Decimal
  - probability: Integer
  - expected_closing: Date
  - lost_reason: String

  1 <----> * [Activity]
  1 <----> * [SaleOrder] (conversión)

[Stage]
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - team_id: UUID (FK)
  - name: String
  - sequence: Integer
  - probability: Integer
  - is_won: Boolean
  - is_lost: Boolean

[SalesTeam]
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - company_id: UUID (FK)
  - name: String
  - leader_id: UUID (FK user)
  - target_amount: Decimal

  1 <----> * [User] (members)
  1 <----> * [Stage]

[Activity]
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - lead_id: UUID (FK)
  - user_id: UUID (FK)
  - activity_type: ENUM (call, meeting, email, task)
  - summary: String
  - description: Text
  - date: Date
  - status: ENUM (pending, completed, overdue)

[LeadTag]
  - id: UUID (PK)
  - tenant_id: UUID (FK)
  - name: String
  - color: String

  * <----> * [Lead] (many-to-many)
```

## Entidades Principales

### 1. Lead (Oportunidad de Venta)
**Descripción:** Contacto interesado o oportunidad de venta.

**Atributos:**
- `id`: UUID
- `name`: Nombre de la oportunidad (ej: "Proyecto Oficinas Centro")
- `contact_name`: Nombre del contacto
- `email`: Email de contacto
- `phone`: Teléfono
- `partner_id`: Partner asociado (si ya existe)
- `source`: website, referral, campaign, cold_call
- `status`: new, qualified, converted, lost
- `stage_id`: Etapa actual en pipeline
- `assigned_to`: Usuario asignado
- `expected_revenue`: Ingreso esperado
- `probability`: Probabilidad de cierre (0-100%)
- `expected_closing`: Fecha esperada de cierre

**Relaciones:**
- 1 Lead → N Activities
- 1 Lead → 1 SaleOrder (conversión)
- N Leads → 1 Partner

**Patrón Odoo:** crm.lead
**Diferencia Lead vs Opportunity:**
- Lead: Contacto no calificado
- Opportunity: Lead calificado con probabilidad de venta

### 2. Stage (Etapa de Pipeline)
**Descripción:** Etapa en el pipeline de ventas.

**Atributos:**
- `id`: UUID
- `team_id`: Equipo de ventas propietario
- `name`: Nombre (ej: "Prospección", "Calificación", "Propuesta")
- `sequence`: Orden de etapa
- `probability`: Probabilidad por defecto (%)
- `is_won`: Marca si es etapa ganada
- `is_lost`: Marca si es etapa perdida

**Relaciones:**
- N Stages → 1 SalesTeam
- 1 Stage → N Leads

**Patrón Odoo:** crm.stage
**Pipeline típico:**
1. Prospección (10%)
2. Calificación (20%)
3. Propuesta (40%)
4. Negociación (60%)
5. Ganado (100%) o Perdido (0%)

### 3. SalesTeam (Equipo de Ventas)
**Descripción:** Equipo de ventas con vendedores asignados.

**Atributos:**
- `id`: UUID
- `company_id`: Empresa
- `name`: Nombre del equipo
- `leader_id`: Líder del equipo
- `target_amount`: Meta de ventas (mensual/anual)

**Relaciones:**
- 1 SalesTeam → N Users (miembros)
- 1 SalesTeam → N Stages
- 1 SalesTeam → N Leads

**Patrón Odoo:** crm.team
**Equipos típicos:**
- Ventas Corporativas
- Ventas Retail
- Ventas Online

### 4. Activity (Actividad)
**Descripción:** Actividad de seguimiento para lead.

**Atributos:**
- `id`: UUID
- `lead_id`: Lead asociado
- `user_id`: Usuario asignado
- `activity_type`: call, meeting, email, task
- `summary`: Resumen
- `description`: Descripción detallada
- `date`: Fecha programada
- `status`: pending, completed, overdue

**Relaciones:**
- N Activities → 1 Lead
- N Activities → 1 User

**Patrón Odoo:** mail.activity (especializado para CRM)
**Tipos:**
- call: Llamada telefónica
- meeting: Reunión presencial/virtual
- email: Envío de email
- task: Tarea general

### 5. LeadTag (Etiqueta de Lead)
**Descripción:** Etiquetas para categorizar leads.

**Atributos:**
- `id`: UUID
- `name`: Nombre (ej: "Hot", "Enterprise", "SMB")
- `color`: Color para UI

**Relaciones:**
- N LeadTags ←→ N Leads

**Patrón Odoo:** crm.tag
**Tags típicos:**
- Hot/Warm/Cold (temperatura)
- Enterprise/SMB (tamaño)
- Industry tags (construcción, manufactura, etc.)

## Reglas de Negocio

### RN-CRM-001: Flujo de Lead
- Lead comienza en stage inicial del team
- Lead avanza/retrocede entre stages (drag & drop)
- Al llegar a stage con is_won=true, marca como 'won'
- Al llegar a stage con is_lost=true, marca como 'lost'

### RN-CRM-002: Calificación de Lead
- Lead nuevo (new) → Lead calificado (qualified)
- Calificación requiere validar: contacto, presupuesto, autoridad, necesidad
- Solo leads calificados pueden convertirse a oportunidad

### RN-CRM-003: Conversión a Cotización
- Opportunity puede generar Quotation (MGN-007)
- Quotation hereda: partner, productos, expected_revenue
- Vínculo bidireccional opportunity ←→ quotation

### RN-CRM-004: Asignación Automática
- Leads pueden asignarse automáticamente por round-robin
- O por carga de trabajo (# leads activos por vendedor)
- O manualmente por líder de equipo

### RN-CRM-005: Scoring de Lead
- Scoring automático basado en criterios:
  - Tamaño de empresa (+20 puntos)
  - Industria target (+15 puntos)
  - Interacción reciente (+10 puntos)
  - Email abierto (+5 puntos)
- Score > 70: Hot lead

### RN-CRM-006: Actividades Vencidas
- Sistema marca activities como 'overdue' si date < HOY
- Notificaciones automáticas de actividades vencidas
- Dashboard muestra actividades overdue por usuario

## Casos de Uso Principales

1. **UC-CRM-001:** Usuario crea nuevo lead desde formulario web
2. **UC-CRM-002:** Usuario califica lead (new → qualified)
3. **UC-CRM-003:** Usuario mueve oportunidad entre stages
4. **UC-CRM-004:** Usuario programa llamada de seguimiento
5. **UC-CRM-005:** Usuario convierte oportunidad a cotización
6. **UC-CRM-006:** Usuario marca oportunidad como ganada/perdida
7. **UC-CRM-007:** Gerente consulta embudo de ventas (funnel)
8. **UC-CRM-008:** Sistema asigna lead automáticamente a vendedor

## Validaciones y Constraints

```sql
-- Probability entre 0 y 100
CHECK (probability >= 0 AND probability <= 100)

-- Expected revenue >= 0
CHECK (expected_revenue >= 0)

-- Stage sequence > 0
CHECK (sequence > 0)

-- Stage no puede ser won y lost simultáneamente
CHECK (NOT (is_won AND is_lost))

-- Activity date debe ser presente o futuro
CHECK (date >= CURRENT_DATE)

-- Email format válido
CHECK (email ~ '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}$')
```

## Índices Requeridos

```sql
CREATE INDEX idx_leads_stage_id ON crm.leads(stage_id);
CREATE INDEX idx_leads_assigned_to ON crm.leads(assigned_to);
CREATE INDEX idx_leads_status ON crm.leads(status);
CREATE INDEX idx_leads_expected_closing ON crm.leads(expected_closing);
CREATE INDEX idx_leads_partner_id ON crm.leads(partner_id);
CREATE INDEX idx_activities_lead_id ON crm.activities(lead_id);
CREATE INDEX idx_activities_user_id ON crm.activities(user_id);
CREATE INDEX idx_activities_status ON crm.activities(status);
CREATE INDEX idx_activities_date ON crm.activities(date);
```

## Integración con Otros Módulos

### Con MGN-003 (Catálogos)
- Lead puede crear Partner al calificarse
- Lead se vincula a Partner existente

### Con MGN-007 (Ventas)
- Opportunity → Quotation
- Quotation ganada → marca Opportunity como 'won'

### Con MGN-014 (Mensajería)
- Actividades son especializaciones de mail.activity
- Leads tienen chatter para comentarios

### Con MGN-012 (Reportes)
- Dashboard de CRM:
  - Embudo de ventas
  - Conversión rate
  - Revenue por stage
  - Actividades por usuario

## Referencias
- [ALCANCE-POR-MODULO.md - MGN-009](../../01-definicion-modulos/ALCANCE-POR-MODULO.md#mgn-009)
- [ADR-007: Database Design](../../adr/ADR-007-database-design.md)
- [odoo-crm-analysis.md](../../00-analisis-referencias/odoo/odoo-crm-analysis.md)