erp-construccion/docs/02-definicion-modulos/MAI-010-crm-derechohabientes/_MAP.md

693 lines
19 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# _MAP: MAI-010 - CRM de Derechohabientes y Comercialización
**Épica:** MAI-010
**Nombre:** CRM de Derechohabientes y Comercialización
**Fase:** 1 - Alcance Inicial
**Presupuesto:** $25,000 MXN
**Story Points:** 35 SP
**Estado:** 📝 A crear
**Sprint:** Sprint 6 (Semanas 11-12)
**Última actualización:** 2025-11-17
**Prioridad:** P2
---
## 📋 Propósito
Gestión completa de derechohabientes/compradores y proceso de comercialización:
- Registro de derechohabientes/prospectos
- Estatus de cada vivienda: disponible, apartada, vendida, escriturada, entregada
- Seguimiento de expediente del crédito (documentos, avances, citas)
- Comunicación por WhatsApp/email con compradores
- Dashboard de comercialización y pipeline de ventas
**Integración clave:** Se vincula con Proyectos (MAI-002), Calidad/Postventa (MAI-009), INFONAVIT (MAI-011) y Contratos (MAI-012).
---
## 📁 Contenido
### Requerimientos Funcionales (Estimados: 5)
| ID | Título | Estado |
|----|--------|--------|
| RF-CRM-001 | Gestión de prospectos y derechohabientes | 📝 A crear |
| RF-CRM-002 | Control de estatus de viviendas y asignaciones | 📝 A crear |
| RF-CRM-003 | Seguimiento de expediente de crédito | 📝 A crear |
| RF-CRM-004 | Comunicación multicanal con clientes | 📝 A crear |
| RF-CRM-005 | Dashboard de comercialización y reportes | 📝 A crear |
### Especificaciones Técnicas (Estimadas: 5)
| ID | Título | RF | Estado |
|----|--------|----|--------|
| ET-CRM-001 | Modelo de datos de clientes y pipeline | RF-CRM-001 | 📝 A crear |
| ET-CRM-002 | Sistema de estados de vivienda y reservaciones | RF-CRM-002 | 📝 A crear |
| ET-CRM-003 | Gestión de documentos y checklist de crédito | RF-CRM-003 | 📝 A crear |
| ET-CRM-004 | Integración con WhatsApp y email | RF-CRM-004 | 📝 A crear |
| ET-CRM-005 | Analytics de ventas y embudo de conversión | RF-CRM-005 | 📝 A crear |
### Historias de Usuario (Estimadas: 7)
| ID | Título | SP | Estado |
|----|--------|----|--------|
| US-CRM-001 | Registrar prospecto desde formulario web | 5 | 📝 A crear |
| US-CRM-002 | Asignar vivienda a derechohabiente | 5 | 📝 A crear |
| US-CRM-003 | Dar seguimiento a expediente de crédito | 5 | 📝 A crear |
| US-CRM-004 | Enviar notificaciones por WhatsApp | 5 | 📝 A crear |
| US-CRM-005 | Programar y registrar citas con clientes | 5 | 📝 A crear |
| US-CRM-006 | Dashboard de comercialización y ventas | 5 | 📝 A crear |
| US-CRM-007 | Generar reporte de ventas por proyecto | 5 | 📝 A crear |
**Total Story Points:** 35 SP
### Implementación
📊 **Inventarios de trazabilidad:**
- [TRACEABILITY.yml](./implementacion/TRACEABILITY.yml) - Matriz completa de trazabilidad
- [DATABASE.yml](./implementacion/DATABASE.yml) - Objetos de base de datos
- [BACKEND.yml](./implementacion/BACKEND.yml) - Módulos backend
- [FRONTEND.yml](./implementacion/FRONTEND.yml) - Componentes frontend
### Pruebas
📋 Documentación de testing:
- [TEST-PLAN.md](./pruebas/TEST-PLAN.md) - Plan de pruebas
- [TEST-CASES.md](./pruebas/TEST-CASES.md) - Casos de prueba
---
## 🔗 Referencias
- **README:** [README.md](./README.md) - Descripción detallada de la épica
- **Fase 1:** [../README.md](../README.md) - Información de la fase completa
- **Módulo relacionado MVP:** Módulo 10 - CRM de Derechohabientes (MVP-APP.md)
---
## 📊 Métricas
| Métrica | Valor |
|---------|-------|
| **Presupuesto estimado** | $25,000 MXN |
| **Story Points estimados** | 35 SP |
| **Duración estimada** | 7 días |
| **Reutilización GAMILIT** | 30% (CRM básico, notificaciones) |
| **RF a implementar** | 5/5 |
| **ET a implementar** | 5/5 |
| **US a completar** | 7/7 |
---
## 🎯 Módulos Afectados
### Base de Datos
- **Schema:** `crm`, `sales`
- **Tablas principales:**
* `prospects` - Prospectos/leads
* `clients` - Derechohabientes/clientes
* `unit_assignments` - Asignación de viviendas a clientes
* `credit_files` - Expedientes de crédito
* `credit_documents` - Documentos del expediente
* `appointments` - Citas con clientes
* `communications` - Historial de comunicaciones
* `sales_pipeline` - Pipeline de ventas
- **ENUMs:**
* `prospect_source` (web, referral, event, social_media, infonavit_portal)
* `prospect_status` (new, contacted, qualified, lost, converted)
* `unit_status` (available, reserved, sold, titled, delivered, cancelled)
* `credit_status` (pre_approval, document_collection, under_review, approved, rejected, disbursed)
* `appointment_type` (first_visit, document_review, signature, delivery)
* `communication_channel` (whatsapp, email, sms, phone, in_person)
### Backend
- **Módulo:** `crm`, `sales`
- **Path:** `apps/backend/src/modules/crm/`
- **Services:** ProspectService, ClientService, CreditFileService, AppointmentService, CommunicationService, WhatsAppService
- **Controllers:** CRMController, SalesController, CreditFileController
- **Middlewares:** ClientAccessGuard, DataPrivacyMiddleware
### Frontend
- **Features:** `crm`, `sales`, `clients`
- **Path:** `apps/frontend/src/features/crm/`
- **Componentes:**
* ProspectList
* ProspectForm (lead capture)
* ClientProfile
* UnitSelector (disponibilidad de viviendas)
* CreditFileManager
* DocumentChecklistViewer
* AppointmentScheduler
* CommunicationHistory
* SalesPipeline (Kanban view)
* SalesDashboard
- **Stores:** crmStore, clientStore, salesStore
---
## 🏠 Gestión de Viviendas
### Estados de Vivienda
```mermaid
stateDiagram-v2
[*] --> Available
Available --> Reserved: Apartado
Reserved --> Sold: Venta formalizada
Reserved --> Available: Cancelación
Sold --> Titled: Escrituración
Titled --> Delivered: Entrega física
Delivered --> [*]
Available --> [*]: No vendida
```
| Estado | Descripción | Duración típica | Acciones permitidas |
|--------|-------------|-----------------|---------------------|
| **Disponible** | Vivienda lista para venta | - | Asignar a cliente, mostrar en portal |
| **Apartada** | Cliente pagó apartado | 15-30 días | Confirmar venta, cancelar apartado |
| **Vendida** | Contrato de compraventa firmado | 30-60 días | Iniciar trámite de crédito |
| **Escriturada** | Escritura firmada ante notario | 7-15 días | Programar entrega |
| **Entregada** | Entrega física al cliente | - | Activar postventa |
| **Cancelada** | Venta cancelada | - | Liberar vivienda |
---
### Información de Vivienda
```yaml
unit:
id: "UNIT-A-12"
project_id: "PROJ-001"
stage: "Etapa 1"
block: "Manzana A"
lot: "Lote 12"
prototype: "Tipo A - 2 recámaras"
area: 42.5 # m² construidos
price: 580000.00 # Precio de lista
status: "sold"
assignment:
client_id: "CLIENT-456"
reserved_date: "2025-09-15"
down_payment_amount: 5000.00
sold_date: "2025-10-01"
sale_price: 575000.00 # Precio negociado
financing_type: "infonavit"
credit_number: "INF-2025-123456"
timeline:
- date: "2025-09-15"
event: "Apartado"
notes: "Cliente pagó $5,000 de apartado"
- date: "2025-10-01"
event: "Venta formalizada"
notes: "Contrato firmado, precio $575,000"
- date: "2025-10-15"
event: "Trámite de crédito iniciado"
notes: "Expediente enviado a INFONAVIT"
- date: "2025-11-10"
event: "Crédito aprobado"
notes: "Monto aprobado: $575,000"
- date: "2025-11-20"
event: "Escrituración"
notes: "Escritura firmada ante notario"
expected: true
- date: "2025-12-01"
event: "Entrega programada"
expected: true
```
---
## 👥 Gestión de Prospectos y Clientes
### Pipeline de Ventas
```
LEADS (Prospectos)
CONTACTADOS
CALIFICADOS
INTERESADOS
APARTADO
VENTA FORMALIZADA
CRÉDITO APROBADO
ESCRITURADO
ENTREGADO
```
### Fuentes de Prospectos
| Fuente | Descripción | Calidad típica | Conversión |
|--------|-------------|----------------|------------|
| **Portal web** | Formulario de contacto en sitio web | Media | 10-15% |
| **INFONAVIT** | Portal Mi Cuenta INFONAVIT | Alta | 25-30% |
| **Eventos** | Expos de vivienda, ferias | Media-Alta | 15-20% |
| **Referidos** | Clientes actuales refieren conocidos | Muy Alta | 40-50% |
| **Redes sociales** | Facebook, Instagram ads | Baja-Media | 5-10% |
| **Call center** | Llamadas salientes | Baja | 3-5% |
---
### Ficha de Cliente
```yaml
client:
id: "CLIENT-456"
personal_info:
first_name: "María"
last_name: "González Hernández"
email: "maria.gonzalez@email.com"
phone: "+52 442 123 4567"
birth_date: "1988-05-15"
curp: "GOHM880515MQTNRR02"
rfc: "GOHM880515XX1"
marital_status: "married"
dependents: 2
employment:
company: "Empresa XYZ SA de CV"
position: "Administradora"
monthly_income: 18000.00
employment_years: 5
infonavit_number: "1234567890"
infonavit_points: 1250
address:
current_street: "Av. Principal 123"
current_city: "Querétaro"
current_state: "Querétaro"
current_zip: "76000"
origin:
source: "infonavit_portal"
campaign: "Campaña INFONAVIT Q4 2025"
captured_date: "2025-09-01"
captured_by: "Asesora Comercial: Laura Martínez"
status:
current: "sold"
qualification_score: 85 # Puntaje de calificación (0-100)
interested_in: ["Tipo A - 2 rec", "Tipo B - 3 rec"]
budget: 600000.00
financing_type: "infonavit"
timeline: "3_months" # Plazo esperado para compra
```
---
## 📋 Expediente de Crédito
### Checklist de Documentos
| Documento | Requerido por | Estatus | Archivo | Validado |
|-----------|---------------|---------|---------|----------|
| **INE (ambos lados)** | INFONAVIT | ✅ Recibido | `DOC-001.pdf` | Sí |
| **CURP** | INFONAVIT | ✅ Recibido | `DOC-002.pdf` | Sí |
| **Comprobante de domicilio** | INFONAVIT | ✅ Recibido | `DOC-003.pdf` | Sí |
| **Acta de matrimonio** | INFONAVIT | ⏳ Pendiente | - | - |
| **Actas de nacimiento de dependientes** | INFONAVIT | ⏳ Pendiente | - | - |
| **Constancia de percepciones** | INFONAVIT | ✅ Recibido | `DOC-006.pdf` | Sí |
| **Estados de cuenta bancarios (3 meses)** | Notaría | ✅ Recibido | `DOC-007.pdf` | Sí |
| **Solicitud de crédito firmada** | INFONAVIT | ✅ Recibido | `DOC-008.pdf` | Sí |
**Completitud:** 62.5% (5 de 8 documentos)
---
### Flujo de Trámite de Crédito
#### 1. Pre-calificación (Día 1)
**Objetivo:** Verificar que el cliente tiene puntos y capacidad de pago
- Verificación en portal INFONAVIT:
* Puntos acumulados: ✅ 1,250 pts (mínimo 1,080)
* Monto pre-aprobado: ✅ $600,000 (vivienda: $575,000)
* Edad: ✅ 37 años (máximo 64)
* Sin crédito INFONAVIT previo: ✅
**Resultado:** ✅ PRE-APROBADO
---
#### 2. Integración de Expediente (Días 2-15)
**Responsable:** Asesor comercial + cliente
**Actividades:**
- Solicitud de documentos al cliente
- Carga de documentos en sistema
- Validación de documentos:
* Vigencia (no mayor a 3 meses)
* Legibilidad
* Coincidencia de datos
- Seguimiento diario hasta completar 100%
**Herramientas:**
- Portal del cliente (puede subir documentos)
- WhatsApp (recordatorios automáticos)
- Email (checklist de documentos faltantes)
---
#### 3. Envío a INFONAVIT (Día 16)
**Responsable:** Coordinador de créditos
**Actividades:**
- Validación final de expediente completo
- Llenado de formatos oficiales
- Carga en portal INFONAVIT
- Generación de folio de trámite
**Resultado:** Folio `INF-2025-123456` generado
---
#### 4. Evaluación INFONAVIT (Días 17-30)
**Responsable:** INFONAVIT
**Proceso:**
- Validación de documentos
- Verificación de empleo
- Evaluación crediticia
- Valuación de vivienda
- Emisión de dictamen
**Estados posibles:**
-**Aprobado:** Monto autorizado, continuar a firma
- ⚠️ **Información adicional requerida:** Solicitar aclaraciones
-**Rechazado:** No cumple requisitos
**Seguimiento:** Consulta diaria de estatus en portal
---
#### 5. Formalización (Días 31-40)
**Actividades:**
- Firma de contrato de compraventa
- Firma de contrato de crédito INFONAVIT
- Pago de gastos notariales
- Firma de escritura ante notario
**Documentos generados:**
- Contrato de compraventa
- Escritura pública
- Póliza de garantía
---
#### 6. Dispersión de Crédito (Días 41-45)
**Proceso:**
- INFONAVIT transfiere monto a cuenta del vendedor
- Constructora confirma recepción de pago
- Actualización de estatus de vivienda: `titled`
---
#### 7. Entrega de Vivienda (Días 46-60)
**Actividades:**
- Programación de entrega
- Inspección final con cliente
- Firma de acta de entrega-recepción
- Entrega de llaves y documentos
- Actualización de estatus: `delivered`
**Módulo:** Vincula con MAI-009 (Calidad/Postventa)
---
## 💬 Comunicación con Clientes
### Canales de Comunicación
| Canal | Uso principal | Ventajas | Automatización |
|-------|---------------|----------|----------------|
| **WhatsApp** | Recordatorios, actualizaciones rápidas | Alto engagement, respuestas rápidas | Templates, mensajes programados |
| **Email** | Documentos formales, reportes | Trazabilidad, adjuntos | Workflows automáticos |
| **SMS** | Alertas urgentes | Alta tasa de lectura | Notificaciones automáticas |
| **Teléfono** | Consultas complejas, negociación | Contacto personal | Click-to-call desde CRM |
| **Portal web** | Self-service, seguimiento | 24/7 disponible | Notificaciones en app |
---
### Templates de WhatsApp
#### 1. Bienvenida a Prospecto
```
¡Hola {{first_name}}! 👋
Gracias por tu interés en {{project_name}}.
Soy {{advisor_name}}, tu asesora comercial. Estoy aquí para ayudarte a encontrar tu hogar ideal.
📍 Ubicación: {{project_location}}
🏠 Desde: ${{min_price}} MXN
📅 ¿Te gustaría agendar una visita?
Responde SÍ y te compartiremos los horarios disponibles.
```
---
#### 2. Recordatorio de Documentos Pendientes
```
Hola {{first_name}}, 📄
Para continuar con tu trámite de crédito nos faltan los siguientes documentos:
{{missing_documents_list}}
Puedes subirlos desde nuestro portal:
{{client_portal_link}}
O enviarlos por WhatsApp como foto o PDF.
¿Tienes alguna duda? Estoy para ayudarte 😊
```
---
#### 3. Actualización de Estatus de Crédito
```
¡Excelentes noticias {{first_name}}! 🎉
Tu crédito INFONAVIT ha sido *APROBADO* ✅
Monto autorizado: ${{approved_amount}} MXN
Folio: {{credit_number}}
Próximos pasos:
1⃣ Firma de contrato ({{appointment_date}})
2⃣ Trámite de escrituración
3⃣ Entrega de tu vivienda
¿Confirmas tu asistencia a la cita?
```
---
#### 4. Recordatorio de Cita
```
Hola {{first_name}}, 📅
Te recordamos tu cita para {{appointment_type}}:
📍 Lugar: {{location}}
🕐 Fecha: {{date}} a las {{time}}
👤 Con: {{advisor_name}}
Documentos a traer:
{{documents_list}}
¿Confirmas tu asistencia?
Para reprogramar, responde CAMBIAR CITA.
```
---
### Automatizaciones
**Workflows automáticos:**
1. **Nuevo prospecto:**
- Envío de WhatsApp de bienvenida (inmediato)
- Email con brochure del proyecto (+2 horas)
- Asignación a asesor comercial (+1 día)
2. **Documentos pendientes:**
- Recordatorio WhatsApp (+3 días sin subir documentos)
- Recordatorio email (+7 días)
- Escalamiento a coordinador (+10 días)
3. **Crédito aprobado:**
- Notificación WhatsApp (inmediato)
- Email formal con detalles (+30 min)
- SMS de confirmación (+1 hora)
4. **Próxima a entrega:**
- Email con checklist de entrega (-7 días)
- WhatsApp confirmación de fecha (-3 días)
- SMS recordatorio (-1 día)
---
## 📊 Dashboard de Comercialización
### KPIs Principales
| Métrica | Descripción | Cálculo | Meta |
|---------|-------------|---------|------|
| **Tasa de conversión** | % de prospectos que compran | (Ventas / Prospectos) × 100 | >15% |
| **Velocidad de ventas** | Viviendas vendidas por mes | Σ Ventas / Meses | Según inventario |
| **Tiempo promedio de cierre** | Días desde contacto hasta venta | Avg(Fecha venta - Fecha contacto) | <60 días |
| **Viviendas disponibles** | Inventario sin vender | Count(status=available) | Controlar rotación |
| **Viviendas apartadas** | En proceso de venta | Count(status=reserved) | Monitorear expiración |
| **Pipeline value** | Valor potencial de ventas | Σ (Precio × Probabilidad) | - |
| **Satisfacción del cliente** | NPS o CSAT | Encuestas post-venta | >4.5/5 |
---
### Embudo de Ventas
```
PROSPECTOS (500)
↓ 40% conversión
CONTACTADOS (200)
↓ 50% conversión
CALIFICADOS (100)
↓ 40% conversión
APARTADOS (40)
↓ 75% conversión
VENTAS (30)
↓ 95% conversión
ENTREGADOS (28)
Tasa de conversión final: 5.6% (28/500)
```
---
### Reportes
1. **Reporte semanal de ventas:**
- Ventas de la semana por proyecto
- Comparativo vs semana anterior
- Proyección para mes
2. **Reporte de inventario:**
- Disponibles por proyecto/etapa
- Apartados próximos a expirar
- Viviendas listas para entrega
3. **Reporte de pipeline:**
- Prospectos por etapa
- Valor potencial por etapa
- Acciones pendientes
4. **Reporte de asesores:**
- Ventas por asesor
- Prospectos asignados
- Tasa de conversión individual
---
## 💡 Casos de Uso Clave
### Prospecto desde Portal Web
**Flujo:**
1. **Captura (Día 1, 10:00 AM):**
- Prospecto llena formulario en sitio web
- Sistema crea registro automáticamente
- WhatsApp automático de bienvenida (+5 min)
- Email con brochure (+2 horas)
- Asignación automática a asesor de turno
2. **Contacto inicial (Día 1, 2:00 PM):**
- Asesor llama al prospecto
- Calificación inicial (presupuesto, puntos INFONAVIT, timeline)
- Agendamiento de visita al proyecto
3. **Visita (Día 5):**
- Recorrido por proyecto y vivienda muestra
- Explicación de proceso de compra
- Cotización personalizada
4. **Seguimiento (Días 6-20):**
- Mensajes WhatsApp con información adicional
- Envío de cotización formal
- Resolución de dudas
5. **Cierre (Día 25):**
- Cliente decide apartareservar vivienda
- Pago de apartado
- Inicio de trámite de crédito
---
### Venta con Crédito INFONAVIT
**Resumen de timeline típico:**
| Hito | Día | Responsable |
|------|-----|-------------|
| Contacto inicial | 1 | Asesor |
| Primera visita | 5 | Asesor |
| Apartado | 25 | Asesor |
| Expediente completo | 40 | Asesor + Cliente |
| Envío a INFONAVIT | 41 | Coordinador |
| Crédito aprobado | 55 | INFONAVIT |
| Firma de contrato | 60 | Asesor + Notario |
| Escrituración | 75 | Notario |
| Entrega de vivienda | 90 | Postventa |
**Total: 90 días desde primer contacto hasta entrega**
---
## 🚨 Puntos Críticos
1. **Calificación temprana:** No invertir tiempo en prospectos sin capacidad de compra
2. **Seguimiento constante:** Prospectos sin contacto por >7 días se enfrían
3. **Expedientes completos:** Documentos incompletos retrasan aprobación de crédito
4. **Apartados sin avance:** Liberar viviendas si apartado expira
5. **Comunicación clara:** Cliente debe saber en qué etapa está y qué sigue
6. **Portal del cliente:** Self-service reduce carga operativa
7. **Integración con INFONAVIT:** Consulta automática de puntos y estatus
---
## 🎯 Siguiente Paso
Crear documentación de requerimientos y especificaciones técnicas del módulo.
---
**Generado:** 2025-11-17
**Mantenedores:** @tech-lead @backend-team @frontend-team @sales-team
**Estado:** 📝 A crear