erp-core/docs/04-modelado/domain-models/crm-domain.md

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

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

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
• ADR-007: Database Design
• odoo-crm-analysis.md