Modulo de Calendario de Medicamentos y Eventos de Salud¶

Identificador: MTS-CAL-001 Version: 1.2.0 Fecha: 2025-12-05 Ultima Revision: Iteracion 13 - Correccion OBS-060: Documentar 4 roles estandar Autor: SpecQueen

1. Propósito
2. Actores
- 2.1. Actores del Sistema
3. Conceptos Clave
3.1. Evento de Toma
3.2. Momentos del Día
4. Funcionalidades
4.1. Configuración de Hábitos (MTS-CAL-001-F01)
- 4.1.1. Descripción
- 4.1.2. Datos de Hábitos
- 4.1.3. Flujo: Configuración Inicial (Onboarding)
4.2. Cálculo de Horarios (MTS-CAL-001-F02)
- 4.2.1. Descripción
- 4.2.2. Factores Considerados
- 4.2.3. Algoritmo de Sugerencia
- 4.2.4. Restricciones de Toma
4.3. Agrupación en Eventos (MTS-CAL-001-F03)
- 4.3.1. Descripción
- 4.3.2. Reglas de Agrupación
- 4.3.3. Estructura de Evento
4.4. Vista de Calendario (MTS-CAL-001-F04)
- 4.4.1. Descripción
- 4.4.2. Vistas Disponibles
- 4.4.3. Vista "Hoy" (Principal)
4.5. Registro de Toma (MTS-CAL-001-F05)
- 4.5.1. Descripción
- 4.5.2. Acciones Disponibles
- 4.5.3. Flujo: Confirmar Toma desde Notificación
- 4.5.4. Flujo: Confirmar Toma desde App
- 4.5.5. Motivos de Omisión
4.6. Ajustes de Horario (MTS-CAL-001-F06)
- 4.6.1. Descripción
- 4.6.2. Tipos de Ajuste
- 4.6.3. Flujo: Cambiar Horario Permanente
4.7. Modo Viaje (MTS-CAL-001-F07)
- 4.7.1. Descripción
- 4.7.2. Estrategias de Ajuste
- 4.7.3. Flujo: Activar Modo Viaje
5. Reglas de Negocio
6. Modelo de Datos
6.1. Entidad EventoToma
6.2. Entidad TomaProgramada
6.3. Entidad RegistroToma
6.4. Entidad HabitosUsuario
7. Criterios de Aceptación
8. API Endpoints (Iteracion 13)
8.1. Endpoints de Calendario
8.2. Request/Response Listar Eventos
- 8.2.1. Request
- 8.2.2. Response (200)
8.3. Request/Response Completar Toma
- 8.3.1. Request
- 8.3.2. Response (200)
9. Referencias

1. Propósito¶

Este modulo gestiona la programacion inteligente de tomas de medicamentos y eventos de salud (mediciones y tratamientos), adaptada a los habitos de vida del paciente, agrupando tomas en eventos manejables.

2. Actores¶

Nota V1.0: MedTime define 4 roles de usuario estandar. Ver MTS-ROL-001 para detalles completos.

Rol	Codigo	Descripcion en este Modulo
Paciente Independiente	PI	Configura sus propios horarios y confirma sus tomas. Control total sobre su calendario.
Paciente Dependiente	PD	Confirma tomas. Cuidador puede gestionar configuracion de horarios.
Cuidador Supervisor	CS	Visualiza calendario del paciente. Recibe alertas de omisiones. Solo lectura.
Cuidador Responsable	CR	Puede configurar horarios y registrar tomas en nombre del paciente. Control delegado.

2.1. Actores del Sistema¶

Actor	Descripcion
Sistema	Calcula horarios optimos, agrupa eventos, programa notificaciones

3. Conceptos Clave¶

3.1. Evento de Toma¶

Un Evento de Toma agrupa múltiples medicamentos que deben tomarse en un momento similar del día.

Concepto	Descripción
Evento	Agrupación de tomas en un momento del día
Ventana	Rango de tiempo aceptable para el evento
Toma	Medicamento individual dentro del evento
Momento	Referencia al hábito (desayuno, almuerzo, etc.)

3.2. Momentos del Día¶

Momento	Default	Personalizable
Al despertar	07:00	Sí
Desayuno	08:00	Sí
Media mañana	10:30	Sí
Almuerzo	14:00	Sí
Merienda	17:00	Sí
Cena	20:00	Sí
Antes de dormir	22:00	Sí
Madrugada	03:00	Sí

4. Funcionalidades¶

4.1. Configuración de Hábitos (MTS-CAL-001-F01)¶

4.1.1. Descripción¶

Permite al paciente definir sus horarios habituales para que el sistema sugiera tomas óptimas.

