Saltar a contenido

Modulo de Lista de Medicamentos del Paciente

Identificador: MTS-MED-001 Version: 1.3.0 Fecha: 2025-12-05 Ultima Revision: Iteracion 13 - OBS-065 Renombrar para diferenciar de MTS-CAT-001 Autor: SpecQueen

IMPORTANTE - Distincion con MTS-CAT-001 (OBS-065): - MTS-MED-001 (este documento): Lista PERSONAL de medicamentos del PACIENTE - los tratamientos activos que el usuario toma. - MTS-CAT-001: Catalogo MAESTRO de medicamentos - base de datos centralizada de referencia.

Este modulo gestiona los medicamentos que el paciente tiene configurados en su tratamiento personal, no el catalogo de referencia.

1. Proposito

Este modulo gestiona la lista personal de medicamentos del paciente: los tratamientos activos que el usuario toma, su configuracion de dosificacion, horarios e instrucciones especiales.

Nota de Clarificacion (OBS-065): - La busqueda en el catalogo maestro (base de datos de referencia) se documenta en MTS-CAT-001. - Este modulo (MTS-MED-001) gestiona la lista personal del paciente, que referencia al catalogo pero es independiente.

2. Actores

Actor Descripción
Paciente Gestiona sus medicamentos activos
Cuidador Visualiza medicamentos (con permiso)
Sistema Valida interacciones y configura alertas

3. Funcionalidades

3.1. Referencia al Catalogo de Medicamentos (Ver MTS-CAT-001)

OBS-065: El catalogo maestro de medicamentos se documenta en MTS-CAT-001-catalogo-medicamentos.md.

Este modulo (MTS-MED-001) se enfoca en la lista personal del paciente, que utiliza el catalogo como referencia.

3.1.1. Relacion con MTS-CAT-001

Aspecto MTS-CAT-001 (Catalogo) MTS-MED-001 (Lista Paciente)
Proposito Base de datos de referencia Tratamientos personales
Datos Informacion generica de medicamentos Configuracion especifica del paciente
Almacenamiento Cache local + servidor Cifrado E2E en dispositivo/nube
Actualizacion Periodica desde fuentes oficiales Por el paciente
Ejemplo "Metformina 850mg existe" "Yo tomo Metformina 850mg a las 8am"

3.1.2. Flujo de Seleccion de Medicamento

  1. Paciente busca medicamento en catalogo (MTS-CAT-001)
  2. Paciente selecciona medicamento del catalogo
  3. Sistema crea entrada en lista personal (MTS-MED-001)
  4. Paciente configura dosis, horarios, instrucciones
  5. Medicamento personal queda vinculado a referencia del catalogo (opcional)

3.2. Medicamentos del Paciente (MTS-MED-001-F02)

3.2.1. Descripción

Gestión de los medicamentos que el paciente toma actualmente.

3.2.2. Estructura del Medicamento del Paciente

Campo Tipo Obligatorio Descripción
id UUID Sí Identificador único
medicamento_id UUID Sí Referencia al catálogo
nombre_personalizado string No Nombre dado por el paciente
dosis string Sí Cantidad por toma (ej: "500mg")
unidad_dosis enum Sí mg, ml, tabletas, gotas, etc.
frecuencia object Sí Configuración de horarios
duracion object No Duración del tratamiento
instrucciones string No Instrucciones especiales
recordatorios object Sí Configuración de alertas
color_etiqueta string No Color para identificación visual
icono string No Ícono personalizado
receta_id UUID No Receta asociada
medico_prescriptor string No Nombre del médico
fecha_inicio date Sí Inicio del tratamiento
fecha_fin date No Fin del tratamiento
estado enum Sí ACTIVO, PAUSADO, FINALIZADO
motivo_pausa string No Razón de pausa
notas string No Notas adicionales

3.2.3. Tipos de Frecuencia

Tipo Descripción Ejemplo
DIARIA Cada día a horas fijas 8:00, 14:00, 20:00
INTERVALO Cada X horas Cada 8 horas
DIAS_SEMANA Días específicos Lunes, Miércoles, Viernes
DIAS_MES Días del mes Día 1 y 15 de cada mes
CICLOS Ciclos de tratamiento 21 días sí, 7 días no
CONDICIONAL Según necesidad Cuando hay dolor

