# EPICA: EPIC-CL-003 - Citas (Agenda Médica)

## Metadata

| Campo | Valor |
|-------|-------|
| **ID** | EPIC-CL-003 |
| **Nombre** | Citas (Agenda Médica) |
| **Modulo** | citas |
| **Fase** | Fase 1 - MVP |
| **Prioridad** | P0 (Critico) |
| **Estado** | Backlog |
| **Story Points** | 42 |
| **Sprint(s)** | Sprint 3-4 |

---

## Descripcion

Sistema de agenda médica para programación de citas. Gestión de horarios por médico y consultorio, confirmación de citas, recordatorios automáticos, lista de espera y módulo de check-in para llegada de pacientes.

---

## Objetivo de Negocio

- Optimizar uso de consultorios
- Reducir ausentismo con recordatorios
- Mejorar experiencia del paciente
- Control de tiempos de espera
- Maximizar productividad médica

---

## Historias de Usuario

| ID | Historia | Prioridad | SP | Estado |
|----|----------|-----------|-----|--------|
| US-CL003-001 | Como recepcionista, quiero agendar cita seleccionando médico, fecha y hora disponible | P0 | 5 | Backlog |
| US-CL003-002 | Como recepcionista, quiero ver agenda del día por médico en formato calendario | P0 | 5 | Backlog |
| US-CL003-003 | Como recepcionista, quiero confirmar cita vía WhatsApp o llamada | P0 | 3 | Backlog |
| US-CL003-004 | Como paciente, quiero recibir recordatorio automático 24h antes de mi cita | P0 | 5 | Backlog |
| US-CL003-005 | Como recepcionista, quiero reagendar cita manteniendo historial | P0 | 3 | Backlog |
| US-CL003-006 | Como recepcionista, quiero registrar check-in del paciente al llegar | P0 | 3 | Backlog |
| US-CL003-007 | Como médico, quiero ver mis citas del día con datos del paciente | P0 | 3 | Backlog |
| US-CL003-008 | Como admin, quiero configurar horarios de atención por médico | P0 | 5 | Backlog |
| US-CL003-009 | Como recepcionista, quiero gestionar lista de espera para cancelaciones | P1 | 3 | Backlog |
| US-CL003-010 | Como paciente, quiero agendar cita desde portal web o app | P1 | 5 | Backlog |
| US-CL003-011 | Como admin, quiero bloquear horarios por vacaciones o eventos | P1 | 2 | Backlog |

**Total Story Points:** 42 SP

---

## Flujo de Cita

```
┌─────────────┐
│  AGENDADA   │  ← Cita programada
└──────┬──────┘
       │
       ▼ (-24h)
┌─────────────┐
│ RECORDATORIO│  ← Envío automático WhatsApp/SMS
└──────┬──────┘
       │
       ├── Sin respuesta ────────────┐
       ▼                             │
┌─────────────┐                      │
│ CONFIRMADA  │                      │
└──────┬──────┘                      │
       │                             │
       ▼ (Día de la cita)            │
┌─────────────┐                      │
│  CHECK-IN   │  ← Paciente llega    │
└──────┬──────┘                      │
       │                             │
       ▼                             │
┌─────────────┐                      │
│ EN_CONSULTA │  ← Médico inicia     │
└──────┬──────┘                      │
       │                             │
       ▼                             ▼
┌─────────────┐               ┌─────────────┐
│  ATENDIDA   │               │ NO_ASISTIO  │
└─────────────┘               └─────────────┘
```

---

## Configuración de Agenda

```
┌─────────────────────────────────────────────────────────┐
│              AGENDA DEL DR. GARCÍA                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  HORARIO DE ATENCIÓN                                    │
│  ├── Lunes a Viernes: 09:00 - 14:00, 16:00 - 20:00     │
│  ├── Sábados: 09:00 - 14:00                             │
│  └── Domingos: No labora                                │
│                                                         │
│  DURACIÓN DE CITAS                                      │
│  ├── Primera vez: 45 minutos                            │
│  ├── Seguimiento: 20 minutos                            │
│  └── Procedimiento: 60 minutos                          │
│                                                         │
│  CONSULTORIOS                                           │
│  ├── Consultorio 1 (Principal)                          │
│  └── Consultorio 3 (Alterno)                            │
│                                                         │
│  BLOQUEOS                                               │
│  ├── 15-22 Dic: Vacaciones                              │
│  └── Cada miércoles 10:00-11:00: Junta médica           │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Vista de Agenda

```
┌─────────────────────────────────────────────────────────┐
│  DR. GARCÍA - Lunes 9 Diciembre 2024                    │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  09:00 │ ████████████████████ Juan Pérez (Primera vez)  │
│  09:45 │                      - DISPONIBLE -            │
│  10:00 │ ████████ María López (Seguimiento) ✓ Confirmada│
│  10:20 │                      - DISPONIBLE -            │
│  10:40 │ ████████ Carlos Ruiz (Seguimiento)             │
│  11:00 │                      ▓▓▓ JUNTA MÉDICA ▓▓▓      │
│  12:00 │ ████████████████████████████████ Procedimiento │
│  13:00 │ ████████ Ana García (Seguimiento) ✓ En sala    │
│  13:20 │ ████████ Pedro Soto (Seguimiento)              │
│  13:40 │                      - DISPONIBLE -            │
│                                                         │
│  ────────────── DESCANSO ──────────────                 │
│                                                         │
│  16:00 │ ████████████████████ Nuevo paciente (1a vez)   │
│  ...                                                    │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