4.1.2. Datos de Hábitos¶

Dato	Tipo	Descripción
hora_despertar	time	Hora habitual de levantarse
hora_desayuno	time	Hora habitual de desayunar
hora_almuerzo	time	Hora habitual de almorzar
hora_cena	time	Hora habitual de cenar
hora_dormir	time	Hora habitual de acostarse
dias_laborales	array	Días con horario laboral
horario_flexible	boolean	Si los horarios varían mucho

4.1.3. Flujo: Configuración Inicial (Onboarding)¶

Sistema pregunta hora habitual de despertar
Sistema pregunta si desayuna y a qué hora
Sistema pregunta hora de almuerzo
Sistema pregunta hora de cena
Sistema pregunta hora de dormir
Sistema pregunta si horarios cambian fines de semana
Si cambian, solicita horarios de fin de semana
Sistema guarda configuración
Sistema calcula momentos del día personalizados

4.2. Cálculo de Horarios (MTS-CAL-001-F02)¶

4.2.1. Descripción¶

Algoritmo inteligente que determina el mejor horario para cada medicamento.

4.2.2. Factores Considerados¶

Factor	Peso	Descripción
Frecuencia prescrita	Alto	Cada 8h, 12h, 24h, etc.
Relación con comidas	Alto	Con/sin alimentos, antes/después
Hábitos del paciente	Medio	Alineación con rutina
Interacción temporal	Medio	Separación entre medicamentos
Preferencia del paciente	Alto	Horarios preferidos

4.2.3. Algoritmo de Sugerencia¶

flowchart TD
    A[Inicio] --> B[Obtener frecuencia del medicamento]
    B --> C[Obtener restricciones]
    C --> D[Obtener hábitos del paciente]
    D --> E{Calcular horarios base según frecuencia}
    E -->|24h| F[1 horario - momento preferido]
    E -->|12h| G[2 horarios - mañana, noche]
    E -->|8h| H[3 horarios - mañana, tarde, noche]
    E -->|6h| I[4 horarios - distribuidos]
    F --> J{Ajustar según restricciones}
    G --> J
    H --> J
    I --> J
    J -->|Con comida| K[Alinear con comidas]
    J -->|En ayunas| L[30 min antes de comida]
    J -->|Antes de dormir| M[Alinear con hora de dormir]
    K --> N[Verificar separación con otros medicamentos]
    L --> N
    M --> N
    N --> O[Presentar sugerencia al paciente]
    O --> P[Fin]

4.2.4. Restricciones de Toma¶

Restricción	Código	Implementación
Con alimentos	WITH_FOOD	Alinear con comidas
Sin alimentos	WITHOUT_FOOD	1h antes o 2h después
En ayunas	FASTING	30min antes de primera comida
Antes de dormir	BEDTIME	Alinear con hora de dormir
Al despertar	WAKEUP	Alinear con hora de despertar
Separado de lácteos	NO_DAIRY	2h de separación
Separado de antiácidos	NO_ANTACID	2h de separación

4.3. Agrupación en Eventos (MTS-CAL-001-F03)¶

4.3.1. Descripción¶

Agrupa medicamentos con horarios similares en eventos unificados.

4.3.2. Reglas de Agrupación¶

Regla	Descripción
Ventana de tiempo	Medicamentos dentro de 30 minutos
Máximo por evento	8 medicamentos por evento
Compatibilidad	No agrupar si hay restricción de separación
Mismo momento	Agrupar por momento del día

4.3.3. Estructura de Evento¶

Evento {
  id: UUID
  nombre: "Medicinas del desayuno"
  hora_programada: "08:00"
  ventana_inicio: "07:45"
  ventana_fin: "08:30"
  momento: "DESAYUNO"
  tomas: [
    { medicamento: "Metformina", dosis: "850mg", instruccion: "con alimentos" },
    { medicamento: "Lisinopril", dosis: "10mg", instruccion: null },
    { medicamento: "Omeprazol", dosis: "20mg", instruccion: "30min antes" }
  ]
  estado: "PENDIENTE"
}

4.4. Vista de Calendario (MTS-CAL-001-F04)¶

4.4.1. Descripción¶

Visualización del calendario de tomas en diferentes formatos.

4.4.2. Vistas Disponibles¶

Vista	Descripción
Hoy	Eventos del día actual con estado
Semana	Vista semanal con resumen por día
Mes	Calendario mensual con indicadores
Lista	Lista cronológica de próximos eventos

4.4.3. Vista "Hoy" (Principal)¶