3.2.4. Flujo: Añadir Medicamento Manualmente

  1. Paciente selecciona "Añadir Medicamento"
  2. Sistema muestra barra de búsqueda
  3. Paciente busca medicamento por nombre
  4. Sistema muestra resultados coincidentes
  5. Paciente selecciona medicamento
  6. Sistema muestra formulario de configuración:
  7. Dosis
  8. Frecuencia
  9. Horarios
  10. Instrucciones especiales
  11. Duración del tratamiento
  12. Sistema sugiere horarios basados en frecuencia
  13. Paciente ajusta horarios según sus hábitos
  14. Sistema verifica interacciones con medicamentos existentes
  15. Si hay interacciones, sistema muestra advertencia
  16. Paciente confirma configuración
  17. Sistema activa medicamento y programa alertas

3.2.5. Flujo Alternativo: Medicamento No Encontrado

  1. Paciente no encuentra medicamento en catálogo
  2. Paciente selecciona "Añadir medicamento personalizado"
  3. Sistema muestra formulario extendido:
  4. Nombre del medicamento
  5. Forma farmacéutica
  6. Concentración
  7. Vía de administración
  8. Sistema solicita foto del medicamento (opcional)
  9. Paciente completa configuración normal
  10. Sistema registra medicamento personalizado
  11. Sistema marca para revisión/matching posterior

3.3. Detección de Interacciones (MTS-MED-001-F03)

3.3.1. Descripción

Verificación automática de interacciones entre medicamentos.

3.4. Fuentes de Datos de Interacciones (ACL9-007)

Decision del Director Round 9 (PREG-R9-007): Opcion B - Base de datos propietaria + DrugBank para validacion comercial.

3.4.1. Fuentes Primarias

Fuente Tipo Region Uso
Base propia MedTime Propietaria Global Cache local offline
DrugBank Comercial Global Validacion online (Pro/Perfect)
RxNorm (NIH) Publica USA Normalizacion de codigos

3.4.2. Fuentes Secundarias (por region)

Region Fuente Tipo Uso
Mexico Compendio CSG Publica Catalogo base
Mexico COFEPRIS Publica Regulacion
USA FDA Orange Book Publica Equivalentes
Brasil ANVISA Publica Regulacion

3.4.3. Arquitectura de Datos de Interacciones

flowchart TD
    subgraph Fuentes
        DB[(DrugBank)]
        RX[(RxNorm)]
        FP[(Fuentes Pais)]
    end

    subgraph Backend MedTime
        PROC[Procesador de datos]
        VAL[Validador de interacciones]
        CACHE[Cache de interacciones]
    end

    subgraph Dispositivo
        LOCAL[(Base local)]
        MOTOR[Motor de deteccion]
    end

    DB --> PROC
    RX --> PROC
    FP --> PROC

    PROC --> VAL
    VAL --> CACHE
    CACHE --> LOCAL

    LOCAL --> MOTOR

3.4.4. Actualizacion de Datos

Tier Actualizacion Frecuencia
Free Solo con nueva version de app Variable
Pro Descarga automatica Mensual
Perfect Descarga automatica + notificacion Quincenal

3.4.5. Licenciamiento y Costos

Fuente Tipo Licencia Costo Estimado
DrugBank Comercial Por consulta API
RxNorm Publica (NIH) Gratis
Compendio CSG Publica Gratis
Base propia Propietaria Desarrollo interno

3.4.6. Disclaimer por Fuente

Cada interaccion mostrada incluye:

  • Fuente del dato
  • Fecha de ultima actualizacion
  • Nivel de confianza
  • Disclaimer obligatorio

3.4.7. Disponibilidad por Tier

Tier Verificación de Interacciones
Free Solo caché local (sin actualización online)
Pro Caché local + IA on-demand (pago adicional)
Perfect Caché local + IA incluida

Disclaimer obligatorio: "Información solo orientativa. Consulte siempre con su médico o farmacéutico."

3.4.8. Niveles de Severidad

