MEMORIA TÉCNICA

El sistema WHeat-Jobs | Fenotipo no se limita a la recopilación pasiva de variables biométricas o clínicas, sino que integra múltiples capas funcionales destinadas a la interpretación estructurada del estado fisiológico y de su evolución temporal.

---

8.1. Construcción de la Colección de Datos Funcionales

El sistema genera un objeto funcional unificado, HealthDashDataBundle, que agrupa perfil personal, biometría diaria y analítica clínica relevante.

---

8.2. Coexistencia de motores hardcoded y declarativo

La coexistencia de ambos motores permite verificar la equivalencia lógica entre implementaciones y facilita la evolución progresiva del sistema sin pérdida de consistencia histórica.

---

8.3. Persistencia del contexto completo de cálculo

Cada cálculo se registra junto con su contexto funcional, incluyendo fecha efectiva, intervalo biométrico, analítica clínica, edad fisiológica y regla o motor utilizado.

---

8.4. Importación estructurada y normalización de datos externos

El sistema transforma exportaciones externas en registros diarios internos normalizados mediante persistencia del XML, reducción semanal, agregación diaria y transformación a BiodataDiaria.

VO2 máx: el campo Vo2Max (ml/kg/min) recoge el último VO2 máximo estimado por el dispositivo. A diferencia de las variables acumulativas o promediadas, es una medida esporádica: una lectura nueva sustituye al valor y, si un día no trae lectura, se conserva el último valor conocido (sin límite de antigüedad); un dato ausente nunca lo pone a nulo. Se alimenta desde los cuatro canales de importación: XML de Apple (HKQuantityTypeIdentifierVO2Max, fuente reloj, última lectura del día), JSON de Health Auto Export (métrica vo2_max, lectura más reciente del día), webhook de Health Connect (clave vo2_max, campo ml_per_kg_per_min, según la documentación del proyecto) y exportación ZIP de Google (lectura tolerante por nombre de fichero). El arrastre a días sin lectura se aplica en los pipelines de Apple (XML y JSON) y en la exportación de Google.

---

8.5. Subsistema longitudinal de tendencias sobre BiodataDiaria

Esta capa permite observar la evolución de variables fisiológicas directas y resumir el comportamiento reciente del usuario mediante valores actuales, medias, variaciones y calificación operativa.

---

8.6. Motor estructural de agregación diaria

El motor admite el tratamiento estructural de nodos simples y compuestos mediante lectura XML en streaming.

---

8.7. Análisis metabólico diario y dinámica energética funcional

El sistema incorpora una capa específica de análisis energético-metabólico diario, diferenciada del motor general de scores, que permite interpretar el estado funcional del día a partir de ingesta, gasto basal, gasto activo, balance energético, distribución de macronutrientes, alcohol y proteína relativa al peso corporal.

Esta capa se apoya en una fuente determinista centralizada, EnergyDailyBalance, y utiliza una regla única de clasificación del estado energético, evitando inconsistencias entre vistas, prompts e interpretaciones auxiliares.

Junto al análisis metabólico diario, el sistema dispone de una vista de dinámica metabólica que representa visualmente la disponibilidad energética funcional mediante balance acumulado por fases e índice relativo sintético.

---

8.8. Arquitectura modular y evolución progresiva

La estructura general permite sustituir motores internos, introducir nuevas variables, extender el modelo declarativo y adaptar nuevas fuentes externas sin ruptura funcional.

---

8.9. Integración de módulos de asistencia inteligente mediante modelos IA

El sistema incorpora módulos de asistencia funcional basados en modelos de lenguaje ejecutados mediante IA. Estos módulos no sustituyen la lógica determinista del sistema, sino que actúan como capa auxiliar.

En su estado actual, la integración IA se articula en los siguientes módulos: análisis nutricional de ingesta (estimación de macronutrientes y valor energético a partir de alimentos registrados), resumen interpretativo de evolución de BiodataDiaria, análisis integrado de HealthDash (síntesis en lenguaje natural del estado fisiológico global, sin carácter diagnóstico), interpretación de dinámica metabólica, importación automática de analítica clínica desde PDF (extracción de biomarcadores con conversión de unidades por laboratorio) y revisión histórica parcial con resumen IA (informe longitudinal del período seleccionado con estado funcional, balance energético, nutrición, analítica clínica y recomendaciones priorizadas). Todos ellos operan sobre datos del usuario o sobre resultados previamente calculados por los motores internos del sistema.

La utilización de modelos de lenguaje no altera la autoría sobre la concepción, organización lógica, arquitectura, validación y control final del sistema.

---

8.10. Arquitectura de procesamiento IA en segundo plano

Las llamadas a modelos de lenguaje, cuyo tiempo de respuesta puede oscilar entre 10 y 90 segundos, se procesan mediante una arquitectura de cola asíncrona en segundo plano basada en IHostedService y Channel<T>.

Esta arquitectura desacopla la solicitud del usuario de la espera bloqueante, permitiendo que la interfaz muestre un indicador de progreso con estimación de tiempo mientras el resultado se almacena en un ConcurrentDictionary y se recupera mediante polling desde el cliente. El tiempo estimado se calibra dinámicamente a partir de mediciones históricas del propio sistema.

---

8.11. Sistema declarativo de gestión de prompts IA

El sistema incorpora una arquitectura declarativa propia para la gestión, composición y versionado de los prompts utilizados por los módulos de asistencia inteligente. Esta arquitectura permite modificar, extender y versionar el comportamiento de los módulos IA sin necesidad de alterar el código fuente.

La estructura se compone de tres entidades persistidas: IaPromptTemplate, que define la plantilla activa identificada por un código funcional y una versión semántica, con system prompt y user prompt propios; IaPromptBlock, que representa bloques de contenido reutilizables y versionados de forma independiente; y IaPromptTemplateBlock, que establece la composición ordenada de bloques dentro de cada plantilla mediante SortOrder.

El servicio IaPromptBuilderService actúa como motor de construcción: localiza la versión activa más reciente de la plantilla identificada por su código, une los bloques activos en orden, e interpola las variables de contexto mediante sintaxis {{NombreVariable}}, produciendo el par SystemPrompt / UserPrompt final que recibe el modelo.

El sistema incluye una consola de administración dedicada que permite gestionar plantillas, bloques y composiciones sin intervención sobre el código fuente, preservando la trazabilidad entre versiones de prompt y resultados producidos.

---

8.12. Subsistema de importación automática de analíticas clínicas desde PDF

El sistema incorpora un subsistema específico para la ingestión de informes de laboratorio en formato PDF, orientado a poblar automáticamente la entidad AnaliticaClinica sin introducción manual de valores.

A diferencia de las arquitecturas habituales basadas en OCR + extracción de texto, el subsistema envía el PDF directamente como documento nativo en base64 al modelo claude-haiku a través de AnthropicClient con DocumentContent / DocumentSource / SourceType.base64, delegando en el modelo la capacidad de comprensión estructurada del informe.

El sistema aplica un conjunto de reglas críticas de escala en el prompt, necesarias porque los laboratorios expresan magnitudes hematológicas con notación científica variable (×10⁶/µL, ×10³/µL, M/µL, K/µL) y algunos parámetros bioquímicos pueden aparecer en unidades distintas según el laboratorio:

• Hematología: extrae siempre el coeficiente (4,47 de "4,47 × 10⁶/µL"), nunca el valor absoluto.
• PCR: convierte mg/dL → mg/L (×10) si el laboratorio informa en mg/dL.
• Urea: convierte mmol/L → mg/dL (×6,006) si el laboratorio informa en mmol/L.
• Calcio: convierte mmol/L → mg/dL (×4,008).
• Fósforo: convierte mmol/L → mg/dL (×3,097).
• T4 Libre: convierte pmol/L → ng/dL (÷12,87).

La respuesta del modelo se deserializa mediante JsonSerializer con JsonNumberHandling.AllowReadingFromString a un DTO interno (AnaliticaJsonDto), que se mapea a AnaliticaClinica antes de presentarse al usuario.

El flujo de revisión introduce una pantalla intermedia (RevisarImport) que muestra todos los valores extraídos organizados por categoría clínica (serie roja / hemostasia, leucocitos, metabolismo / lípidos, enzimas / renal, micronutrientes / tiroides, orina), con un semáforo de rangos de referencia (verde ✓ / rojo ⚠️) que permite al usuario detectar visualmente cualquier error de escala antes de persistir.