┌────────────────────────────────────────┐
│  Hoy, 1 de Diciembre                    │
│                                        │
│  ✓ 07:30 - Al despertar                │
│    Omeprazol 20mg                      │
│                                        │
│  ✓ 08:00 - Desayuno                    │
│    Metformina 850mg                    │
│    Lisinopril 10mg                     │
│                                        │
│  ○ 14:00 - Almuerzo          PRÓXIMO  │
│    Metformina 850mg                    │
│                                        │
│  ○ 20:00 - Cena                        │
│    Metformina 850mg                    │
│    Atorvastatina 20mg                  │
│                                        │
│  ○ 22:00 - Antes de dormir             │
│    Alprazolam 0.5mg                    │
└────────────────────────────────────────┘
✓ = Completado  ○ = Pendiente  ✗ = Omitido

4.5. Registro de Toma (MTS-CAL-001-F05)¶

4.5.1. Descripción¶

Permite registrar la toma, omisión o posposición de medicamentos.

4.5.2. Acciones Disponibles¶

Acción	Descripción	Datos Adicionales
Tomar todo	Confirma todas las tomas del evento	Hora real
Tomar parcial	Confirma algunos medicamentos	Selección
Omitir	Marca como no tomado	Motivo (opcional)
Posponer	Reprograma para más tarde	Nueva hora
Toma anticipada	Registra toma antes de hora	Hora real

4.5.3. Flujo: Confirmar Toma desde Notificación¶

Usuario recibe notificación de toma
Notificación muestra acciones rápidas:
"Tomado" (confirmar todo)
"Posponer 30 min"
"Ver detalles"

3a. Si "Tomado": Sistema registra toma con hora actual 3a. Si "Tomado": Sistema registra toma con hora actual 3b. Si "Posponer": Sistema reprograma evento 3c. Si "Ver detalles": Abrir app en evento

4.5.4. Flujo: Confirmar Toma desde App¶

Usuario abre evento pendiente
Sistema muestra medicamentos del evento
Usuario puede:
Confirmar todos (botón principal)
Seleccionar individualmente
Marcar omisión con motivo
Sistema registra acción con timestamp
Sistema actualiza vista de calendario
Sistema actualiza estadísticas de adherencia

4.5.5. Motivos de Omisión¶

Motivo	Código
Olvidé	FORGOT
No tenía el medicamento	NO_SUPPLY
Efectos secundarios	SIDE_EFFECTS
Me sentí mal	FELT_SICK
Indicación médica	DOCTOR_ORDER
Otro	OTHER

4.6. Ajustes de Horario (MTS-CAL-001-F06)¶

4.6.1. Descripción¶

Permite modificar horarios de eventos de forma temporal o permanente.

4.6.2. Tipos de Ajuste¶

Tipo	Descripción	Afecta
Temporal	Solo para hoy/este evento	Un evento
Permanente	Cambiar horario base	Todos los eventos futuros
Por día	Diferente horario por día de semana	Patrón semanal

4.6.3. Flujo: Cambiar Horario Permanente¶

Usuario accede a configuración del medicamento
Usuario selecciona "Cambiar horarios"
Sistema muestra horarios actuales
Usuario modifica horario(s)
Sistema recalcula eventos afectados
Sistema muestra preview de nuevo calendario
Usuario confirma cambios
Sistema actualiza programación

4.7. Modo Viaje (MTS-CAL-001-F07)¶

4.7.1. Descripción¶

Ajusta automáticamente los horarios al cambiar de zona horaria.

4.7.2. Estrategias de Ajuste¶

Estrategia	Descripción	Uso
Mantener hora local	Ajustar a la nueva hora local	Viajes cortos
Mantener intervalo	Mantener tiempo entre tomas	Medicamentos críticos
Transición gradual	Ajuste progresivo durante días	Cambios grandes

4.7.3. Flujo: Activar Modo Viaje¶

Sistema detecta cambio de zona horaria
Sistema pregunta si usuario está de viaje
Usuario confirma viaje
Sistema pregunta duración estimada
Sistema muestra opciones de ajuste
Usuario selecciona estrategia
Sistema recalcula horarios
Sistema muestra nuevo calendario
Al regresar, sistema pregunta si restablecer

5. Reglas de Negocio¶

ID	Regla
RN-CAL-001	Ventana de toma por defecto: ±30 minutos
RN-CAL-002	Máximo 8 medicamentos por evento
RN-CAL-003	Mínimo 2 horas entre eventos (configurable)
RN-CAL-004	Toma registrada fuera de ventana se marca como "tardía"
RN-CAL-005	Posposición máxima: 4 horas
RN-CAL-006	Toma anticipada máxima: 2 horas antes
RN-CAL-007	Historial de tomas se mantiene indefinidamente
RN-CAL-008	Cambio de zona horaria > 3h activa modo viaje
RN-CAL-009	Eventos pasados no confirmados se marcan como "sin registrar"
RN-CAL-010	Calendario muestra 30 dias hacia adelante
RN-CAL-011	Eventos de salud (mediciones, tratamientos) se muestran junto con medicamentos
RN-CAL-012	Recordatorios de mediciones se programan segun template o configuracion manual
RN-CAL-013	Tratamientos con duracion muestran hora inicio y hora fin en calendario

