Saltar a contenido

Modulo de Catalogo de Medicamentos

Identificador: MTS-CAT-001 Version: 1.2.0 Fecha: 2025-12-08 Ultima Revision: Iteracion 14 - Aviso de Privacidad en Busquedas (INV-015) Autor: SpecQueen Prioridad: ALTA (Esencial para v1.0) Dependencias: MTS-MED-001, MTS-INT-001

1. Proposito

Este modulo gestiona el catalogo centralizado de medicamentos disponibles en MedTime, incluyendo:

  • Base de datos de medicamentos por region
  • Normalizacion de nombres y codigos
  • Actualizacion periodica de datos
  • Busqueda y filtrado de medicamentos

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 Busca medicamentos para agregar a su tratamiento. Puede crear medicamentos personalizados.
Paciente Dependiente PD Visualiza catalogo. Cuidador gestiona agregado de medicamentos.
Cuidador Supervisor CS Sin acceso directo al catalogo. Solo visualiza medicamentos ya agregados al paciente.
Cuidador Responsable CR Puede buscar y agregar medicamentos en nombre del paciente.

2.1. Actores del Sistema

Actor Descripcion
Sistema Mantiene catalogo actualizado y normalizado
Wizard de Recetas Busca medicamentos automaticamente durante digitalizacion OCR. Referencia: MTS-REC-001
Administrador Gestiona fuentes de datos, actualizaciones y validacion de medicamentos personalizados

3. Fuentes de Datos

3.1. Fuentes por Region (ACL9-007)

Decision del Director Round 9: Base de datos propietaria como cache local + fuentes externas para validacion.

3.1.1. Fuentes Primarias

Fuente Tipo Region Contenido Licencia
Base MedTime Propietaria Global Catalogo unificado Propia
RxNorm (NIH) Publica USA Normalizacion Gratis
DrugBank Comercial Global Validacion Por API

3.1.2. Fuentes por Pais

Pais Fuente Organismo Tipo Actualizacion
Mexico Compendio CSG Consejo de Salubridad General Publica Anual
Mexico Registro COFEPRIS COFEPRIS Publica Mensual
Mexico Cuadro Basico IMSS IMSS Publica Semestral
USA FDA Orange Book FDA Publica Mensual
USA NDF-RT VA Publica Mensual
Brasil Lista RENAME ANVISA Publica Anual

Nota Iteración 13 (Dual Source México): El catálogo mexicano utiliza dos fuentes principales: CSG (Compendio de Medicamentos) para la base terapéutica y COFEPRIS (Registros Sanitarios) para validar comercialización legal. Medicamentos no encontrados en ninguna fuente pueden agregarse manualmente por el usuario (ver sección 4.5).

3.2. Arquitectura de Datos

flowchart TD
    subgraph Fuentes Externas
        RX[(RxNorm)]
        DB[(DrugBank)]
        CSG[(Compendio CSG)]
        FDA[(FDA Orange Book)]
        ANV[(ANVISA)]
    end

    subgraph Backend MedTime
        ETL[ETL - Extraccion y Transformacion]
        NORM[Normalizador]
        VALID[Validador]
        MASTER[(Master DB)]
    end

    subgraph Distribucion
        API[API Catalogo]
        DELTA[Generador de Deltas]
        PKG[Empaquetador Offline]
    end

    subgraph Dispositivos
        LOCAL[(Catalogo Local)]
    end

    RX --> ETL
    DB --> ETL
    CSG --> ETL
    FDA --> ETL
    ANV --> ETL

    ETL --> NORM
    NORM --> VALID
    VALID --> MASTER

    MASTER --> API
    MASTER --> DELTA
    MASTER --> PKG

    API --> LOCAL
    DELTA --> LOCAL
    PKG --> LOCAL

4. Funcionalidades

4.1. Estructura del Medicamento (MTS-CAT-001-F01)