Nivel Descripción Acción
CONTRAINDICADO No deben usarse juntos Bloqueo con advertencia fuerte
SERIO Riesgo significativo Advertencia prominente
MODERADO Precaución necesaria Advertencia informativa
MENOR Riesgo mínimo Nota informativa

3.4.9. Flujo de Verificación

  1. Sistema detecta nuevo medicamento o cambio
  2. Sistema consulta base de interacciones
  3. Sistema cruza contra medicamentos activos del paciente
  4. Si hay interacciones:
  5. Sistema clasifica por severidad
  6. Sistema muestra alerta apropiada
  7. Sistema registra en historial
  8. Si es CONTRAINDICADO:
  9. Sistema requiere confirmación explícita
  10. Sistema solicita razón de continuación
  11. Sistema registra decisión

3.4.10. Información de Interacción

Campo Descripción
medicamentos Par de medicamentos involucrados
severidad Nivel de riesgo
descripcion Explicación de la interacción
efecto Qué puede ocurrir
recomendacion Qué hacer al respecto
fuente Referencia científica

3.5. Gestión de Inventario Personal (MTS-MED-001-F04)

3.5.1. Descripción

Seguimiento de existencias de medicamentos del paciente.

3.5.2. Datos de Inventario

Campo Tipo Descripción
medicamento_paciente_id UUID Referencia al medicamento
cantidad_actual number Unidades disponibles
cantidad_alerta number Umbral para alerta de reabasto
fecha_caducidad date Vencimiento del lote actual
lote string Número de lote (opcional)
ultimo_reabasto date Fecha de última compra

3.5.3. Flujo: Alerta de Reabasto

  1. Sistema calcula consumo proyectado
  2. Sistema detecta que cantidad llegará a umbral en X días
  3. Sistema envía alerta de reabasto con anticipación
  4. Alerta incluye:
  5. Medicamento a reabastecer
  6. Cantidad recomendada
  7. Días restantes estimados
  8. Paciente puede:
  9. Marcar como "Ya comprado"
  10. Posponer recordatorio
  11. Actualizar cantidad actual

3.5.4. Flujo: Alerta de Caducidad

  1. Sistema detecta medicamento próximo a caducar (30 días)
  2. Sistema envía alerta de caducidad
  3. Alerta incluye:
  4. Medicamento por caducar
  5. Fecha de caducidad
  6. Cantidad restante
  7. Recomendación de no usar después de fecha

3.6. Historial de Medicamentos (MTS-MED-001-F05)

3.6.1. Descripción

Registro histórico de todos los medicamentos del paciente.

3.6.2. Información del Historial

Dato Descripción
Medicamento Nombre y configuración
Período Fecha inicio - fecha fin
Motivo de finalización Terminó tratamiento, cambio, etc.
Adherencia Porcentaje de adherencia durante el período
Notas Observaciones del paciente
Anomalías Problemas reportados

3.6.3. Exportación de Historial

Formatos disponibles:

  • PDF (informe formateado)
  • CSV (datos tabulares)
  • HL7 FHIR (interoperabilidad)

4. Reglas de Negocio

Referencia Canónica (Iteración 11): Las reglas de negocio centrales se encuentran en 06-reglas-de-negocio.md. Este módulo contiene reglas específicas de implementación. Ver RN-MED-001 a RN-MED-008 y RN-MED-LIM-001 a RN-MED-LIM-004 en el documento central.

4.1. Medicamentos por Tier (Iteracion 13)

Actualizado en Iteracion 13: Por decision del Director, NINGUN tier tiene limite de medicamentos activos.

Tier Medicamentos Activos Medicamentos Historicos
Free Ilimitados Ilimitado
Pro Ilimitados Ilimitado
Perfect Ilimitados Ilimitado

Notas:

  • Soft limit de 100 medicamentos genera advertencia de rendimiento (todos los tiers)
  • Medicamentos FINALIZADOS no aparecen en lista principal pero se mantienen en historial