6. Modelo de Datos¶

6.1. Entidad EventoToma¶

EventoToma {
  id: UUID (PK)
  usuario_id: UUID (FK)
  fecha: date
  hora_programada: time
  ventana_inicio: time
  ventana_fin: time
  momento: enum
  nombre_personalizado: string
  estado: enum [PENDIENTE, COMPLETADO, PARCIAL, OMITIDO, SIN_REGISTRAR]
  created_at: timestamp
  updated_at: timestamp
}

6.2. Entidad TomaProgramada¶

TomaProgramada {
  id: UUID (PK)
  evento_id: UUID (FK)
  medicamento_paciente_id: UUID (FK)
  dosis: string
  instrucciones: string
  orden: integer
  created_at: timestamp
}

6.3. Entidad RegistroToma¶

RegistroToma {
  id: UUID (PK)
  toma_programada_id: UUID (FK)
  estado: enum [TOMADO, OMITIDO, POSPUESTO]
  hora_registro: timestamp
  hora_real_toma: timestamp
  registrado_por: UUID (FK) -- paciente o cuidador
  motivo_omision: enum
  notas: text
  ubicacion: point (opcional)
  created_at: timestamp
}

6.4. Entidad HabitosUsuario¶

HabitosUsuario {
  id: UUID (PK)
  usuario_id: UUID (FK)
  tipo_dia: enum [LABORAL, FIN_SEMANA]
  hora_despertar: time
  hora_desayuno: time
  hora_almuerzo: time
  hora_cena: time
  hora_dormir: time
  created_at: timestamp
  updated_at: timestamp
}

7. Criterios de Aceptación¶

ID	Criterio
AC-001	Paciente puede configurar sus hábitos de horario
AC-002	Sistema sugiere horarios basados en hábitos y restricciones
AC-003	Medicamentos con horarios similares se agrupan en eventos
AC-004	Paciente puede confirmar toma desde notificación
AC-005	Paciente puede omitir toma indicando motivo
AC-006	Paciente puede posponer toma hasta 4 horas
AC-007	Calendario muestra estado visual de cada evento
AC-008	Sistema detecta cambio de zona horaria y sugiere ajuste
AC-009	Cuidador puede registrar tomas con permiso
AC-010	Historial de tomas accesible para consulta y exportación

8. API Endpoints (Iteracion 13)¶

Referencia: Ver 11-estandares-api.md para especificaciones completas.

8.1. Endpoints de Calendario¶

Metodo	Endpoint	Descripcion	Auth
GET	`/v1/calendar/events`	Listar eventos de toma	Bearer
GET	`/v1/calendar/events/{id}`	Detalle de evento	Bearer
POST	`/v1/calendar/events/{id}/complete`	Marcar toma como completada	Bearer
POST	`/v1/calendar/events/{id}/snooze`	Posponer toma	Bearer
POST	`/v1/calendar/events/{id}/skip`	Omitir toma con motivo	Bearer
GET	`/v1/calendar/reminders`	Listar recordatorios	Bearer
PUT	`/v1/calendar/reminders/{id}`	Actualizar recordatorio	Bearer

8.2. Request/Response Listar Eventos¶

8.2.1. Request¶

GET /v1/calendar/events?date=2025-12-03&status=pending

8.2.2. Response (200)¶

{
  "data": [
    {
      "id": "uuid",
      "type": "medication",
      "scheduled_time": "2025-12-03T08:00:00Z",
      "window_minutes": 30,
      "status": "pending",
      "medications": [
        {
          "id": "med_uuid",
          "name": "Metformina",
          "dosage": "850mg",
          "instructions": "Con alimentos"
        }
      ]
    }
  ]
}

8.3. Request/Response Completar Toma¶

8.3.1. Request¶

{
  "completed_at": "2025-12-03T08:15:00Z",
  "notes": "Tomado con desayuno"
}

8.3.2. Response (200)¶

{
  "data": {
    "id": "uuid",
    "status": "completed",
    "completed_at": "2025-12-03T08:15:00Z",
    "adherence_score": 95
  }
}

9. Referencias¶

Documento generado por SpecQueen - La especificación funcional ES el sistema.