# US-MGN-009-001-001: CRUD Leads

**RF Asociado:** [RF-MGN-009-001](../../02-modelado/requerimientos-funcionales/mgn-009/RF-MGN-009-001-gestión-de-leads-y-oportunidades.md)
**Módulo:** MGN-009 - CRM Básico
**Epic:** Leads
**Prioridad:** P0
**Story Points:** 4
**Sprint:** Sprint 20
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story
**Como** vendedor, **Quiero** crear y gestionar leads (contactos potenciales), **Para** dar seguimiento a prospectos antes de convertirlos en oportunidades.

## Descripción Detallada
Lead es un contacto potencial que aún no es cliente. Incluye:
- Información de contacto (nombre, email, teléfono, empresa)
- Fuente (web, referido, evento, cold call)
- Estado (new, contacted, qualified, unqualified, converted)
- Vendedor asignado
- Tags

## Criterios de Aceptación

### Escenario 1: Crear lead
**Dado que** soy vendedor,
**Cuando** creo lead: name="Juan Pérez", email="juan@example.com", company="ABC Corp", source="website",
**Entonces** sistema crea lead con state=new, assigned_to=current_user.

### Escenario 2: Email único (opcional)
**Dado que** ya existe lead con email="juan@example.com",
**Cuando** intento crear otro con mismo email,
**Entonces** sistema muestra warning "Lead con este email ya existe" pero permite crear.

### Escenario 3: Actualizar lead
**Dado que** lead existe,
**Cuando** actualizo state=contacted, notes="Llamada realizada",
**Entonces** sistema actualiza y registra en audit_log.

### Escenario 4: Asignar lead a vendedor
**Dado que** soy sales_manager,
**Cuando** asigno lead a vendedor Juan,
**Entonces** lead.assigned_to=Juan, sistema notifica a Juan.

### Escenario 5: Filtrar leads por estado
**Dado que** hay 50 leads: 20 new, 15 contacted, 15 qualified,
**Cuando** filtro state=new,
**Entonces** veo solo los 20 leads new.

## Reglas de Negocio
- **RN-1:** Lead se crea en state=new.
- **RN-2:** Email no es único (puede haber duplicados).
- **RN-3:** Vendedor asignado por defecto: creador del lead.
- **RN-4:** RLS filtra por empresa.
- **RN-5:** Permisos: sales_user (propios), sales_manager (todos).

## Tareas Técnicas

### Backend
- [ ] Endpoint: POST/GET/PUT/DELETE `/api/v1/crm/leads`
- [ ] Service: `LeadService` (CRUD methods)
- [ ] DTO: `CreateLeadDto`, `UpdateLeadDto`
- [ ] Enum: lead_state, lead_source
- [ ] Notificar al asignar lead
- [ ] Unit tests (>80%)
- [ ] Integration tests
- [ ] Swagger docs

### Frontend
- [ ] Página: `LeadsPage.tsx` (/crm/leads)
- [ ] Componente: `LeadForm.tsx`
- [ ] Componente: `LeadList.tsx` (tabla con filtros)
- [ ] Componente: `LeadCard.tsx` (vista detalle)
- [ ] Filtros: Estado, Fuente, Vendedor, Fecha
- [ ] Badges: Estado con colores
- [ ] API client: `leadApi`
- [ ] Component tests
- [ ] E2E test

### Database
- [ ] Tabla: `crm.leads` (id, company_id, name, email, phone, company_name, source, state, assigned_to, created_by)
- [ ] Enum: lead_state, lead_source
- [ ] Índices: idx_leads_state, idx_leads_assigned_to, idx_leads_email
- [ ] RLS policy: company_isolation

---

## Estimación Detallada
| Tarea | Horas |
|-------|-------|
| Backend | 2 |
| Frontend | 2.5 |
| Testing | 1.5 |
| Code Review | 0.5 |
| **TOTAL** | **6.5 horas = 4 SP** |

---

## Definition of Done
- [ ] CRUD completo funcional
- [ ] Tests pasando (>80%)
- [ ] Filtros funcionan
- [ ] Asignación de vendedor funciona
- [ ] Notificaciones enviadas
- [ ] RLS aplicado
- [ ] QA/PO aprobado

---

## Referencias
- [RF-MGN-009-001](../../02-modelado/requerimientos-funcionales/mgn-009/RF-MGN-009-001-gestión-de-leads-y-oportunidades.md)
- [Traceability](../../02-modelado/trazabilidad/TRACEABILITY-MGN-009.yaml)