Files
HealthLog/src/lib/fhir/loinc-map.ts
T
Marc-André BombeckandClaude Opus 4.8 e984ada5f1 feat(cycle): import Apple Health reproductive data into cycle, add cycle export
Promote the reproductive HealthKit category types out of the
Apple-Health-import privacy-hold list and route them into cycle day-logs
instead of measurements, and surface cycle data on the three export
surfaces.

Import promotion:
- A new HealthKit -> cycle mapping module is the single source of truth for
  how MenstrualFlow, IntermenstrualBleeding, CervicalMucusQuality,
  OvulationTestResult, SexualActivity, PregnancyTestResult,
  ProgesteroneTestResult, Contraceptive and the symptom category types fold
  into CycleDayLog fields / seeded symptom keys. The XML importer
  accumulates same-day reproductive samples and writes one canonical
  day-log per day with source APPLE_HEALTH and a synthetic per-day
  externalId for idempotent re-import. The fold is gated on cycle tracking
  being enabled, so a non-cycle export never provisions cycle rows. A
  contraceptive method nudges the profile goal toward avoiding pregnancy
  only when the goal is still on its default. Basal body temperature stays
  a measurement and mirrors onto the day-log. Pregnancy/Lactation status
  and the pregnancy-bleeding types stay deferred; the cycle awareness types
  remain server-derived.

Export:
- FHIR emits LMP (LOINC 8665-2), average cycle length (64700-8), period
  length (64698-4) and the current phase as opt-in reproductive-health
  observations grouped into their own document section.
- The doctor PDF gains an opt-in cycle section (recent cycles, average
  length and variability, current phase), privacy-default off like mood.
- The full-backup export, the weekly backup worker and the off-host DR
  snapshot include the cycle tables, and the admin restore re-creates them;
  the day-log note round-trips as ciphertext and is never decrypted onto a
  report surface.

Mapping table documented in docs/api/cycle-healthkit-mapping.md. Adds unit
+ integration coverage for the mapping, the import routing, the FHIR
observations and the backup round-trip. OpenAPI regenerated. Six-locale
strings added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-06 10:16:54 +02:00

319 lines
9.5 KiB
TypeScript