MedicamentoCatalogo {
  id: UUID (PK)
  codigo_rxnorm: string (nullable)
  codigo_atc: string
  codigo_pais: string (ej: IMSS-001234)

  // Nombres
  nombre_generico: string
  nombre_generico_normalizado: string (lowercase, sin acentos)
  nombres_comerciales: array<string>
  nombres_comerciales_normalizados: array<string>

  // Composicion
  principios_activos: array<PrincipioActivo>
  forma_farmaceutica: enum
  concentracion: string
  concentracion_valor: decimal
  concentracion_unidad: string

  // Administracion
  via_administracion: enum
  instrucciones_default: text

  // Clasificacion
  clasificacion_atc: string
  categoria_terapeutica: string
  es_controlado: boolean
  requiere_receta: boolean

  // Regulacion
  paises_disponible: array<string>
  registro_sanitario: map<pais, registro>

  // Interacciones (referencia)
  interacciones_conocidas: integer (count)

  // Metadata
  fuente_primaria: string
  fecha_actualizacion: timestamp
  version: string
  activo: boolean

  created_at: timestamp
  updated_at: timestamp
}

PrincipioActivo {
  nombre: string
  codigo_rxnorm: string (nullable)
  concentracion: string
}

4.2. Busqueda de Medicamentos (MTS-CAT-001-F02)

4.2.1. Tipos de Busqueda

Tipo Descripcion Ejemplo
Por nombre generico Busca en nombres genericos "metformina"
Por nombre comercial Busca en marcas "Glucophage"
Por principio activo Busca en composicion "clorhidrato de metformina"
Por codigo de barras EAN/UPC del empaque "7501234567890"
Fonetica (fuzzy) Tolerante a errores "metformuna" -> "metformina"

4.2.2. Algoritmo de Busqueda

flowchart TD
    A[Usuario ingresa texto] --> B{Longitud >= 3?}
    B -->|No| C[Esperar mas caracteres]
    B -->|Si| D[Normalizar texto]

    D --> E[Buscar coincidencia exacta]
    E --> F{Resultados?}

    F -->|Si| G[Ordenar por relevancia]
    F -->|No| H[Buscar fuzzy]

    H --> I{Resultados fuzzy?}
    I -->|Si| G
    I -->|No| J[Sugerir agregar personalizado]

    G --> K[Mostrar resultados]
    K --> L[Incluir sugerencia Did you mean?]

4.2.3. Filtros de Busqueda

Filtro Opciones Default
Pais Mexico, USA, Brasil, Todos Segun region usuario
Forma farmaceutica Tableta, Capsula, Jarabe, etc. Todas
Via administracion Oral, Topica, Inyectable, etc. Todas
Requiere receta Si, No, Todos Todos

4.3. Arquitectura de Busqueda en Catalogo (MTS-CAT-001-F03)

Decision del Director (Iteracion 13):SIN CACHE LOCAL DEL CATALOGO

  • Todas las busquedas del catalogo requieren conexion a internet
  • Los medicamentos del usuario (MedicamentoPaciente) se almacenan localmente y funcionan 100% offline
  • Esta decision simplifica la arquitectura y reduce significativamente el tamano de la app
  • El catalogo completo reside en el servidor y se consulta bajo demanda

4.3.1. Arquitectura de Busqueda

Componente Ubicacion Descripcion
Catalogo Maestro Servidor Base de datos completa de medicamentos (50,000+)
API de Busqueda Servidor Endpoint para busquedas en tiempo real
Medicamentos del Usuario Dispositivo Lista de medicamentos agregados al tratamiento (offline)
Cache de Busquedas Recientes Dispositivo Ultimas 50 busquedas para autocompletado (7 dias)

4.3.2. Flujo de Busqueda (Requiere Conexion)

flowchart TD
    A[Usuario inicia busqueda] --> B{Hay conexion?}

    B -->|Si| C[Enviar query al servidor]
    B -->|No| D[Mostrar mensaje: Requiere conexion]

    C --> E[Servidor procesa busqueda]
    E --> F[Retornar resultados]
    F --> G[Mostrar al usuario]
    G --> H[Guardar en cache recientes]

    D --> I{Buscar en medicamentos del usuario?}
    I -->|Si| J[Buscar solo en lista local del paciente]
    I -->|No| K[Sugerir conectarse a internet]
    J --> L[Mostrar resultados limitados]

