# US-MGN-009-002-001: CRUD Oportunidades

**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:** Oportunidades
**Prioridad:** P0
**Story Points:** 5
**Sprint:** Sprint 20
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story
**Como** vendedor, **Quiero** gestionar oportunidades de venta calificadas, **Para** trackear el pipeline hasta el cierre.

## Descripción Detallada
Oportunidad es un lead calificado con potencial de venta:
- Cliente/Contacto
- Monto estimado
- Probabilidad de cierre (%)
- Fecha estimada de cierre
- Etapa (prospecting, qualification, proposal, negotiation, won, lost)
- Productos/servicios de interés

## Criterios de Aceptación

### Escenario 1: Crear oportunidad
**Dado que** soy vendedor,
**Cuando** creo oportunidad: name="Venta 500 laptops ABC Corp", customer_id=1, amount=50000, probability=60%, stage=proposal, expected_close_date="2024-03-30",
**Entonces** sistema crea oportunidad exitosamente.

### Escenario 2: Mover oportunidad por etapas
**Dado que** oportunidad está en stage=qualification,
**Cuando** actualizo stage=proposal, probability=70%,
**Entonces** sistema actualiza y registra cambio en histórico.

### Escenario 3: Marcar como ganada (Won)
**Dado que** oportunidad está en negotiation con amount=50000,
**Cuando** cambio stage=won,
**Entonces** sistema marca como ganada, registra fecha de cierre, actualiza KPIs de ventas.

### Escenario 4: Marcar como perdida (Lost)
**Dado que** oportunidad está activa,
**Cuando** cambio stage=lost, lost_reason="Precio muy alto",
**Entonces** sistema marca como perdida, requiere motivo obligatorio.

## Reglas de Negocio
- **RN-1:** Oportunidad requiere customer_id válido.
- **RN-2:** amount > 0.
- **RN-3:** stage=won requiere fecha de cierre.
- **RN-4:** stage=lost requiere lost_reason.
- **RN-5:** expected_revenue = amount × (probability/100).

## Tareas Técnicas

### Backend
- [ ] Endpoint: POST/GET/PUT/DELETE `/api/v1/crm/opportunities`
- [ ] Service: `OpportunityService` (CRUD, markAsWon, markAsLost)
- [ ] Calcular expected_revenue automáticamente
- [ ] Validar lost_reason si stage=lost
- [ ] Unit tests

### Frontend
- [ ] Página: `OpportunitiesPage.tsx`
- [ ] Formulario: `OpportunityForm.tsx`
- [ ] Kanban view por etapas
- [ ] Drag & drop entre etapas
- [ ] Component tests

### Database
- [ ] Tabla: `crm.opportunities` (customer_id, name, amount, probability, stage, expected_close_date, actual_close_date, lost_reason)
- [ ] Enum: opportunity_stage
- [ ] Índices: idx_opportunities_stage, idx_opportunities_customer_id

---

## Estimación Detallada
| Tarea | Horas |
|-------|-------|
| Backend | 2.5 |
| Frontend | 2.5 |
| Testing | 2 |
| **TOTAL** | **7 horas = 5 SP** |

---

## Definition of Done
- [ ] CRUD completo
- [ ] Workflow de etapas funciona
- [ ] Won/Lost con validaciones
- [ ] Tests >80%
- [ ] 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)