ID Regla
RN-MED-001 Todos los tiers pueden tener medicamentos activos ilimitados
RN-MED-002 Interacción CONTRAINDICADA requiere confirmación explícita
RN-MED-003 Alerta de reabasto se envía 7 días antes de agotarse
RN-MED-004 Alerta de caducidad se envía 30 días antes
RN-MED-005 Medicamento pausado no genera alertas de toma
RN-MED-006 Historial de medicamentos se mantiene indefinidamente
RN-MED-007 Medicamentos finalizados no aparecen en lista principal
RN-MED-008 Cambio de dosis crea nuevo registro en historial
RN-MED-009 Medicamentos personalizados se marcan para revisión
RN-MED-010 Catálogo se actualiza mensualmente de fuentes oficiales

5. Modelo de Datos

MedicamentoCatalogo {
  id: UUID (PK)
  codigo_rxnorm: string
  codigo_pais: string
  nombre_generico: string
  nombres_comerciales: array
  principios_activos: array
  forma_farmaceutica: enum
  concentracion: string
  via_administracion: enum
  clasificacion_atc: string
  requiere_receta: boolean
  paises_disponible: array
  interacciones_ids: array
  contraindicaciones: array
  efectos_secundarios: array
  instrucciones_default: text
  activo: boolean
  created_at: timestamp
  updated_at: timestamp
}

5.2. Entidad MedicamentoPaciente

MedicamentoPaciente {
  id: UUID (PK)
  usuario_id: UUID (FK)
  medicamento_catalogo_id: UUID (FK, nullable)
  nombre: string (encrypted)
  nombre_personalizado: string (encrypted)
  dosis: string (encrypted)
  unidad_dosis: enum
  frecuencia_tipo: enum
  frecuencia_config: jsonb (encrypted)
  instrucciones: text (encrypted)
  color_etiqueta: string
  icono: string
  receta_id: UUID (FK, nullable)
  medico_prescriptor: string (encrypted)
  fecha_inicio: date
  fecha_fin: date
  estado: enum [ACTIVO, PAUSADO, FINALIZADO]
  motivo_cambio_estado: string
  notas: text (encrypted)
  created_at: timestamp
  updated_at: timestamp
}

5.3. Entidad InventarioMedicamento

InventarioMedicamento {
  id: UUID (PK)
  medicamento_paciente_id: UUID (FK)
  cantidad_actual: decimal
  cantidad_alerta: decimal
  fecha_caducidad: date
  lote: string
  ultimo_reabasto: date
  created_at: timestamp
  updated_at: timestamp
}

5.4. Entidad InteraccionMedicamento

InteraccionMedicamento {
  id: UUID (PK)
  medicamento_a_id: UUID (FK)
  medicamento_b_id: UUID (FK)
  severidad: enum [CONTRAINDICADO, SERIO, MODERADO, MENOR]
  descripcion: text
  efecto: text
  recomendacion: text
  fuente: string
  created_at: timestamp
  updated_at: timestamp
}

6. Criterios de Aceptación

ID Criterio
AC-001 Paciente puede buscar medicamentos por nombre genérico o comercial
AC-002 Paciente puede añadir medicamento del catálogo con configuración personalizada
AC-003 Paciente puede añadir medicamento personalizado si no está en catálogo
AC-004 Sistema detecta y muestra interacciones entre medicamentos
AC-005 Interacciones CONTRAINDICADAS requieren confirmación explícita
AC-006 Sistema envía alertas de reabasto 7 días antes de agotarse
AC-007 Sistema envía alertas de caducidad 30 días antes
AC-008 Paciente puede pausar medicamento sin eliminarlo
AC-009 Historial de medicamentos exportable en PDF, CSV, FHIR
AC-010 Cuidador puede ver medicamentos si tiene permiso otorgado

7. Casos de Error

7.1. ERR-MED-001: Toma Fuera de Ventana de Tiempo

Campo Valor
Código ERR-MED-001
Descripción Usuario intenta registrar toma fuera de la ventana configurada
Causa Toma muy anticipada (>2hr antes) o muy tardía (>ventana configurada)
Detección Timestamp de registro vs hora programada
Acción Usuario Mostrar: "Esta toma está fuera del horario. ¿Deseas registrarla de todos modos?" con opciones [Registrar como tardía] [Registrar hora real] [Cancelar]
Acción Sistema Si confirma: registrar con flag fuera_ventana=true, afectar estadísticas de adherencia proporcionalmente
Severidad Baja
Recuperación Usuario decide, sistema registra con metadata apropiada