---

## Criterios de Aceptacion de la Epica

**Funcionales:**
- [ ] Agendar citas con validación de disponibilidad
- [ ] Vista de agenda diaria/semanal por médico
- [ ] Confirmación de citas
- [ ] Recordatorios automáticos (WhatsApp/SMS/Email)
- [ ] Check-in de pacientes
- [ ] Reagendar y cancelar citas
- [ ] Lista de espera
- [ ] Configuración de horarios

**No Funcionales:**
- [ ] Carga de agenda < 2 segundos
- [ ] Envío de recordatorio en < 1 minuto
- [ ] Soporte para 10+ médicos simultáneos

**Tecnicos:**
- [ ] Integración con WhatsApp Business API
- [ ] Calendario sincronizable (Google Calendar, Outlook)
- [ ] Notificaciones push para app
- [ ] Tiempo real con WebSockets

---

## Dependencias

**Esta epica depende de:**
| Epica/Modulo | Estado | Bloqueante |
|--------------|--------|------------|
| EPIC-CL-001 Fundamentos | Backlog | Si |
| EPIC-CL-002 Pacientes | Backlog | Si |

**Esta epica bloquea:**
| Epica/Modulo | Razon |
|--------------|-------|
| EPIC-CL-004 Consultas | Requiere cita para iniciar consulta |
| EPIC-CL-008 Facturación | Requiere citas para facturar |

---

## Desglose Tecnico

**Database:**
- [ ] Schema: `appointments`
- [ ] Tablas: 7 (appointments, schedules, schedule_blocks, waiting_list, reminders, check_ins, appointment_types)
- [ ] Funciones: 3 (check_availability, send_reminder, calculate_wait_time)
- [ ] Indices: Por médico, fecha, paciente, estado

**Backend:**
- [ ] Modulo: `appointments`
- [ ] Entities: 6 (Appointment, Schedule, ScheduleBlock, WaitingList, Reminder, CheckIn)
- [ ] Endpoints: 18
- [ ] Jobs: Envío de recordatorios
- [ ] Tests: 35

**Frontend:**
- [ ] Paginas: 5 (Calendar, AppointmentForm, DayView, WeekView, WaitingList)
- [ ] Componentes: 15 (CalendarGrid, TimeSlot, AppointmentCard, CheckInModal, etc.)
- [ ] WebSockets para actualizaciones en tiempo real
- [ ] Stores: 1 (appointmentsStore)

---

## Endpoints API

| Metodo | Endpoint | Descripcion |
|--------|----------|-------------|
| POST | /api/appointments | Crear cita |
| GET | /api/appointments/:id | Detalle de cita |
| PATCH | /api/appointments/:id | Actualizar cita |
| DELETE | /api/appointments/:id | Cancelar cita |
| GET | /api/appointments/calendar/:doctorId | Agenda del médico |
| GET | /api/appointments/availability | Horarios disponibles |
| POST | /api/appointments/:id/confirm | Confirmar cita |
| POST | /api/appointments/:id/check-in | Registrar llegada |
| GET | /api/schedules/:doctorId | Horarios del médico |
| POST | /api/schedules/:doctorId/blocks | Bloquear horario |
| GET | /api/waiting-list | Lista de espera |

---

## Riesgos

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Overbooking | Media | Alto | Validación de disponibilidad |
| Recordatorios no enviados | Media | Medio | Reintentos + logs |
| Ausentismo alto | Media | Medio | Confirmación + lista de espera |

---

## Definition of Ready (DoR)

- [x] Historias de usuario definidas
- [x] Criterios de aceptacion claros
- [x] Dependencias identificadas
- [x] Estimacion completada
- [ ] Horarios de médicos definidos
- [ ] Proveedor de WhatsApp Business API seleccionado

## Definition of Done (DoD)

- [ ] Agenda funcional por médico
- [ ] Recordatorios automáticos enviándose
- [ ] Check-in operativo
- [ ] Lista de espera activa
- [ ] Tests de integración pasando
- [ ] Documentación de API

---

## Historial

| Fecha | Cambio | Autor |
|-------|--------|-------|
| 2025-12-08 | Creacion de epica | Claude-Agent |

---

**Creada por:** Claude-Agent
**Fecha:** 2025-12-08
**Ultima actualizacion:** 2025-12-08