4.3.3. Disponibilidad Offline

Funcionalidad Disponible Offline Notas
Buscar en catalogo general NO Requiere conexion
Ver medicamentos del usuario SI Almacenados localmente
Agregar medicamento del catalogo NO Requiere conexion para buscar
Agregar medicamento personalizado SI Se guarda localmente, sync posterior
Autocompletado recientes SI Cache local de 50 items

4.3.4. Formato de Delta

{
  "version": "2025.12.02.001",
  "prev_version": "2025.11.15.001",
  "changes": {
    "added": [...],
    "modified": [...],
    "deprecated": [...]
  },
  "affected_interactions": [...],
  "checksum": "sha256..."
}

4.4. Medicamentos Personalizados (MTS-CAT-001-F05)

4.4.1. Descripcion

Cuando un medicamento no existe en el catalogo, el usuario puede agregarlo manualmente. Los medicamentos personalizados pueden enriquecer la base de datos oficial mediante un proceso de validacion.

4.4.2. Datos de Medicamento Personalizado

Campo Obligatorio Descripcion
nombre Si Nombre del medicamento
forma_farmaceutica Si Tipo de presentacion
concentracion No Dosis por unidad
via_administracion Si Como se administra
foto No Imagen del empaque
codigo_barras No Si esta disponible
pais_origen Si Pais donde se adquirio

4.4.3. Flujo de Creacion y Enriquecimiento de BD

Decision del Director (Iteracion 13): Los medicamentos personalizados pueden enriquecer la base de datos oficial mediante un proceso de validacion estructurado.

flowchart TD
    A[Usuario crea medicamento personalizado] --> B[Medicamento creado localmente]
    B --> C{Tiene conexion?}

    C -->|No| D[Guardar para sync posterior]
    C -->|Si| E[Sincronizar con servidor]

    D --> F[Medicamento disponible offline]
    E --> G[Sistema busca coincidencias automaticas]

    G --> H{Match encontrado en catalogo?}

    H -->|Si >= 90% similitud| I[Sugerir vincular con entrada existente]
    H -->|Si parcial 70-89%| J[Sugerir como posible duplicado]
    H -->|No < 70%| K[Marcar como candidato nuevo]

    I --> L{Usuario acepta vinculacion?}
    L -->|Si| M[Vincular y enriquecer datos del usuario]
    L -->|No| N[Mantener como personalizado separado]

    J --> O[Notificar equipo validacion]
    K --> O

    O --> P[Cola de Validacion MedTime]
    P --> Q{Validacion por equipo?}

    Q -->|Aprobado - Medicamento real| R[AGREGAR AL CATALOGO OFICIAL]
    Q -->|Rechazado - No valido| S[Marcar como solo-personal]
    Q -->|Requiere info| T[Solicitar mas datos al usuario]

    R --> U[Notificar usuario: Su aporte enriquecio BD]
    R --> V[Vincular automaticamente a usuarios con mismo med personalizado]

    T --> W{Usuario proporciona?}
    W -->|Si| P
    W -->|No timeout 30 dias| S

4.4.4. Proceso de Validacion para Enriquecimiento

Etapa Descripcion Tiempo Estimado
1. Recepcion Medicamento personalizado llega al servidor Inmediato
2. Matching automatico Algoritmo busca coincidencias en BD < 5 segundos
3. Cola de validacion Revision por equipo MedTime 24-72 horas
4. Verificacion externa Consulta en fuentes oficiales (COFEPRIS, FDA, etc.) Incluido en paso 3
5. Aprobacion/Rechazo Decision final Incluido en paso 3
6. Notificacion Informar al usuario del resultado Inmediato post-decision

4.4.5. Datos Requeridos para Validacion Exitosa