/**
* v1.7.0 — HealthLog `MeasurementType` → FHIR R4 coding (LOINC + UCUM).
*
* Per the R-export spec table (§4.2). Types without a stable LOINC fall
* back to a local `text`-only `CodeableConcept` with the UCUM unit, and
* the absence of a `loinc` code documents that at the call site.
*
* BP is handled specially by the builder (panel 85354-9 with sys/dia
* components 8480-6 / 8462-4), so the two BP component types are NOT in
* this single-value map.
*/
export const LOINC_SYSTEM = "http://loinc.org";
export const UCUM_SYSTEM = "http://unitsofmeasure.org";
/**
* Shared custom CodeSystem for HealthKit placeholder metrics that have no
* published LOINC term. A non-LOINC code under `http://loinc.org` is a FHIR
* conformance violation, so these route here instead. Byte-aligned with the
* iOS exporter (confirmed 2026-06-01) — both clients emit the identical
* `system` + raw `HKQuantityTypeIdentifier…` `code`.
*/
export const HEALTHKIT_CODESYSTEM =
"https://healthlog.dev/fhir/CodeSystem/healthkit";
export type FhirObservationCategory =
| "vital-signs"
| "laboratory"
| "activity";
export interface LoincMapping {
/** LOINC code, or null when no stable LOINC applies (local text fallback). */
loinc: string | null;
display: string;
/** UCUM unit string (also used as the `code`). */
unit: string;
category: FhirObservationCategory;
}
/**
* Single-value measurement-type mapping. Keyed by `MeasurementType` enum
* string. BP components are intentionally absent (the builder emits a BP
* panel). Glucose is handled per-context by the builder using
* `GLUCOSE_LOINC`.
*/
export const MEASUREMENT_LOINC: Record<string, LoincMapping> = {
WEIGHT: {
loinc: "29463-7",
display: "Body weight",
unit: "kg",
category: "vital-signs",
},
BODY_MASS_INDEX: {
loinc: "39156-5",
display: "Body mass index (BMI) [Ratio]",
unit: "kg/m2",
category: "vital-signs",
},
PULSE: {
loinc: "8867-4",
display: "Heart rate",
unit: "/min",
category: "vital-signs",
},
RESTING_HEART_RATE: {
loinc: "40443-4",
display: "Heart rate --resting",
unit: "/min",
category: "vital-signs",
},
RESPIRATORY_RATE: {
loinc: "9279-1",
display: "Respiratory rate",
unit: "/min",
category: "vital-signs",
},
BODY_TEMPERATURE: {
loinc: "8310-5",
display: "Body temperature",
unit: "Cel",
category: "vital-signs",
},
OXYGEN_SATURATION: {
loinc: "59408-5",
display: "Oxygen saturation in Arterial blood by Pulse oximetry",
unit: "%",
category: "vital-signs",
},
BODY_FAT: {
loinc: "41982-0",
display: "Percentage of body fat Measured",
unit: "%",
category: "vital-signs",
},
VO2_MAX: {
loinc: "96402-2",
display: "Oxygen consumption maximum during exercise",
unit: "mL/min/kg",
category: "vital-signs",
},
HEART_RATE_VARIABILITY: {
loinc: "80404-7",
display: "R-R interval.standard deviation (Heart rate variability)",
unit: "ms",
category: "vital-signs",
},
ACTIVITY_STEPS: {
loinc: "41950-7",
display: "Number of steps in 24 hour Measured",
unit: "{steps}",
category: "activity",
},
// Stored canonically in MINUTES; the builder converts the emitted value to
// hours so it matches the UCUM `h` unit (and the iOS table). PDF unaffected.
SLEEP_DURATION: {
loinc: "93832-4",
display: "Sleep duration",
unit: "h",
category: "activity",
},
ACTIVE_ENERGY_BURNED: {
loinc: "41981-2",
display: "Calories burned",
unit: "kcal",
category: "activity",
},
WALKING_SPEED: {
loinc: "41957-2",
display: "Gait speed [Velocity] Measured",
unit: "m/s",
category: "vital-signs",
},
WALKING_ASYMMETRY: {
loinc: "91557-1",
display: "Walking asymmetry percentage",
unit: "%",
category: "vital-signs",
},
WALKING_STEP_LENGTH: {
loinc: "41955-6",
display: "Step length Measured",
unit: "m",
category: "vital-signs",
},
// Body-composition family with iOS-locked LOINC codes.
TOTAL_BODY_WATER: {
loinc: "73704-9",
display: "Body water by Bioelectrical impedance analysis",
unit: "kg",
category: "vital-signs",
},
BONE_MASS: {
loinc: "73708-0",
display: "Bone mineral content by DXA",
unit: "kg",
category: "vital-signs",
},
// HK-placeholder codes — no published LOINC term. Both iOS and the server
// emit the HealthKit identifier STRING as the `code` under the shared
// `HEALTHKIT_CODESYSTEM` (NOT the LOINC namespace — a non-LOINC code under
// http://loinc.org fails FHIR conformance). The `loinc` field below carries
// the placeholder string verbatim; the builder routes any
// `HKQuantityTypeIdentifier…` code onto the custom system.
WALKING_DOUBLE_SUPPORT: {
loinc: "HKQuantityTypeIdentifierWalkingDoubleSupportPercentage",
display: "Walking double support percentage",
unit: "%",
category: "vital-signs",
},
AUDIO_EXPOSURE_ENV: {
loinc: "HKQuantityTypeIdentifierEnvironmentalAudioExposure",
display: "Environmental audio exposure",
unit: "dB[A]",
category: "vital-signs",
},
AUDIO_EXPOSURE_HEADPHONE: {
loinc: "HKQuantityTypeIdentifierHeadphoneAudioExposure",
display: "Headphone audio exposure",
unit: "dB[A]",
category: "vital-signs",
},
FLIGHTS_CLIMBED: {
loinc: "HKQuantityTypeIdentifierFlightsClimbed",
display: "Flights climbed",
unit: "{flights}",
category: "activity",
},
WALKING_RUNNING_DISTANCE: {
loinc: "HKQuantityTypeIdentifierDistanceWalkingRunning",
display: "Distance walking/running",
unit: "m",
category: "activity",
},
TIME_IN_DAYLIGHT: {
loinc: "HKQuantityTypeIdentifierTimeInDaylight",
display: "Time in daylight",
unit: "min",
category: "activity",
},
MUSCLE_MASS: {
loinc: null,
display: "Muscle mass",
unit: "kg",
category: "vital-signs",
},
FAT_MASS: {
loinc: null,
display: "Fat mass",
unit: "kg",
category: "vital-signs",
},
FAT_FREE_MASS: {
loinc: null,
display: "Fat-free mass",
unit: "kg",
category: "vital-signs",
},
LEAN_BODY_MASS: {
loinc: null,
display: "Lean body mass",
unit: "kg",
category: "vital-signs",
},
VISCERAL_FAT: {
loinc: null,
display: "Visceral fat",
unit: "1",
category: "vital-signs",
},
// ── v1.10.0 — additive HealthKit signals (WX-A) ──
// No stable LOINC term for these Apple-specific quantities, so each
// routes through the shared HEALTHKIT_CODESYSTEM with the raw
// HKQuantityTypeIdentifier… string as the code (a non-LOINC code under
// the LOINC namespace would fail FHIR conformance).
CARDIO_RECOVERY: {
loinc: "HKQuantityTypeIdentifierHeartRateRecoveryOneMinute",
display: "Cardio recovery (1-minute heart-rate recovery)",
unit: "/min",
category: "vital-signs",
},
WRIST_TEMPERATURE: {
loinc: "HKQuantityTypeIdentifierAppleSleepingWristTemperature",
display: "Sleeping wrist temperature",
unit: "Cel",
category: "vital-signs",
},
FALL_COUNT: {
loinc: "HKQuantityTypeIdentifierNumberOfTimesFallen",
display: "Number of times fallen",
unit: "{falls}",
category: "activity",
},
SIX_MINUTE_WALK_DISTANCE: {
loinc: "HKQuantityTypeIdentifierSixMinuteWalkTestDistance",
display: "Six-minute walk test distance",
unit: "m",
category: "activity",
},
STAIR_ASCENT_SPEED: {
loinc: "HKQuantityTypeIdentifierStairAscentSpeed",
display: "Stair ascent speed",
unit: "m/s",
category: "vital-signs",
},
STAIR_DESCENT_SPEED: {
loinc: "HKQuantityTypeIdentifierStairDescentSpeed",
display: "Stair descent speed",
unit: "m/s",
category: "vital-signs",
},
BREATHING_DISTURBANCES: {
loinc: "HKQuantityTypeIdentifierAppleSleepingBreathingDisturbances",
display: "Sleeping breathing disturbances",
unit: "{count}",
category: "vital-signs",
},
};
/** BP panel + component LOINC codes. */
export const BP_PANEL_LOINC = "85354-9";
export const BP_SYS_LOINC = "8480-6";
export const BP_DIA_LOINC = "8462-4";
export const BP_UNIT = "mm[Hg]";
/**
* Per-context glucose LOINC, byte-aligned to the iOS table:
* - random / unspecified / bedtime → 2339-0 (Glucose in Blood)
* - fasting / beforeMeal → 1558-6 (Fasting glucose in Serum/Plasma)
* - afterMeal (POSTPRANDIAL) → 1521-4 (Glucose in Serum/Plasma 2h post meal)
*
* The server's `GlucoseContext` enum has no separate beforeMeal/afterMeal; its
* POSTPRANDIAL value is the afterMeal case and maps to 1521-4.
*/
export const GLUCOSE_LOINC: Record<string, { loinc: string; display: string }> =
{
FASTING: {
loinc: "1558-6",
display: "Fasting glucose [Mass/volume] in Serum or Plasma",
},
POSTPRANDIAL: {
loinc: "1521-4",
display: "Glucose [Mass/volume] in Serum or Plasma --2 hours post meal",
},
RANDOM: { loinc: "2339-0", display: "Glucose [Mass/volume] in Blood" },
BEDTIME: { loinc: "2339-0", display: "Glucose [Mass/volume] in Blood" },
};
/** Medication-adherence Observation LOINC. */
export const MEDICATION_ADHERENCE_LOINC = "71799-1";
/** Mood Observation LOINC (opt-in only). */
export const MOOD_LOINC = "76542-6";
/* ── Cycle / reproductive-health LOINCs (v1.15.0, opt-in only) ──────── */
/** Last menstrual period (LMP) start date. */
export const LMP_LOINC = "8665-2";
/** Menstrual cycle length [time]. */
export const CYCLE_LENGTH_LOINC = "64700-8";
/** Length of menses (period / bleeding duration). */
export const PERIOD_LENGTH_LOINC = "64698-4";