La vista incluye un botón de información que documenta, campo a campo, las conversiones de unidad aplicadas y los rangos esperados por laboratorio, garantizando trazabilidad y transparencia del proceso de importación.

---

8.13. Módulo de revisión histórica parcial con resumen IA

El sistema incorpora un módulo de revisión histórica longitudinal que permite al usuario generar, para cualquier período seleccionado, un informe integrado que consolida todas las dimensiones funcionales disponibles: perfil fenotípico, evolución de scores SNC, Metabólico y Bioenergético, balance energético (ingesta media, gasto basal, gasto activo NEAT, gasto total y balance resultante), macronutrientes medios, analítica clínica con verificación sistemática de rangos de referencia, y apéndice de registros diarios brutos del período.

El módulo HistoriaPacienteService aplica el método BuildParametros() para comprobar los ~55 parámetros del modelo AnaliticaClinica contra sus rangos de referencia, marcando cada parámetro con EsAnormal = true cuando el valor cae fuera del rango. En el informe, los parámetros esenciales y los anormales se destacan visualmente (fondo cálido, nombre en ámbar, valor en rojo con indicador ⚠); el resto se omite para no sobrecargar la lectura.

El período analizado nunca incluye el día en curso (datos incompletos). El informe es imprimible directamente como PDF desde el navegador mediante Layout = null y CSS media print.

El resumen IA se genera de forma asíncrona mediante IBackgroundTaskQueue (máximo 2 500 tokens) con una plantilla versionada gestionada por HistoriaPacientePromptSeeder. La plantilla produce cinco párrafos estructurados: estado funcional, balance energético, nutrición/sueño/composición corporal, analítica clínica (siempre presente aunque todos los valores sean normales) y recomendaciones priorizadas, con cierre de valoración global. Los parámetros marcados como [FUERA DE RANGO] en el bloque de datos son señalados explícitamente por el modelo en el párrafo de analítica y en las recomendaciones.

Veredicto de rutina de fuerza — criterio autorreferencial de ventana reciente. El bloque de actividad de fuerza no evalúa el promedio de todo el período (puede diluir una rutina reciente y constante entre meses previos sin actividad), sino una ventana de los últimos 14 días con criterio OMS (≥2 sesiones/semana de ≥20 min). Esa ventana se ancla en el día de generación del informe, no en la última fecha del período histórico: si el informe se genera con fecha fin igual a ayer (el máximo permitido, ya que el día en curso nunca se incluye por tener el balance energético incompleto), se consulta además el registro de hoy exclusivamente para los minutos de gimnasio — una sesión de fuerza ya registrada es un dato completo en el momento en que se guarda, a diferencia del balance energético del día en curso. El veredicto ("YA ESTABLECIDA" / "NO establecida") se presenta como primera línea autocontenida del bloque, con las cifras de todo el período relegadas y marcadas explícitamente como contexto histórico no válido para ese juicio, de modo que el modelo use el veredicto ya calculado en lugar de recalcular por su cuenta la frecuencia semanal.

---

8.13b. Módulo de evolución longitudinal de parámetros clínico-analíticos

El sistema incorpora un módulo específico de análisis longitudinal de series temporales de analíticas clínicas, accesible desde el menú Informes / Evolución → Evolución Analítica. Su unidad de procesamiento es la colección de objetos AnaliticaClinica del usuario filtrada por un intervalo temporal configurable (presets de 6 meses, 1, 2 y 5 años, o rango de fechas libre).

Visualización por categoría clínica. El módulo genera ocho gráficas Chart.js independientes (línea continua, sin interpolación forzada, con spanGaps: true para analíticas no consecutivas), una por sistema fisiológico: perfil lipídico, metabolismo glucémico, función renal, función hepática, tiroides, inflamación (PCR/VSG), micronutrientes y hematología. Cada serie incluye los valores efectivos de cada FechaAnalisis como eje X temporal.

Matriz comparativa interactiva. Un modal a pantalla completa presenta todos los biomarcadores disponibles en una única tabla vertical continua, con las fechas de analítica como columnas y cada parámetro como fila. Las filas con ningún valor registrado en el período se omiten automáticamente. La última columna muestra el delta (Δ) entre el primer y el último valor con dato, con codificación semántica de color: verde cuando la variación es clínicamente favorable para ese parámetro (p.ej. reducción de LDL, incremento de HDL o filtrado glomerular), rojo cuando empeora, gris cuando es neutro o sin datos suficientes. La dirección favorable se parametriza individualmente por parámetro mediante el argumento positivo en la función de renderizado FilaComp().

Interpretación IA longitudinal. El módulo integra un análisis asíncrono de tendencias generado por el proveedor IA activo (Ollama Cloud o Claude API) mediante la plantilla versionada con código ANALITICA_EVOLUCION, gestionada por AnaliticaEvolucionPromptSeeder y editable desde la consola de prompts sin redesplegar. El bloque de datos inyectado como {{DataBlock}} es una tabla de texto plano estructurada por categorías, con una fila por parámetro mostrando los valores en cada fecha y el Δ calculado. El servicio AnaliticaEvolucionAiService encola la tarea en IBackgroundTaskQueue (tipo ANALITICA_EVOLUCION) y la UI hace polling cada 2 segundos al endpoint CheckEvolucionIA hasta recibir el HTML interpretativo. El modelo produce exactamente cinco secciones h6 en HTML parcial, interpretando tendencias sostenidas (≥ 2 registros consecutivos en la misma dirección), identificando el Δ de los parámetros con variación clínicamente relevante y agrupando los hallazgos por sistema. La referencia comparativa es siempre el propio paciente en el tiempo, nunca baremos poblacionales.

Informe impreso. Desde la propia vista puede generarse un informe en hoja A4 apaisada que reúne, en este orden, las ocho gráficas en formato compacto (redibujadas en cliente con Chart.js a partir de las mismas series), la matriz comparativa completa con el delta (Δ) y, únicamente si el análisis IA longitudinal ya ha sido generado en esa sesión, su resultado precedido del aviso de que no constituye diagnóstico médico ni sustituye la valoración de un profesional sanitario. El informe se compone íntegramente en el navegador y no requiere persistencia adicional.

La arquitectura reutiliza todos los componentes de infraestructura IA del sistema: el mismo IAiCompletionService con selección automática de proveedor por rol (admin / usuario), la misma cola de tareas con timing estimado (IAiTimingService) y el mismo almacén en memoria IAiResultStore con TTL de 10 minutos. La plantilla se registra en IaPromptTemplates mediante la acción de seed /Inicializer/SeedAnaliticaEvolucionPrompt.

---

8.14. Sistema híbrido de estimación nutricional (OFf + IA)

El módulo de ingesta opera en dos modos: IA pura y modo híbrido que consulta la etiqueta real de OpenFoodFacts para productos envasados de marca con fallback a IA para genéricos. Las bebidas alcohólicas se calculan siempre por IA mediante fórmula determinista. Antes de invocar cualquiera de los dos motores, cada alimento se contrasta contra una biblioteca personal por usuario (IntakeFoodLibraryItem); si hay coincidencia exacta de nombre normalizado, se reutiliza su composición ya guardada por 100 g/ml, sin llamar a ningún motor. Ver sección 11.11 para descripción completa.

---

8.15. Modelo estadístico de impacto etílico

AlcoholCalibrationService: regresión MCO con F fijo que cuantifica β_alc (retención la mañana siguiente, D+1), único coeficiente del modelo. La calidad del análisis se basa en la significancia de β_alc, no en R². Calcula contrafactual de pérdida sin alcohol y detecta anomalías de eficiencia metabólica. Ver sección 11.12.

---

8.16. Factor de corrección diferenciado macros/alcohol y alerta de recalibración

El OllamaIntakeCorrectionFactor se aplica solo sobre macros, excluye el alcohol. El CalibrationAlertService emite aviso automático cuando el balance acumulado supera el umbral individual. Ver sección 11.13.

---

8.17. Arquitectura multiusuario y generación de documentación RGPD

Aislamiento completo por UsuarioId en todas las entidades. Generación asistida por IA de consentimientos informados, políticas de privacidad y contratos profesional-paciente conformes con el RGPD europeo. Ver secciones 11.14, 11.15 y 11.16.

---

8.18. Trazabilidad de origen de HRV y comparativa multi-dispositivo (HealthKit vs Oura)

El sistema admite la importación de BiodataDiaria desde dos fuentes de wearable heterogéneas: la exportación de Apple HealthKit y la API en vivo de Oura Ring. Ambas alimentan los mismos campos del modelo, pero emplean algoritmos y ventanas temporales distintos para magnitudes nominalmente equivalentes, lo que exige una capa explícita de trazabilidad de origen antes de cualquier comparación longitudinal.