Dato Peso para Aprobacion Notas
Foto del empaque Alto Permite verificar registro sanitario
Codigo de barras Alto Validacion automatica contra BD comerciales
Nombre comercial exacto Medio Busqueda en registros oficiales
Laboratorio fabricante Medio Validacion de existencia
Pais de origen Alto Determina fuente de validacion

4.4.6. Beneficios del Enriquecimiento

Beneficiario Beneficio
Usuario que aporto Reconocimiento + datos enriquecidos automaticamente
Otros usuarios Medicamento disponible en busquedas futuras
Sistema MedTime Base de datos mas completa y regionalizada
Comunidad medica Mejor cobertura de medicamentos disponibles

5. Reglas de Negocio

ID Regla
RN-CAT-001 SIN CACHE LOCAL: Busquedas del catalogo requieren conexion a internet
RN-CAT-002 Busqueda requiere minimo 3 caracteres
RN-CAT-003 Resultados ordenados por: coincidencia exacta > pais usuario > popularidad
RN-CAT-004 Medicamentos del usuario (MedicamentoPaciente) se almacenan localmente - 100% offline
RN-CAT-005 Medicamentos personalizados pueden enriquecer BD oficial via proceso de validacion
RN-CAT-006 Cache de busquedas recientes: maximo 50 items, retencion 7 dias
RN-CAT-007 Medicamentos deprecados se marcan en servidor, no se eliminan
RN-CAT-008 Normalizacion de nombres elimina acentos y mayusculas
RN-CAT-009 Wizard de Recetas (MTS-REC-001) tiene acceso de solo lectura al catalogo
RN-CAT-010 Medicamentos personalizados aprobados se agregan al catalogo en 24-72 horas

6. Integraciones

6.1. Con Modulo de Medicamentos (MTS-MED-001)

Integracion Descripcion
Busqueda MTS-MED-001 usa MTS-CAT-001 para buscar medicamentos
Vinculacion Medicamentos del paciente referencian catalogo
Enriquecimiento Datos del catalogo enriquecen medicamentos del usuario

6.2. Con Motor de Interacciones (MTS-INT-001)

Integracion Descripcion
Codigos MTS-INT-001 usa codigos normalizados del catalogo
Referencias Interacciones referencian medicamentos por ID catalogo
Alertas Si medicamento deprecado, alertar sobre interacciones

7. Criterios de Aceptacion

ID Criterio
AC-001 Busqueda de medicamento por nombre retorna resultados en < 500ms (con conexion)
AC-002 Busqueda fuzzy sugiere correccion de errores tipograficos
AC-003 Medicamentos del usuario funcionan 100% offline
AC-004 Sin conexion, sistema informa claramente que busqueda requiere internet
AC-005 Usuario puede agregar medicamento personalizado si no existe (offline supported)
AC-006 Filtros de busqueda funcionan combinados
AC-007 Wizard de Recetas puede buscar medicamentos durante digitalizacion OCR
AC-008 Medicamentos personalizados entran a proceso de validacion para enriquecer BD
AC-009 Usuario recibe notificacion cuando su aporte es aprobado al catalogo

8. Consideraciones de Privacidad

Aspecto Implementacion
Historial de busquedas Solo local, no se envia al servidor
Medicamentos personalizados Free Solo en dispositivo
Medicamentos personalizados Pro/Perfect Subidos solo para matching, cifrados

8.1. Retención de Datos Locales (HIPAA-CAT-001)

Añadido Iteración 11: Política explícita de retención para historial de búsquedas.

Dato Retención Ubicación Sincronización
Historial de búsquedas Máximo 30 días Solo dispositivo NUNCA
Medicamentos recientes Máximo 50 items Solo dispositivo NUNCA
Cache de resultados 7 días Solo dispositivo NUNCA

Regla RN-CAT-009: El historial de búsquedas de medicamentos se almacena exclusivamente en el dispositivo local, con retención máxima de 30 días, y NUNCA se sincroniza al servidor para proteger la privacidad del paciente.