7.2. ERR-MED-002: Conflicto Dosis Registradas vs Inventario

Campo Valor
Código ERR-MED-002
Descripción Dosis registradas no coinciden con inventario disponible
Causa Usuario no actualizó inventario, reabasto no registrado, pérdida de medicamento
Detección cantidad_actual < 0 después de registrar toma
Acción Usuario Mostrar: "El inventario muestra [X] unidades pero has registrado más tomas. ¿Actualizamos?" con opciones [Actualizar inventario] [Ignorar]
Acción Sistema Log discrepancia, ofrecer reconciliación, no bloquear registro de toma
Severidad Baja
Recuperación Reconciliación manual de inventario
Campo Valor
Código ERR-MED-003
Descripción Búsqueda de medicamento no retorna resultados
Causa Nombre incorrecto, medicamento no indexado, medicamento descontinuado
Detección Query retorna 0 resultados
Acción Usuario Mostrar sugerencias fuzzy + opción "Agregar medicamento personalizado"
Acción Sistema Log búsqueda fallida para mejorar catálogo, ofrecer agregar manualmente
Severidad Baja
Recuperación Usuario agrega medicamento personalizado o corrige búsqueda

7.4. ERR-MED-004: Interacción Crítica Ignorada

Campo Valor
Código ERR-MED-004
Descripción Usuario intenta agregar medicamento con interacción CONTRAINDICADA
Causa Combinación peligrosa de medicamentos
Detección Motor de interacciones detecta severidad=CONTRAINDICADO
Acción Usuario Bloqueo con advertencia: "Esta combinación está CONTRAINDICADA. Requiere confirmación explícita." [Entiendo el riesgo, continuar] [Cancelar]
Acción Sistema Requerir motivo de continuación, registrar en audit log, alertar cuidadores si existen
Severidad Alta
Recuperación Usuario confirma con justificación o cancela

7.5. Reglas de Manejo de Errores

ID Regla
RN-ERR-MED-001 Errores de inventario no bloquean registro de tomas
RN-ERR-MED-002 Interacciones CONTRAINDICADAS siempre requieren confirmación
RN-ERR-MED-003 Todas las discrepancias se registran para analytics
RN-ERR-MED-004 Usuario siempre puede agregar medicamento personalizado

8. API Endpoints (Iteracion 13)

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

8.1. Endpoints de Medicamentos

Metodo Endpoint Descripcion Auth
GET /v1/medications Listar medicamentos del usuario Bearer
POST /v1/medications Agregar medicamento a tratamiento Bearer
GET /v1/medications/{id} Obtener detalle de medicamento Bearer
PUT /v1/medications/{id} Actualizar medicamento Bearer
DELETE /v1/medications/{id} Eliminar medicamento Bearer
GET /v1/catalog/search Buscar en catalogo de medicamentos Bearer
GET /v1/catalog/{id} Detalle de medicamento en catalogo Bearer
POST /v1/medications/interactions Verificar interacciones Bearer

8.2.1. Request

GET /v1/catalog/search?q=paracetamol&limit=10

8.2.2. Response (200)

{
  "data": [
    {
      "id": "uuid",
      "nombre_generico": "Paracetamol",
      "nombre_comercial": ["Tylenol", "Tempra"],
      "forma_farmaceutica": "tableta",
      "concentracion": "500mg"
    }
  ],
  "meta": {
    "pagination": {
      "total_items": 15,
      "page": 1,
      "per_page": 10
    }
  }
}

8.3. Request/Response Verificar Interacciones

8.3.1. Request

{
  "medication_ids": ["uuid1", "uuid2", "uuid3"]
}

8.3.2. Response (200)

{
  "data": {
    "interactions": [
      {
        "medication_a": "uuid1",
        "medication_b": "uuid2",
        "severity": "MODERATE",
        "description": "Puede aumentar el efecto...",
        "recommendation": "Monitorear..."
      }
    ],
    "safe_combinations": 2,
    "warnings": 1
  }
}

9. Referencias

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