El caso más relevante es la variabilidad de la frecuencia cardiaca (HRV): HealthKit reporta heartRateVariabilitySDNN (algoritmo SDNN), mientras que Oura reporta average_hrv del periodo de sueño principal (algoritmo RMSSD). Ambos valores se expresan en milisegundos pero no son numéricamente comparables entre sí. Para resolverlo, cada registro de BiodataDiaria persiste el enumerado HrvOrigen (HrvSource: HealthKitSDNN, OuraRMSSD, Manual, Desconocido), y de forma análoga la frecuencia cardiaca media persiste FcMediaOrigen (media diaria de HealthKit vs media nocturna de Oura). El marcado de HrvOrigen se aplica de forma homogénea en las dos vías de importación de HealthKit existentes —el pipeline JSON (HealthKitJsonImportService) y el pipeline XML/agregador (HealthKitDailyAggregator + HealthKitBiodataMapper)—, de modo que ningún registro de HRV queda sin trazabilidad de origen con independencia del canal de importación utilizado.

El Panel de Recuperación (RecoveryService) explota esta trazabilidad calculando un baseline independiente por origen (RecoveryBaseline.Fuente: media, desviación típica y número de muestras sobre una ventana de 30 días) para la señal de HRV. Cada RecoveryDailyScore conserva el campo HrvFuente del día evaluado y se compara únicamente contra el baseline de su misma fuente, evitando contaminar la línea base de un dispositivo con valores de otro.

Además del origen, cada registro de BiodataDiaria persiste HrvMuestrasNocturnas: el nº de muestras crudas de HRV que cayeron dentro de la ventana de sueño de esa noche concreta y se promediaron para dar el valor final. Con el Apple Watch lo habitual son 2 muestras por noche, y el campo permite que el peso de la señal HRV en el score (43%, el más alto de las cuatro) distinga una noche con pocas muestras de una con muchas. El método RecoveryService.ResolverHrvNocturno combina cobertura, plausibilidad frente al baseline propio y vigilia nocturna absoluta, de forma asimétrica: con cobertura suficiente (≥3 muestras) el valor se acepta siempre, sea cual sea su magnitud; con pocas muestras, solo hay ambigüedad real cuando el valor es anormalmente bajo (por debajo de -1,5σ del baseline propio) — un valor anormalmente alto con pocas muestras se acepta siempre, porque los artefactos de medición típicos de HRV (mal contacto, movimiento durante el sueño) tienden a deprimir el valor, no a inflarlo.

Independientemente de si el valor se acepta o se sustituye, su peso en la media ponderada del score también depende de HrvMuestrasNocturnas, vía RecoveryService.FactorConfianzaHrv: el 43% base se escala por min(muestras / 2, 1) — con 2 o más muestras (el caso normal) pesa el 43% completo; con 1 sola muestra, el 21,5%; con 0 (valor sustituido en el import por el geométrico del baseline, ver 8.16), no aporta nada al score ese día. El peso sobrante se redistribuye automáticamente hacia FC Reposo/Temperatura/Sueño al renormalizar por pesoTotal. El umbral de plena confianza se fija en 2, no en el umbral de aceptación sin comprobación (3, ver arriba), precisamente porque 2 es la cobertura normal de este dispositivo — penalizar el caso típico habría bajado el peso de HRV casi todos los días.

El score del día en curso puede pasar de no incluir FC Reposo/HRV a incluirlos horas después, sin que el usuario haga nada — no porque el dato nocturno en sí cambie (ya está cerrado en cuanto termina el sueño), sino porque el import exige tener en el mismo envío tanto el día de inicio como el de fin de la ventana de sueño (ver 8.16); si una sincronización de Health Auto Export llega incompleta, el cálculo se omite ese ciclo en vez de promediar con datos a medias, y se completa en cuanto llega un envío con ambos días. El icono ⓘ junto al score de hoy lo explica en esos términos — dato ausente pasando a presente, no un valor que fluctúa.

Cuando un día tiene sueño registrado pero ninguna lectura de HRV cayó dentro del episodio (p. ej. porque el reloj cortó el episodio de sueño antes de que el usuario se despertara), la ficha de Biodata y el detalle de Recovery muestran un aviso de "probable corte anticipado del sueño" que recomienda subir el export reducido (Adquisición de datos → Apple / Android ZIP) para recalcular el HRV con la noche completa. El aviso no aparece mientras no haya sueño registrado (sincronización aún pendiente) y en Recovery se actualiza al seleccionar cada día.

FC Reposo está protegida frente a automatizaciones parciales del mismo día: cada import se queda con el mínimo entre el valor guardado y el nuevo, así que solo puede mejorar o quedar igual en el día. HRV, al ser un promedio (no un mínimo), usa una protección equivalente (HealthKitJsonPersistenceService y HealthImportPreviewPersistenceService, pipelines JSON y ZIP) es exigir que la nueva importación use un número de muestras nocturnas igual o mayor que el ya persistido antes de sobrescribir HrvMs, de modo que una automatización con menos contexto (el reloj aún no ha terminado de sincronizar) no pisa un cálculo hecho con más muestras ni altera, sin motivo fisiológico, el score de Recovery, que pondera el HRV al 43%.

Cuando un valor con pocas muestras sí resulta anómalamente bajo, el sistema no lo descarta: comprueba si esa noche hubo vigilia nocturna prolongada (SueñoDespertarMinutos ≥ 30 min absolutos). Si la hubo, el valor se sustituye por la mediana del baseline personal (RecoveryDailyScore.HrvSustituido = true, HrvValorSustituido = mediana usada) — la vigilia ofrece una explicación plausible de un valor degradado por el propio despertar, cuando la lectura cae en un tramo de vigilia. El valor crudo de BiodataDiaria.HrvMs nunca se toca — la sustitución es exclusiva de este cálculo del Panel de Recuperación; cualquier otro módulo (Biodatos diarios, Evolución temporal, exports) sigue viendo el dato tal como lo mandó el wearable. Si no hubo vigilia que lo explique, el valor se mantiene tal cual, sin sustituir ni descartar: un HRV bajo sin vigilia que lo justifique no es ruido de medición, es precisamente el caso fisiológicamente más relevante (estrés, sobreentrenamiento, enfermedad incipiente...) y debe seguir contando en el score con su propio peso. La vigilia nunca actúa, por tanto, como criterio aislado — solo como explicación de una anomalía que ya existe por sí misma en el valor: la vigilia agregada de toda la noche no indica si la muestra concreta de HRV cayó en vigilia, y sin esa anomalía previa no se sustituye ni se avisa de nada, por mucha vigilia que haya habido. En la vista, la sustitución se marca con un asterisco junto al Z-HRV (tarjeta de hoy, historial y detalle) que abre un modal con la fecha, el valor medido, los minutos de vigilia y la mediana usada.

Ese modal incluye una comprobación contra el export.xml de Apple Health subido al servidor. Al pulsarla, el fichero se lee completo en ese momento (sin importarlo antes), se localiza la ventana de sueño de esa noche con el mismo agrupado de episodios que la importación y se determina, muestra a muestra, cuántas lecturas de HRV se tomaron dentro de un tramo de vigilia (HKCategoryValueSleepAnalysisAwake). El modal muestra cada lectura con su hora, su valor y si se tomó despierto o dormido. El veredicto se guarda en HrvVerificacionNocturna (usuario, fecha, lecturas totales, lecturas en vigilia, HRV recalculado, lecturas usadas y fecha del export leído) y RecoveryService lo aplica al recalcular el score. Si ninguna lectura cayó en vigilia, el valor medido se usa tal cual y desaparece la sustitución. Si al menos una cayó, esas lecturas se descartan y el HRV de la noche pasa a ser la media de las restantes, tras aplicar el mismo filtro de valores fisiológicamente implausibles frente al baseline propio que usa la importación (HrvOutlierFilter); esta corrección no exige que el valor original fuera anómalo. El peso del HRV en el score se escala con el número de lecturas realmente usadas, y solo si no queda ninguna lectura válida se recurre a la mediana del baseline personal. BiodataDiaria.HrvMs no se modifica en ningún caso. La comprobación solo está disponible sobre los datos propios del usuario, no en el contexto de un paciente.