8.2. Aviso de Privacidad en Busquedas (INV-015)

Referencia: INV-015 - Investigacion sobre privacidad en busquedas de catalogos Referencia Tecnica: MTS-PRI-001 seccion 9 - Privacidad en Busquedas de Catalogos Publicos

8.2.1. Disclaimer de Privacidad

El sistema DEBE mostrar un aviso claro al usuario sobre como funcionan las busquedas en el catalogo:

Texto del Disclaimer:

+--------------------------------------------------+
| Aviso de Privacidad - Busqueda en Catalogo        |
+--------------------------------------------------+

Cuando buscas medicamentos en nuestro catalogo:

[Icono Check] Tu busqueda se envia a nuestros servidores
[Icono Check] NO sabemos quien eres (busqueda anonima)
[Icono Check] NO vemos que medicamento seleccionas
[Icono Check] NO vemos si lo agregas a tu tratamiento

Tus medicamentos y datos de salud siguen protegidos
con cifrado de extremo a extremo.

[ ] Activar busqueda automatica
    (No mostrar este aviso cada vez)

[Entendido, buscar]  [Cancelar]
+--------------------------------------------------+

8.2.2. Cuando se Muestra el Disclaimer

Escenario Comportamiento Toggle Visible
Primera busqueda manual Modal bloqueante con disclaimer completo Si - "Activar busqueda automatica"
Busqueda automatica habilitada Sin modal, busqueda directa No aplica
Busqueda manual posterior Texto informativo discreto en header Si - "Activar automatica" inline
Configuracion deshabilitada Modal cada vez que busca manualmente Si - En cada modal 
flowchart TD
    A[Usuario inicia busqueda] --> B{Es primera busqueda?}

    B -->|Si| C[Mostrar modal disclaimer]
    B -->|No| D{Busqueda automatica habilitada?}

    C --> E{Usuario acepta?}
    E -->|Si + Activa automatica| F[Guardar preferencia]
    E -->|Si sin automatica| G[Permitir busqueda unica]
    E -->|Cancela| H[No buscar]

    F --> I[Busquedas futuras sin modal]
    G --> J[Proximo vez mostrar modal de nuevo]

    D -->|Si| I
    D -->|No| K[Mostrar modal disclaimer]
    K --> E

8.2.3. Implicaciones para el Usuario

Aspecto Lo que Ocurre Privacidad
El servidor VE Texto de busqueda, timestamp Datos anonimos
El servidor NO VE Identidad del usuario user_id hasheado solo para rate-limit
El servidor NO VE Que medicamento selecciono Seleccion 100% local
El servidor NO VE Si agrego el medicamento Dato cifrado E2E

Mensaje Clave para el Usuario:

"Podemos ver QUE buscaste, pero no sabemos QUIEN eres ni que HICISTE con los resultados."

8.2.4. Configuracion de Preferencias

El usuario puede cambiar su preferencia en cualquier momento:

Ubicacion Ruta Opciones
Configuracion App Ajustes > Privacidad > Busquedas Toggle On/Off
Durante busqueda Modal disclaimer Checkbox "Activar automatica"

Preferencia por Default: Deshabilitada (mostrar disclaimer cada vez)

8.2.5. Reglas de Negocio - Disclaimer

Regla Descripcion
RN-CAT-011 Disclaimer obligatorio antes de primera busqueda en catalogo
RN-CAT-012 Usuario puede habilitar/deshabilitar busqueda automatica en cualquier momento
RN-CAT-013 Preferencia de busqueda automatica se almacena localmente (no sincronizada)
RN-CAT-014 Cambio de preferencia no requiere re-autenticacion

9. Casos de Error (Iteración 11)

Añadido Iteración 11: Documentación de casos de error para mejorar cobertura de 61% a 85%.

9.1. ERR-CAT-001: Búsqueda sin resultados

