# DIRECTIVA-GESTION-CITAS

**Version:** 1.0
**Fecha:** 2025-12-08
**Vertical:** Clinicas
**Nivel:** 2B.2

---

## PROPOSITO

Define las directrices para el sistema de gestion de citas medicas.

---

## ALCANCE

- Agenda de medicos
- Programacion de citas
- Confirmaciones y recordatorios
- Gestion de consultorios

---

## PRINCIPIOS

### 1. Disponibilidad Visible

- Horarios de medicos siempre actualizados
- Slots disponibles en tiempo real
- Sin overbooking

### 2. Comunicacion Proactiva

- Confirmacion inmediata de cita
- Recordatorios automaticos (24h, 2h antes)
- Notificacion de cambios

### 3. Optimizacion de Recursos

- Maximizar uso de consultorios
- Minimizar tiempos muertos
- Balance de carga entre medicos

---

## MODELO DE DATOS

### doctors (medicos)
```yaml
campos:
  - id: uuid
  - employee_id: FK -> hr.employees
  - license_number: string # cedula profesional
  - specialty_id: FK -> specialties
  - consultation_duration: integer # minutos default
  - max_daily_appointments: integer
  - status: enum(active, inactive, vacation)
```

### doctor_schedules (horarios)
```yaml
campos:
  - id: uuid
  - doctor_id: FK -> doctors
  - day_of_week: enum(mon, tue, wed, thu, fri, sat, sun)
  - start_time: time
  - end_time: time
  - consulting_room_id: FK -> consulting_rooms
  - is_active: boolean
```

### appointments (citas)
```yaml
campos:
  - id: uuid
  - patient_id: FK -> patients
  - doctor_id: FK -> doctors
  - appointment_type_id: FK -> appointment_types
  - consulting_room_id: FK -> consulting_rooms
  - scheduled_start: timestamp
  - scheduled_end: timestamp
  - actual_start: timestamp
  - actual_end: timestamp
  - status: enum(scheduled, confirmed, in_progress, completed, cancelled, no_show)
  - cancellation_reason: text
  - notes: text
```

### consulting_rooms (consultorios)
```yaml
campos:
  - id: uuid
  - room_number: string
  - floor: string
  - equipment: json # equipo disponible
  - specialty_id: FK -> specialties (si es especializado)
  - status: enum(available, occupied, maintenance)
```

---

## FLUJO DE CITA

### Programacion

```
1. Paciente solicita cita
   |
2. Selecciona especialidad/medico
   |
3. Sistema muestra disponibilidad
   |
4. Paciente selecciona horario
   |
5. Sistema valida:
   |-- Disponibilidad del medico
   |-- Disponibilidad del consultorio
   |-- No conflictos del paciente
   |
6. Cita creada (status: scheduled)
   |
7. Notificacion al paciente
```

### Confirmacion

```
24 horas antes:
  Sistema envia recordatorio
  Paciente puede:
    - Confirmar
    - Reprogramar
    - Cancelar

2 horas antes:
  Sistema envia recordatorio final
```

### Dia de la Cita

```
1. Paciente llega
   |
2. Recepcion marca llegada
   |
3. Cuando medico esta listo:
   |-- Cita pasa a "in_progress"
   |-- Registra hora real de inicio
   |
4. Al terminar:
   |-- Cita pasa a "completed"
   |-- Registra hora real de fin
```

---

## ESTADOS DE CITA

```
scheduled --> confirmed --> in_progress --> completed
     |            |              |
     v            v              v
 cancelled    no_show       cancelled
```

### Reglas de Transicion

| De | A | Condicion |
|----|---|-----------|
| scheduled | confirmed | Paciente confirma |
| scheduled | cancelled | Antes de 24h |
| confirmed | in_progress | Paciente presente |
| confirmed | no_show | No se presento |
| in_progress | completed | Consulta terminada |

---

## NOTIFICACIONES

### Canales

| Canal | Uso |
|-------|-----|
| Email | Confirmacion, recordatorios |
| SMS | Recordatorio 2h antes |
| WhatsApp | Opcional, si configurado |
| Push | Si tiene app instalada |

### Templates

```
Confirmacion:
  "Su cita con Dr. {doctor} ha sido confirmada para el {fecha} a las {hora}."

Recordatorio 24h:
  "Le recordamos su cita manana {fecha} a las {hora} con Dr. {doctor}.
   Por favor confirme respondiendo SI o cancele respondiendo NO."

Recordatorio 2h:
  "Su cita es en 2 horas. Direccion: {direccion}. Consultorio: {consultorio}."
```

---

## INTEGRACION CON CORE

### Herencia de Specs

| Spec Core | Aplicacion |
|-----------|------------|
| SPEC-INTEGRACION-CALENDAR | Base del calendario |
| SPEC-TAREAS-RECURRENTES | Citas recurrentes |
| SPEC-MAIL-THREAD-TRACKING | Historial de comunicacion |

### APIs a Extender

- Calendar del core para la agenda
- Notification service para recordatorios

---

## METRICAS

| Metrica | Objetivo | Alerta |
|---------|----------|--------|
| Ocupacion de agenda | > 80% | < 60% |
| No-shows | < 5% | > 10% |
| Tiempo de espera | < 15 min | > 30 min |
| Confirmaciones | > 90% | < 80% |

---

## REFERENCIAS

- SPEC-INTEGRACION-CALENDAR.md (core)
- DIRECTIVA-EXPEDIENTE-CLINICO.md
- HERENCIA-SPECS-ERP-CORE.md

---

**Documento de directiva oficial**