El valor de HRV varía según la fase de sueño activa en el instante de cada lectura (más alto en REM que en sueño ligero, profundo o vigilia), de modo que con 1-2 muestras por noche el resultado depende de qué fase concreta capturó el reloj. El sistema no filtra el HRV por fase porque el JSON de Health Auto Export solo aporta totales agregados de la noche (core/deep/rem/awake en horas), no la fase activa en cada instante; solo el XML/ZIP completo tiene ese detalle.

Como apoyo a la interpretación clínica y técnica de estas disparidades, se incorpora una página de comparativa multi-dispositivo (HealthKit vs Oura) que documenta, métrica a métrica de BiodataDiaria, el origen del dato en cada plataforma, su grado de equivalencia (equivalente directo, aproximación razonable, disparidad que requiere etiquetado o corrección, o campo exclusivo de una fuente) y el estado de la corrección aplicada. La página incluye además una nota operativa sobre la configuración de permisos de Oura en HealthKit/Health Connect, necesaria para evitar que ambas fuentes se mezclen antes de llegar al sistema y se pierda así la separación de orígenes.

Complementariamente, el módulo Evolución temporal (HealthTimeSeriesController, IOuraTimeSeriesService) permite visualizar series de mediciones individuales sin agregación diaria: desde export.xml para los parámetros de HealthKit, o en vivo desde la API de Oura (/v2/usercollection/heartrate para frecuencia cardiaca intradía y el subobjeto hrv de /v2/usercollection/sleep para HRV nocturno por RMSSD). Para SpO₂ y HRV de HealthKit, el sistema calcula además una línea base personal de 3 meses y compara la media del periodo seleccionado frente a dicha línea base.

---

8.19. Importación Android — Google Health Connect: Takeout (legacy) y Webhook

El sistema ofrece dos vías de adquisición para dispositivos Android: una importación manual por ZIP (Google Takeout), documentada a continuación como vía heredada, y un endpoint REST desatendido equivalente al de iOS (sección 8.21), que es la vía recomendada.

8.19.1. Vía heredada — ZIP de Google Takeout (importación manual)

La arquitectura reutiliza íntegramente la mecánica de subida chunked de iOS (StartZipUpload → UploadZipChunk) y añade dos acciones propias: CompleteAndroidZipUpload (previsualización, sin escritura en BD) y ConfirmAndroidImport (upsert definitivo).

El servicio GoogleHealthConnectImportService detecta automáticamente dos layouts dentro del mismo ZIP: CSVs de Daily activity metrics (Google Fit, un fichero por día con cabeceras nominales como Step count, Average heart rate (bpm), Distance (m)…) y CSVs por tipo de métrica en subcarpetas Health Connect (detectadas por nombre de fichero: HeartRateVariabilitySdnn, RestingHeartRate, SleepSession, OxygenSaturation, RespiratoryRate, BodyTemperature, Weight, Steps). Ambos formatos pueden coexistir en el mismo ZIP; el acumulador por fecha (BiodataRow) aplica ??= para que el primer valor encontrado por campo tenga prioridad y los formatos se complementen sin sobreescribirse.

El flujo de confirmación en dos pasos garantiza que el usuario revise los datos antes de modificar BiodataDiaria: la previsualización muestra una tabla con filas coloreadas (verde = registro nuevo, amarillo = actualiza existente) marcadas consultando las fechas ya presentes en BD para ese UsuarioId. El ZIP ensamblado se mantiene en disco hasta la confirmación y se elimina inmediatamente después. Un usuario puede combinar importaciones iOS y Android sobre el mismo período sin conflicto, ya que el upsert por (UsuarioId, Fecha) es idempotente.

La integración en la vista (Adquisición de datos → Apple / Android (ZIP)) se articula mediante un selector de plataforma Bootstrap Pills con paneles tab-pane independientes, compartiendo CSS y estructura de card pero con JS y endpoints separados por plataforma. Esta vía se mantiene operativa para importaciones puntuales, pero la pestaña Android la marca como obsoleta en la interfaz: el HRV que produce es un valor ya pre-agregado por fila del export (average(milliseconds), primer valor del día), sin el filtrado por ventana de sueño real descrito en 8.19.2 y en 8.21.

8.19.2. Vía recomendada — Webhook "HC Webhook"

Igual que en iOS, se incorpora un endpoint desatendido (GoogleHealthConnectWebhookApiController, POST /api/healthconnectwebhook/{token}) que recibe el payload directamente desde una app de terceros instalada en el dispositivo Android, sin sesión interactiva. La app compatible es "Health Connect Webhook" (proyecto "HC Webhook", código abierto, github.com/mcnaveen/health-connect-webhook), que lee Health Connect a través de su API nativa y publica un objeto JSON plano con un array por tipo de dato. El endpoint reutiliza el mismo PerfilPersonal.HealthAutoExportToken (guardado como hash) que iOS —el token identifica al usuario, no la plataforma de origen, por lo que no hace falta un campo ni una pantalla de generación distintos.

El servicio GoogleHealthConnectWebhookImportService parsea el payload y produce el mismo DTO por día (HealthKitJsonDayResult) que el pipeline de iOS, reutilizando sin cambios HealthKitJsonPersistenceService para la persistencia. A diferencia del XML de Apple, cada sesión de sueño llega ya resuelta con su desglose de fases (stages[] con inicio/fin por fase), por lo que no hace falta reconstruir episodios agrupando por hueco. Cada sesión se atribuye al día en que termina; si varias terminan el mismo día (p. ej. noche y siesta), se toma como episodio principal la de más minutos de sueño real (ligero + profundo + REM), mismo criterio que el pipeline ZIP de Apple. El HRV (heart_rate_variability: rmssd_millis + time) se recoge como muestras crudas por instante y se resuelve, exactamente igual que en 8.21, filtrando por la ventana de sueño real de esa noche concreta (comprobando también el cubo del día anterior, por si la ventana empieza la noche previa) en vez de promediar todo el día. El origen se marca como HrvSource.HealthConnectRMSSD —mismo algoritmo RMSSD que Oura, pero dispositivo/app distintos, por lo que no se reutiliza OuraRMSSD— y hereda el mismo criterio de trazabilidad descrito en 8.18.

---

8.20. Módulo de adaptación metabólica

El sistema incorpora un módulo específico de detección y cuantificación de adaptación metabólica (adaptive thermogenesis), accesible desde el menú Energía → Metabolismo → Adaptación metabólica. Su función es medir el gap entre el TDEE teórico por el modelo energético propio del sistema y el TDEE real estimado mediante el principio de conservación de energía aplicado sobre la serie histórica de ingesta corregida y variación de masa corporal.

La variación de masa se extrae mediante regresión OLS sobre la serie de peso del período (umbral R² 0,25 para dar prioridad a la estimación de tendencia sobre el endpoint), reduciendo el sesgo asociado a fluctuaciones de retención hídrica y glucógeno. El módulo clasifica la adaptación en cuatro niveles (Sin / Leve / Moderada / Severa), emite alertas de reactivación metabólica y proteína, y permite almacenar snapshots para seguimiento longitudinal.

La vista del módulo ofrece una serie histórica de 12 ventanas de 28 días con gráficas Chart.js y un modal de información exhaustivo que documenta causas hormonales (leptina, T3, cortisol), mecanismos de conservación (NEAT, eficiencia muscular), evidencia científica de reactivación metabólica (estudio MATADOR, Byrne 2017) y limitaciones de la estimación.

Indicadores complementarios sobre la misma ventana: TEF individualizado por macronutriente, Ratio TDEE real/teórico ("Índice de Rendimiento Metabólico"), ΔAdaptación a 30 días (velocidad de cambio contra el histórico) y variabilidad de peso residual — ninguno recalcula ni sustituye el TDEE_real ya descrito, son lecturas adicionales sobre los mismos datos. El Índice de Eficiencia Locomotora (señal diagnóstica, nunca calibradora — ver 8.22) se muestra ya integrado dentro de esta misma pantalla. Las etiquetas de nivel mostradas en pantalla ("Muy adaptable"/"Sin adaptación" para SinAdaptacion según el residual sea inferior o no al −5 % del TDEE teórico, "Leve", "Moderada", "Severa") están unificadas entre AdaptacionMetabolica e HistoricoAdaptacion en NivelAdaptacionDisplay, de modo que ambas vistas usan la misma redacción. La interpretación completa de cada nivel vive en el tooltip del badge, no en el texto visible.