Campo Valor
Código ERR-CAT-001
Descripción Usuario busca medicamento que no existe en catálogo
Causa Medicamento no incluido, nombre incorrecto, error tipográfico
Acción Usuario Verificar nombre, usar búsqueda fuzzy, agregar como personalizado
Acción Sistema Mostrar sugerencias fuzzy, ofrecer agregar personalizado

Pantalla de Error:

+--------------------------------------------------+
| No encontramos "[búsqueda]"                       |
+--------------------------------------------------+

¿Quisiste decir?
  • Metformina
  • Metoprolol

¿No está en la lista?
[+ Agregar medicamento personalizado]

Consejos:
• Verifica la ortografía
• Intenta con el nombre genérico
• Busca por principio activo

+--------------------------------------------------+

9.2. ERR-CAT-002: Fallo en descarga delta

Campo Valor
Código ERR-CAT-002
Descripción Actualización incremental del catálogo falla
Causa Conexión interrumpida, servidor no disponible, archivo corrupto
Acción Usuario Reintentar más tarde, verificar conexión
Acción Sistema Reintentar 3 veces, usar catálogo anterior, notificar

Flujo de Recuperación:

flowchart TD
    A[Iniciar descarga delta] --> B{Descarga exitosa?}
    B -->|Sí| C[Aplicar actualización]
    B -->|No| D{Intento < 3?}
    D -->|Sí| E[Esperar 30s] --> A
    D -->|No| F[Mantener catálogo anterior]
    F --> G[Notificar usuario]
    G --> H["Catálogo actualizado hace X días.
            Se actualizará cuando haya conexión."]

Regla: El catálogo anterior sigue funcionando hasta la próxima actualización exitosa.

9.3. ERR-CAT-003: Espacio insuficiente para cache

Campo Valor
Código ERR-CAT-003
Descripción Dispositivo sin espacio para almacenar catálogo
Causa Almacenamiento lleno, cache acumulado
Acción Usuario Liberar espacio en dispositivo
Acción Sistema Limpiar cache antiguo, usar catálogo compacto

Pantalla de Error:

+--------------------------------------------------+
| Espacio insuficiente                              |
+--------------------------------------------------+

MedTime necesita ~50 MB para actualizar el
catálogo de medicamentos.

Espacio disponible: 12 MB

Opciones:
[Limpiar cache de MedTime] (Libera ~30 MB)
[Abrir configuración del dispositivo]
[Continuar sin actualizar]

+--------------------------------------------------+

Estrategia de Limpieza:

Elemento Prioridad de eliminación
Cache de búsquedas antiguas 1 (primero)
Imágenes de recetas en baja resolución 2
Historial de más de 90 días 3
Catálogo de medicamentos (última versión) NUNCA

9.4. ERR-CAT-004: Corrupción de cache local

Campo Valor
Código ERR-CAT-004
Descripción Base de datos local corrupta, no se puede leer
Causa Cierre forzado, error de escritura, falla de hardware
Acción Usuario Permitir reconstrucción automática
Acción Sistema Detectar corrupción, reconstruir desde backup/servidor

Flujo de Recuperación:

flowchart TD
    A[Detectar corrupción en inicio] --> B{Hay backup local?}
    B -->|Sí| C[Restaurar desde backup]
    B -->|No| D{Hay conexión?}
    D -->|Sí| E[Descargar catálogo completo]
    D -->|No| F[Modo degradado]

    C --> G[Verificar integridad]
    E --> G
    G --> H{Integridad OK?}
    H -->|Sí| I[Operación normal]
    H -->|No| J[Notificar soporte]

    F --> K["Búsqueda limitada.
            Conecte a internet para restaurar."]

Mensaje al Usuario:

+--------------------------------------------------+
| Restaurando catálogo                              |
+--------------------------------------------------+

Detectamos un problema con el catálogo local.
Estamos restaurándolo automáticamente.

[=====>              ] 35%

Esto puede tomar unos minutos.
Tus medicamentos y tomas NO se ven afectados.

+--------------------------------------------------+

10. Referencias

Documento generado por SpecQueen - La especificacion funcional ES el sistema.