# US-MGN-009-004-001: CRUD Actividades CRM

**RF Asociado:** [RF-MGN-009-003](../../02-modelado/requerimientos-funcionales/mgn-009/RF-MGN-009-003-actividades-y-seguimiento.md)
**Módulo:** MGN-009 - CRM Básico
**Epic:** Actividades
**Prioridad:** P0
**Story Points:** 4
**Sprint:** Sprint 21
**Estado:** Ready for Development
**Fecha:** 2025-11-24

---

## User Story
**Como** vendedor, **Quiero** registrar actividades (llamadas, reuniones, emails) en leads/oportunidades, **Para** mantener histórico de interacciones.

## Descripción Detallada
Actividad CRM registra:
- Tipo (llamada, reunión, email, tarea)
- Fecha/hora
- Duración
- Notas/descripción
- Vinculación a lead/oportunidad
- Estado (pendiente, completada)

## Criterios de Aceptación

### Escenario 1: Crear actividad
**Dado que** estoy en oportunidad id=1,
**Cuando** creo actividad: type=call, date="2024-01-15 10:00", duration=30, notes="Discutir propuesta",
**Entonces** sistema crea actividad vinculada a oportunidad.

### Escenario 2: Marcar como completada
**Dado que** actividad está state=pending,
**Cuando** marco como completada,
**Entonces** state=completed, completed_at=now().

### Escenario 3: Timeline de actividades
**Dado que** oportunidad tiene 10 actividades,
**Cuando** veo timeline,
**Entonces** veo lista ordenada por fecha descendente.

### Escenario 4: Próximas actividades pendientes
**Dado que** tengo 5 actividades pendientes para hoy y 3 para mañana,
**Cuando** accedo a dashboard,
**Entonces** widget "Próximas Actividades" muestra las 8 actividades.

## Reglas de Negocio
- **RN-1:** Actividad vincula a lead OR oportunidad (no ambos).
- **RN-2:** state default: pending.
- **RN-3:** completed_at se registra al marcar completada.
- **RN-4:** Actualiza score de lead al registrar actividad.

## Tareas Técnicas

### Backend
- [ ] Endpoint: POST/GET/PUT/DELETE `/api/v1/crm/activities`
- [ ] Service: `ActivityService` (CRUD, markAsCompleted)
- [ ] Validar lead_id XOR opportunity_id
- [ ] Actualizar lead score al crear actividad
- [ ] Unit tests

### Frontend
- [ ] Componente: `ActivityForm.tsx`
- [ ] Componente: `ActivityTimeline.tsx`
- [ ] Componente: `UpcomingActivitiesWidget.tsx`
- [ ] Checkbox: Marcar como completada
- [ ] Component tests

### Database
- [ ] Tabla: `crm.activities` (type, date, duration, notes, lead_id, opportunity_id, state, completed_at)
- [ ] Enum: activity_type, activity_state
- [ ] Índices: idx_activities_lead_id, idx_activities_opportunity_id, idx_activities_date

---

## Estimación Detallada
| Tarea | Horas |
|-------|-------|
| Backend | 2 |
| Frontend | 2 |
| Testing | 1.5 |
| **TOTAL** | **5.5 horas = 4 SP** |

---

## Definition of Done
- [ ] CRUD completo
- [ ] Timeline funcional
- [ ] Marcar completada funciona
- [ ] Score de lead actualiza
- [ ] Tests >80%
- [ ] QA/PO aprobado

---

## Referencias
- [RF-MGN-009-003](../../02-modelado/requerimientos-funcionales/mgn-009/RF-MGN-009-003-actividades-y-seguimiento.md)