R² del peso: la pendiente de ΔPeso se calcula por Theil-Sen (mediana de pendientes por pares, robusta a valores atípicos). Como Theil-Sen no minimiza la suma de residuos al cuadrado, el R² no se calcula sobre esa recta sino sobre una recta OLS independiente ajustada a los mismos puntos, que por construcción nunca ajusta peor que la media y cae siempre en [0,1]. Ese R² es el que decide, con el umbral de 0,25, si ΔPeso usa la regresión o el endpoint.

Cobertura de pesaje real y estado "No concluyente": para distinguir una ventana con adherencia normal a la báscula de una reconstruida en su mayor parte a partir de valores heredados, MetabolicAdaptationService calcula por ventana el % de días con PesoMedidoEnUtc real (no heredado); por debajo del 50%, el badge Leve/Moderada/Severa se sustituye por completo por "No concluyente" —no se atenúa ni se muestra junto a un aviso, se omite la gradación entera— tanto en AdaptacionMetabolica.cshtml como en HistoricoAdaptacion.cshtml, y la recomendación de reactivación metabólica (RecomendacionRefeed) no se dispara en esas ventanas. El prompt HISTORICO_ADAPTACION recibe la misma señal por fila y tiene prohibido interpretar Nivel/TDEE Real/ΔPeso como hallazgo en las filas marcadas, con la misma prioridad que la regla de "Aviso peso desactualizado".

Ventanas de ~90 días en la interpretación por IA: el prompt HISTORICO_ADAPTACION recibe, junto a la tabla de snapshots (ventanas de ~28-30 días), una segunda tabla con una serie semanal de ventanas de 90 días. Esta serie se calcula al vuelo en EnergyManagerController.HistoricoAdaptacion mediante MetabolicAdaptationService.BuildAsync con ventana de 90 días —reutilizando la serie transitoria que ya calcula ese método, sin escribir en MetabolicAdaptationSnapshots— y solo incluye las ventanas con al menos 75 días con datos. El prompt instruye apoyar la conclusión sobre presencia o ausencia de adaptación en esas ventanas (donde el ruido diario del peso tiene menos peso relativo que en las de ~30 días), formularla como "sin adaptación metabólica medible en el periodo" cuando el residual se mantiene por debajo del umbral de Leve, no contar como mediciones independientes las filas solapadas, y abstenerse de concluir cuando no existe ninguna ventana de 90 días válida. La etiqueta "Muy adaptable" se define en el prompt como residual inferior al −5 % (gasto superior al teórico fuera del margen de ruido), no como adaptación intensa.

---

8.21. Importación JSON de HealthKit: automatización REST desatendida

Junto al pipeline XML descrito en 8.4, el sistema incorpora un segundo canal de adquisición de BiodataDiaria desde Apple HealthKit basado en el esquema JSON de la aplicación de terceros Health Auto Export (HealthKitJsonImportService), que llega mediante un endpoint REST desatendido (HealthAutoExportApiController, POST /api/healthautoexport/{token}) que recibe el payload directamente desde una automatización configurada en el dispositivo del usuario, sin intervención humana ni sesión interactiva.

La autenticación del endpoint desatendido se resuelve mediante un token opaco de 256 bits generado y regenerado por el propio usuario desde su ficha de perfil; en PerfilPersonal.HealthAutoExportToken solo se persiste su hash SHA-256 (el valor en claro se muestra una única vez al generarlo). El endpoint está marcado [AllowAnonymous] a nivel de autenticación de sesión, pero exige el token en la cabecera Authorization: Bearer (o X-Import-Token) para resolver el usuario destino y rechaza con 401 cualquier token no reconocido; la forma antigua con el token en la ruta se mantiene mientras se reconfiguran los dispositivos y puede desactivarse con Importacion:PermitirTokenEnUrl.

El motor de parseo reproduce, para el esquema JSON, los mismos modos de agregación por campo ya validados en el pipeline XML (Suma, Promedio y Último valor, según el tipo de magnitud), mediante un acumulador (Fecha, Campo) → (Suma, Contador) resuelto al cierre de cada lote — necesario porque, a diferencia de la exportación manual (una entrada por día y métrica), la automatización REST puede remitir múltiples muestras intradía para el mismo día.

Para las magnitudes acumulativas en las que Apple Watch e iPhone pueden registrar simultáneamente el mismo evento físico (pasos, distancia recorrida, pisos subidos, energía activa y energía basal), el sistema aplica un criterio de preferencia de fuente por día: si existe alguna muestra cuyo campo source referencia el reloj, se descartan las muestras del resto de fuentes para ese día y métrica antes de sumar, replicando el criterio SourcePreference.PreferWatchFallbackSalud ya empleado por el pipeline XML; en ausencia de muestra del reloj se utiliza la fuente disponible. Esta deduplicación evita que la coincidencia temporal de dos dispositivos contabilizando la misma actividad infle el agregado diario.

Dado que las dos vías de entrada del esquema JSON exponen sus métricas y entrenamientos de forma potencialmente fragmentada en llamadas independientes —la aplicación de automatización no admite combinar métricas y entrenamientos en un único disparo—, la separación de MinutosEjercicioExterior (calculado como minutos totales de ejercicio Apple menos minutos de gimnasio) se resuelve mediante reconstrucción del valor bruto a partir de los campos ya persistidos en BiodataDiaria (BrutoPrevio = ExteriorGuardado + GimnasioGuardado) en cada llamada parcial, garantizando un resultado convergente con independencia del orden de llegada de ambas automatizaciones.

FC reposo (FrecuenciaCardiacaReposo): mínimo absoluto de pulso durante la ventana de sueño real, no el campo RestingHeartRate de Apple. Ese campo de Apple no es el mínimo del día ni está atado al sueño — es una estimación propia calculada a partir de muestras de FC tomadas durante periodos de inactividad a lo largo de todo el día, que se va refinando según se acumulan más muestras de reposo, de modo que dos consultas al mismo día en horas distintas pueden devolver valores distintos. En su lugar, el sistema recoge las muestras crudas de heart_rate.Min (el submínimo de cada intervalo que ya reporta Health Auto Export) y se queda con el mínimo de las que caen dentro de la misma ventana de sueño real ya usada para el HRV nocturno — mismo criterio de ventana completa (si falta el día anterior en el payload, no se resuelve ese día) y mismo criterio de sobrescritura, incluido a null. El mismo cálculo se aplica en el pipeline XML (8.4) y en el JSON de este apartado; el canal de Google Health Connect (Android) conserva el valor que entrega la plataforma.

Toda escritura sobre BiodataDiaria, con independencia de su canal de origen —edición manual, importación XML, automatización REST, Google Health Connect u Oura—, queda marcada con FechaUltimaActualizacion y un código corto de procedencia (OrigenUltimaActualizacion: Manual, HealthKit, GoogleKit, ManualJson, AutoJson, ImportOura), visible en la vista de listado de BiodataDiaria y en el panel de adherencia de la página de inicio, lo que permite al usuario verificar de forma directa si la automatización desatendida está ejecutándose con la periodicidad esperada sin depender de inspección técnica.

Protección de la cintura medida a mano frente al arrastre automático: como la cintura no la reporta HealthKit, ambos pipelines de importación (el REST desatendido de este apartado y el XML manual de 8.4) la rellenan por fallback con el último valor real conocido (hasta 30 días) cuando el día no trae dato — mismo mecanismo que el peso heredado descrito más arriba. Como Health Auto Export reenvía la semana completa en cada disparo, dos disparos solapados pueden procesar el mismo día en momentos distintos; para que el arrastre nunca sobrescriba una medición manual, el campo CinturaMedidaEnUtc —mismo patrón que PesoMedidoEnUtc— se rellena únicamente cuando el valor viene de una medición real introducida en Biodata; mientras esté informado, ningún pipeline de importación vuelve a evaluar el fallback de cintura para ese día, sea cual sea el orden de llegada de las automatizaciones.

Aviso de horario de sueño faltante: algunas noches Health Auto Export manda la duración del sueño (fases core/deep/rem) sin las marcas sleepStart/sleepEnd de esa entrada sleep_analysis. Cuando ocurre, BiodataDiaria.HorarioSuenoFaltante y SleepNoche.HorarioFaltante lo reflejan como un aviso visible en la ficha de Registros Diarios y en la pestaña Noche a noche de Sueño, sin ocultar la duración ya conocida. ISleepScheduleAnomalyLogService guarda además el JSON crudo de esa entrada en AppData/SleepScheduleAnomalyLogs (un fichero por día, panel de administración en Admin → Supervisión → Anomalías de sueño), para diagnosticar con el payload real en vez de suponer la causa. Subir el export ZIP de esa semana (8.4) suele rellenar el horario, porque ese pipeline reconstruye la ventana de sueño desde los registros crudos en vez de depender de ese par de campos agregados.

El funcionamiento operativo del sistema se articula mediante una secuencia ordenada de fases funcionales, cada una de las cuales produce un resultado estructurado que sirve de entrada a la fase siguiente.

---

FASE 0 — Importación estructurada de datos externos

Recepción, validación estructural y persistencia interna del archivo XML o contenedor comprimido.

---

FASE 0 BIS — Reducción documental y segmentación semanal

Generación de subconjuntos documentales por semana natural mediante lectura secuencial en streaming.

---

FASE 1 — Agregación estructural diaria

Reconstrucción diaria de registros, intervalos, entrenamientos, actividad y demás nodos relevantes.

---

FASE 2 — Normalización y generación de BiodataDiaria

Transformación de agregados diarios en registros normalizados compatibles con BiodataDiaria.

---

FASE 2 BIS — Cálculo energético diario

A partir de BiodataDiaria, el sistema calcula y persiste el balance energético diario mediante EnergyDailyBalance, integrando ingesta, gasto basal ajustado, gasto activo ajustado, gasto total, macronutrientes, alcohol, proteína/kg y estado energético oficial.

Este cálculo constituye la base del análisis metabólico diario y de la dinámica energética funcional.

---

FASE 3 — Construcción de la Colección de Datos Funcionales

Formación del HealthDashDataBundle con perfil, biometría diaria reciente y analítica válida.

---

FASE 4 — Ejecución del motor de cálculo

Ejecución del motor hardcoded, declarativo o comparativo sobre la Colección de Datos Funcionales.

---

FASE 5 — Persistencia del resultado

Registro del resultado junto con su contexto operativo, temporal, técnico y funcional.

La originalidad técnica del sistema WHeat-Jobs | Fenotipo no deriva de la utilización aislada de variables biomédicas conocidas, sino de la estructura funcional que permite integrarlas dentro de un flujo coherente, reproducible y trazable.

---

11.1. Modelo de Colección de Datos Funcionales

El HealthDashDataBundle consolida variables relevantes para el cálculo en una estructura funcional única.

---

11.2. Arquitectura dual de cálculo

La coexistencia de motor hardcoded y declarativo permite validación cruzada y evolución controlada.

---

11.3. Persistencia contextual del cálculo

Cada cálculo se almacena junto con los parámetros, contexto temporal, analítica y motor que lo originaron.

---

11.4. Pipeline estructurado de importación biométrica

El sistema transforma exportaciones externas en estructuras internas normalizadas mediante lectura secuencial y agregación diaria.

---

11.5. Integración de lógica heurística funcional

El sistema combina referencias biomédicas con reglas heurísticas para representar estados fisiológicos comparables.

---

11.6. Evolución estructural controlada

La modularidad permite introducir modificaciones progresivas sin alterar resultados históricos.

---

11.7. Lectura analítica dual: score compuesto y tendencia biométrica directa

El sistema combina scores compuestos de dominio con análisis longitudinal directo de variables diarias persistidas.

---

11.8. Modelo diario de balance energético y disponibilidad funcional

El sistema introduce un modelo diario específico de balance energético, basado en la integración de energía ingerida, gasto basal ajustado, gasto activo ajustado, gasto total, macronutrientes, alcohol y proteína relativa al peso corporal.

Este modelo permite distinguir entre el mero saldo calórico y la calidad funcional del día, incorporando la suficiencia proteica y la composición nutricional como elementos relevantes para la interpretación de la presión metabólica.

La existencia de una vista dinámica complementaria, basada en curva diaria por fases e índice relativo de disponibilidad energética, aporta una lectura visual y sintética del estado energético funcional, sin convertir dicho índice en magnitud clínica directa.

---

11.9. Importación automática de analítica clínica desde PDF con IA nativa

El sistema incorpora un mecanismo de ingestión de informes de laboratorio en formato PDF que prescinde de OCR previo. El PDF se transmite directamente como documento base64 al modelo de lenguaje, que comprende la estructura del informe y extrae hasta 60 biomarcadores mapeados al modelo de dominio AnaliticaClinica.

El diseño incorpora reglas de conversión explícitas para los casos en que distintos laboratorios emplean unidades diferentes (notación científica hematológica, PCR en mg/dL, urea/calcio/fósforo en mmol/L, T4 Libre en pmol/L), evitando errores de orden de magnitud independientemente del laboratorio emisor.

La pantalla de revisión con semáforo de rangos de referencia constituye una capa de validación interactiva que permite detectar visualmente cualquier discrepancia antes de la persistencia definitiva.

---

11.10. Informe de revisión histórica parcial con análisis IA integrado

El sistema incorpora un módulo de revisión longitudinal propio (HistoriaPacienteService) que compila, para cualquier período seleccionado por el usuario, un informe multidimensional que integra perfil fenotípico, evolución de los tres scores funcionales, balance energético período, macronutrientes medios, verificación sistemática de ~55 parámetros analíticos contra rangos de referencia clínicos y apéndice de registros diarios brutos.

El mecanismo de verificación analítica (BuildParametros) marca individualmente cada parámetro como esencial o anormal, con resaltado visual diferenciado en el informe imprimible. El resumen IA de cinco párrafos estructurados se genera de forma asíncrona mediante plantilla versionada en base de datos (HistoriaPacientePromptSeeder), garantizando que la analítica clínica figure siempre en el análisis independientemente de si los valores son normales, y que los parámetros fuera de rango sean explícitamente contextualizados en las recomendaciones.

---

11.11. Sistema híbrido de estimación nutricional (OFf + IA)

Antes de decidir entre IA u OpenFoodFacts, cada alimento del menú del día se contrasta contra la biblioteca de alimentos del usuario (IntakeFoodLibraryItem): nombre normalizado, composición por 100 g/ml (proteínas, hidratos, grasas, alcohol, sodio), origen (IA / Manual / OpenFoodFacts) y estado Fijado. El match es exacto tras normalización básica (minúsculas, sin tildes, espacios colapsados) — deliberadamente sin coincidencia difusa, para no fusionar alimentos distintos con nombre parecido. Los alimentos resueltos por biblioteca se excluyen del prompt enviado al motor elegido; si todos los alimentos del día están resueltos (por biblioteca o por macros manuales), no se invoca ningún motor. Cada alimento se da de alta en la biblioteca desde un botón junto al resultado ya calculado; un alimento Fijado queda exento de cualquier sobrescritura salvo edición manual explícita desde la pantalla de gestión (/Intake/FoodLibrary). El alta manual y la actualización comparten una única operación (upsert por nombre normalizado): si el nombre no existe se crea con origen Manual y, si existe, se sobrescriben sus valores por 100 g/ml; el candado de cada fila del listado usa esa misma operación y además establece el estado Fijado (fija o desfija) en la misma pulsación. Los alimentos que el motor OFf no encuentra se notifican al usuario con su nombre, y desde ese aviso pueden darse de alta con la composición introducida a mano, tras lo cual se recalcula el menú (ya resuelto por biblioteca); el resto de alimentos del menú se calcula y guarda con normalidad. Este mecanismo ataca directamente la volubilidad inherente a la reestimación repetida del mismo alimento por parte de la IA, sin afectar al histórico ya persistido en BiodataDiaria.

El módulo de ingesta alimentaria incorpora además un modo de operación híbrido que combina datos reales de etiqueta de la API pública OpenFoodFacts (OFf) con estimación por IA como fallback, para los alimentos que no se resuelven por biblioteca. El usuario puede alternar entre ambos modos mediante un switch en la vista de intake, con persistencia del estado en localStorage.

En modo OFf+IA, el servicio NutritionOpenFoodFactsService busca cada alimento en world.openfoodfacts.org con throttling de 2 peticiones concurrentes (SemaphoreSlim) para evitar rate limiting. La selección del candidato más relevante entre hasta 5 resultados se realiza mediante puntuación de coincidencia de palabras (sin llamada adicional a IA). Los alimentos no encontrados y las bebidas alcohólicas van siempre al servicio IA (INutritionAiService), que calcula el alcohol por fórmula determinista: ml × graduación × 0,789 × 7 kcal/g.

El JSON nutricional resultante mantiene la misma estructura que el producido por el modo IA puro (AlimentoDiaItem: name, grams, kcal, hidratos, proteinas, grasas, alcohol, sodioMg), siendo transparente para el resto del sistema.

---

11.12. Modelo estadístico de impacto etílico (AlcoholCalibrationService)

El sistema incorpora un modelo propio de regresión por mínimos cuadrados ordinarios (MCO) destinado a cuantificar el efecto del alcohol sobre la variación de peso, separado del factor puro de ingesta calórica.

El modelo opera sobre el residuo diario y_t* = ΔPeso_t + Gasto_{t-1}/7700 − F × KcalSinAlcohol_{t-1}/7700, donde F es el factor de ingesta fijado desde UserEnergyCalibration para evitar multicolinealidad. Estima un único coeficiente:

• β_alc (mañana siguiente, D+1): kg de variación de peso por gramo de alcohol consumido el día anterior.

Dado que R² ronda 0,05–0,10 en la mayoría de usuarios (esperable con un único predictor sobre peso diario, inherentemente ruidoso), el servicio calcula además el error estándar y el p-valor bilateral (aproximación normal) de β_alc a partir de la matriz (X^TX)^-1 invertida por Gauss-Jordan. La calidad del análisis (badge Excelente/Buena/Aceptable/Insuficiente) se basa en esa significancia, no en el R² — gatear por R² penalizaría una señal real por el simple hecho de venir sola. El panel marca en amarillo el coeficiente cuando p ≥ 0,05, para que no se interprete como cifra operativa.

Por separado —y sin relación con la regresión anterior— se calcula el equivalente calórico teórico del alcohol consumido (ΣAlcoholG × 7 kcal/g ÷ 7700), bajo la hipótesis física de sustitución 1:1 de oxidación de grasa por etanol (Suter, Schutz & Jéquier, 1992). Este valor NO se deriva de β_alc: es una constante física aplicada directamente sobre los gramos de alcohol del período. Se usa para mostrar el contrafactual "pérdida sin alcohol" en la UI.

Para contrastar esa hipótesis sin caer en tautología, el módulo construye también una predicción de balance energético independiente: día a día, sobre el mismo conjunto de transiciones que alimenta la regresión, se predice ΔPeso únicamente a partir de ingesta calibrada (F), gasto energético y alcohol a 7 kcal/g — sin usar en ningún momento el ΔPeso realmente observado. La diferencia entre esa predicción acumulada y el ΔPeso observado en los mismos días (ErrorResidual en el DTO) es, por tanto, una comparación genuina: puede ser distinta de cero si la hipótesis de equivalencia calórica no encaja con los datos. En períodos largos (>6 meses), las desviaciones persistentes de este error son la métrica de seguimiento de un posible compromiso de la eficiencia metabólica hepática; el sistema no emite todavía una alerta automática sobre ella.

El resultado (CalibracionAlcoholResult) es un DTO calculado en memoria, no persistido. La calidad del modelo se clasifica en cuatro niveles (Excelente/Buena/Aceptable/Insuficiente) según el p-valor de β_alc y el número de días con consumo etílico, no según R².

---

11.13. Calibración diferenciada macros/alcohol y alerta de recalibración

El factor de corrección de ingesta OllamaIntakeCorrectionFactor se aplica exclusivamente sobre el componente de macros (HC×4 + Prot×4 + Grasa×9), excluyendo el alcohol. Las calorías del alcohol se calculan mediante la fórmula determinista (g × 7 kcal) sin aplicar ningún factor corrector, por ser un cálculo exacto sin sesgo de estimación de IA.

Esta separación se implementa en EnergyDailyBalanceService y en CalibrationAlertService, garantizando coherencia en todos los módulos del sistema.

El servicio CalibrationAlertService evalúa en cada primera aplicación de ingesta del día si el balance energético acumulado de los últimos 28 días implica una variación de peso cuya magnitud supera el umbral personalizado del usuario: threshold = clamp(pesoActual × 0,005 ; 0,200 kg ; 0,800 kg). Si se supera el umbral y han transcurrido ≥ 28 días desde la última calibración guardada, el sistema genera un aviso visible en la vista de intake. El umbral y el período mínimo son configurables en la sección CalibrationAlert del appsettings.json.

---

11.14. Arquitectura multiusuario: roles, contexto de sesión y mensajería asíncrona

El sistema gestiona tres perfiles mediante ASP.NET Core Identity: Profesional (crea pacientes, gestiona su propio expediente y el de sus pacientes), Paciente (creado por el profesional con credenciales propias, datos aislados) y Usuario autónomo (acceso directo sin vinculación profesional). La relación profesional-paciente se persiste en ProfesionalPacienteRelacion con desvinculación no destructiva.

El acceso del profesional a datos del paciente se articula mediante un patrón de contexto de sesión: IContextoUsuarioService.SetPacienteActivo() activa el contexto de un paciente en la sesión HTTP, y BaseContextoController.ResolveUserId() devuelve el UsuarioId del paciente activo —previa validación de EsPacienteDelProfesionalAsync()— o el del propio profesional si no hay contexto activo. Esto permite al profesional navegar la plataforma completa en nombre del paciente sin modificar ningún controlador.

El módulo de mensajería asíncrona (MensajeProfesionalPaciente, MensajesController) permite al profesional enviar Indicaciones (unidireccionales) y SolicitudesPermiso (el paciente puede Aceptar con o sin Rechazar con motivo registrado). Ciclo de estado auditable: Enviado → Leído → Aceptado/Rechazado. El proveedor de IA puede diferir por usuario (Admin = Claude API, resto = Ollama), resuelto dinámicamente en la fábrica de IAiCompletionService.

---

11.15. Generación asistida por IA de documentos RGPD y contratos

El sistema incorpora un subsistema de generación automática de documentación legal orientada a la relación profesional-paciente: consentimientos informados, políticas de privacidad y contratos de servicio, adaptados al perfil del profesional y conformes con el Reglamento General de Protección de Datos (RGPD) y la normativa española.

Los servicios RgpdDocBuilderService, RgpdDocumentService, RgpdExportService y RgpdDocSeeder articulan la construcción, persistencia y exportación de los documentos. Las plantillas son versionadas y configurables mediante el mismo sistema de prompts declarativos que el resto de módulos IA.

---

11.16. Derecho al olvido (Art. 17 RGPD): flujo de baja y copias de seguridad independientes

El BajaUsuarioOrchestrator implementa el flujo de baja de cuenta como una máquina de estados (SolicitudBajaUsuario: Solicitada → Verificada → [ProfesionalNotificado] → BackupPendiente → BackupGenerado → Ejecutada → Completada, o Cancelada). Si el paciente tiene un profesional vinculado activo, este es notificado por email y se abre un periodo de gracia de 7 días naturales antes de poder generar el backup y ejecutar el borrado. Las cuentas con rol Administrador no pueden solicitar ni ejecutar su propia baja (comprobación explícita de rol en SolicitarBajaAsync y EjecutarBorradoAsync).

El borrado nunca se ejecuta sin backup previo: GenerarBackupAsync construye, vía IUserBackupService.GenerateBackupZipAsync, un ZIP autocontenido con todos los datos del usuario en JSON y un visor HTML standalone (BackupViewerHtmlBuilder), cifrado con AES-256 con una contraseña de al menos 12 caracteres que elige el administrador al generarlo (no se guarda); lleva además un LEEME.txt sin cifrar con las instrucciones para abrirlo. El administrador debe confirmar la custodia del backup (ConfirmarCustodiaBackupAsync) antes de que EjecutarBorradoAsync quede habilitado, y UserDeleteService ejecuta entonces el borrado en cascada de todos los datos del usuario (perfil, BioData, analíticas, energía, mensajería, documentos RGPD...).

Copia de seguridad independiente del borrado: dado que IUserBackupService no depende de ninguna SolicitudBajaUsuario, el panel de administración (AdminController.DescargarCopiaSeguridad) expone esta misma generación de backup como una acción autónoma sobre cualquier usuario, sin crear ni requerir ninguna solicitud de baja — es decir, el administrador puede obtener en cualquier momento una copia de seguridad completa de los datos de un usuario sin que ello implique ni inicie ningún proceso de eliminación de cuenta.

Restauración de datos de uso desde una copia de seguridad: IUserBackupRestoreService.RestaurarDatosUsoAsync (acción AdminController.RestaurarDatosUso) permite, a partir del mismo ZIP de backup (con su contraseña), reinsertar en una cuenta activa únicamente los datos de uso diario: BioDataDiaria y AnaliticaClinica. Por cada registro del backup se comprueba si ya existe un registro para esa fecha (Fecha / FechaAnalisis) en la cuenta destino; si existe, se omite — los datos ya presentes en BD son siempre prioritarios sobre la copia de seguridad, que por construcción nunca puede ser más reciente. Solo se insertan las fechas que faltan, reasignando Id=0 (autogenerado) y el UsuarioId destino. La acción devuelve un resumen (RestoreDatosUsoResult) con el número de registros insertados y omitidos por cada tabla.

Consentimiento explícito registrado: la tabla ConsentimientoUsuario guarda, por usuario, la versión del texto aceptado, su huella SHA-256, la fecha y el origen (aceptación en la aplicación o consentimiento firmado fuera de ella y anotado por el administrador). Un filtro de Program.cs redirige a /Consentimiento a quien no lo tenga vigente (nunca aceptado, texto nuevo o retirado); el administrador queda exento. La retirada bloquea el acceso, corta las importaciones por token y el acceso de los profesionales a esos datos, y ofrece solicitar la baja. Las copias de seguridad incluyen estos registros.

Conservación y purga de registros: un servicio en segundo plano (RetencionRegistrosWorker) suprime cada día los registros que superan su plazo de conservación (3 años por omisión, configurable en Retencion:Anios y nunca por debajo de 2): los ficheros mensuales del registro de accesos, los ficheros diarios del registro de uso de IA y las solicitudes de baja completadas o canceladas. Deja constancia de cada purga en el propio registro de accesos y admite un modo de simulación (Retencion:SoloSimular) que solo anota lo que borraría.

Esta restauración se limita deliberadamente a los datos crudos de uso: no toca PerfilPersonal, mensajería ni documentos RGPD, y tampoco reinserta las tablas de históricos derivados (HealthScoreHistory, HealthEvolutionSnapshot, RecoveryBaseline/RecoveryDailyScore, EnergyDailyBalance) — una vez restaurados los datos crudos, estos históricos se regeneran con los servicios de recálculo ya existentes (IEnergyDailyBalanceService.RecalculateRangeAsync, IRecoveryService.CalcularHistoricoAsync / RecalcularBaselineAsync, IHealthScoreBackfillService.BackfillAsync). La recreación completa de una cuenta eliminada (perfil, relaciones, mensajería, documentos RGPD, conexión Oura...) queda deliberadamente fuera de la aplicación, como proceso manual extraordinario de back-office.

---

11.17. Módulo de detección y cuantificación de adaptación metabólica

El sistema incorpora un módulo propio (MetabolicAdaptationService) que cuantifica la adaptive thermogenesis mediante la comparación entre el TDEE teórico por el modelo energético (EnergyDailyBalance.EnergiaGastoTotalKcal) y el TDEE real estimado por balance de masa (TDEE_real = (ΣIngesta_corr − ΔPeso_kg × 7 700) / n).

La ingesta corregida es la suma de EnergyDailyBalance.EnergiaIngeridaKcal, calculada con el factor de corrección de ingesta (OllamaIntakeCorrectionFactor) vigente cada día sobre macros, y el módulo aplica regresión OLS sobre la serie de peso para aislar la variación de masa real del ruido hídrico diario. La adaptación se clasifica en cuatro niveles y los snapshots se persisten en MetabolicAdaptationSnapshots (entidad propia, con FK a AspNetUsers).

El módulo genera una serie histórica de 12 ventanas de 28 días y emite alertas automáticas de reactivación metabólica (nivel Moderada o Severa, es decir, adaptación residual ≥ 15 % del TDEE teórico, con período ≥ 20 días con datos y adherencia de pesaje suficiente) y de cobertura proteica insuficiente (< 80 %). La vista incluye un modal de información científico exhaustivo con bibliografía (Hall 2016, Rosenbaum, MATADOR/Byrne 2017), sin dependencia de nuevos servicios IA.

---

11.18. Adquisición desatendida de biometría mediante automatización REST con trazabilidad de origen y deduplicación por fuente

El sistema incorpora un endpoint REST autenticado por token opaco que permite a una aplicación de terceros remitir datos de HealthKit de forma periódica y desatendida, sin sesión interactiva del usuario, reutilizando el mismo motor de parseo y agregación (Suma/Promedio/Último) que la importación manual.

La originalidad técnica reside en dos mecanismos de robustez frente a la fragmentación de la entrada desatendida: (a) un criterio de preferencia de fuente por día que evita la duplicación de pasos, distancia y energía cuando dos dispositivos (reloj y teléfono) registran el mismo evento físico de forma simultánea; y (b) una reconstrucción del valor bruto a partir de los campos ya persistidos cuando la información de actividad y de entrenamientos llega fragmentada en llamadas independientes, garantizando un resultado final convergente con independencia del orden de llegada.

Toda escritura sobre BiodataDiaria, cualquiera que sea su canal de origen, queda marcada con fecha y código corto de procedencia, ofreciendo al usuario una verificación directa, sin inspección técnica, de si la adquisición automática está operando con la periodicidad esperada.

---

11.19. Formulación de SDS/SAP (Oxigenación nocturna)

SDS (Sleep Desaturation Score): para cada noche n se calcula la SpO₂ media de las lecturas del reloj dentro de la ventana de sueño real de ese día (respaldo: 22:00-07:00 hora de Madrid), sin descartar ninguna, exigiendo un mínimo de 5 lecturas esa noche. Un SDS superior a 85 solo se mantiene como «importante» si esa noche hay un episodio sostenido (3 lecturas consecutivas ≤ 90 % o 2 lecturas ≤ 88 %). El baseline personal (µ, σ) se calcula sobre las noches válidas de la ventana de análisis (14-90 días configurables), exigiendo un mínimo de 7 noches previas:

z = (µ_noche − SpO₂_n) / σ_noche, acotado a ±3σ
SDS = clamp(50 + z_pond × 15, 0, 100)

Nótese el signo: a diferencia de RecoveryService (sección 8.18), aquí z es positivo cuando la SpO₂ de la noche es menor que la media personal — de modo que un SDS alto representa siempre más desaturación de lo habitual en el propio usuario, nunca menos.

SAP (Sleep Apnea Probability): combina SDS con una puntuación STOP-BANG simplificada de 7 factores binarios (IMC>30, edad>65, ronquidos, apnea observada, hipertensión (≥140/90 mmHg), somnolencia diurna, alcohol registrado ese día), sin ponderación diferenciada por factor — el cuestionario STOP-BANG original tampoco la tiene (Chung et al., 2016; ver bibliografía). Los factores sin dato disponible ese día se excluyen tanto del numerador como del denominador:

SAP = clamp(0,5 × SDS + 0,5 × (puntos / factores_disponibles × 100), 0, 100)

Con menos de 4 de los 7 factores disponibles, el resultado se marca como CribadoIncompleto en lugar de presentarse como un cribado completo con datos parciales. La circunferencia de cuello, predictor adicional de STOP-BANG, se recoge en el perfil (CircunferenciaCuelloCm) pero se excluye deliberadamente de la fórmula por decisión de producto (coste de mantenimiento del dato frente a su aportación marginal al cribado).

---

11.20. Formulación del análisis de sueño (SleepAnalysisService)

Sea t una hora local en minutos del día y c un punto de corte (720 para acostarse, 1080 para despertar). La hora referenciada es:

r(t) = ((t − c) mod 1440 + 1440) mod 1440

Regularidad: desviación típica muestral de r(acostarse), r(despertar) y de los minutos dormidos sobre las noches de la ventana, calculada solo con n ≥ 10:

DT = √( Σ (xᵢ − x̄)² / (n − 1) )

Despertar precoz: para cada noche n con al menos 7 noches previas en los 28 días anteriores, H_n = P75{ r(despertar_k) : n−28 ≤ k < n } (percentil con interpolación lineal). La noche es precoz si r(despertar_n) ≤ H_n − 90. Frecuencia semanal: 7 × precoces / evaluables; se marca frecuente si, en las últimas 4 semanas, es ≥ 3 con al menos 14 noches evaluables. La tarjeta muestra la frecuencia de las últimas 4 semanas y la compara con la de las 4 semanas anteriores (al menos 7 noches evaluables en cada una).

Basal a largo plazo: las mismas medias, desviaciones típicas y frecuencia de despertar precoz calculadas sobre las noches de [inicio − 365, inicio), siendo inicio el primer día del periodo analizado; se considera suficiente con al menos 28 noches con horario.

Factores (vista profesional): para cada noche precoz p con valor f(p) del factor y un conjunto N_p de al menos 3 noches normales a |d − p| ≤ 14 días con dato, se forma el par (f(p), media f(N_p)). Con al menos 5 pares se informan media f(p), media de las medias f(N_p) y su diferencia.