mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-15 23:12:04 +00:00
Merge remote-tracking branch 'origin/main' into work/native-stepup-rebase
This commit is contained in:
commit
8119cc6c82
642 files changed
+56250
-13112
No files matched your search
+174
-33
@@ -1,7 +1,7 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: HealthLog API
|
||||
version: 1.30.33
|
||||
version: 1.32.0
|
||||
description: >-
|
||||
Self-hosted personal-health-tracking PWA — public API surface for the iOS native client and external ingest.
|
||||
|
||||
@@ -3054,11 +3054,11 @@ paths:
|
||||
- Measurements
|
||||
summary: Sleep rhythm — sleep-debt + chronotype (v1.17.0)
|
||||
description: "Returns the two server-authoritative sleep-timing signals the Sleep page + iOS render off the same
|
||||
canonical night reconstruction the Sleep Score uses: cumulative `sleepDebt` over the rolling window (calm
|
||||
`partial` state under the night threshold) and MCTQ `chronotype` (MSF/MSFsc band + social jetlag, `learning`
|
||||
state until enough free-day nights exist). Free vs work nights default to weekend = free in the user's timezone
|
||||
(no work calendar). A read-only view over existing per-stage SLEEP_DURATION rows — no schema, no new measurement
|
||||
type."
|
||||
canonical night reconstruction the Sleep Score uses: the outstanding `sleepDebt` balance over the rolling window
|
||||
(calm `partial` state under the night threshold) and MCTQ `chronotype` (MSF/MSFsc band + social jetlag,
|
||||
`learning` state until enough free-day nights exist). Free vs work nights default to weekend = free in the
|
||||
user's timezone (no work calendar). A read-only view over existing per-stage SLEEP_DURATION rows — no schema, no
|
||||
new measurement type."
|
||||
responses:
|
||||
"200":
|
||||
description: Sleep-debt + chronotype DTO.
|
||||
@@ -3126,10 +3126,12 @@ paths:
|
||||
summary: Workout detail (v1.4.32)
|
||||
description: Single-workout envelope. Owns the optional `WorkoutRoute` GeoJSON geometry + `canonicalId` pointer that
|
||||
resolves to the cluster winner so deep-links into non-canonical twin rows can redirect cleanly. Additive
|
||||
enrichment fields (`hrSeries`, `zones`, `splits`, `sportContext`, reserved `aiInsight`) are computed
|
||||
server-side. `compact=1` (sent by the web client) drops the raw `samples.samples` HR blob and
|
||||
`route.sampleTimestamps` array from the response; without it the payload is byte-identical to the v1.4.32
|
||||
contract. Cross-user rows surface as 404 (existence channel sealed).
|
||||
enrichment fields (`hrSeries`, `zones`, `splits`, `sportContext`) are computed server-side. `aiInsight` is a
|
||||
pure read of a per-workout paragraph written by a background job when the workout landed; it is null for every
|
||||
workout that predates the feature or was re-synced, and reading this endpoint never generates one. `compact=1`
|
||||
(sent by the web client) drops the raw `samples.samples` HR blob and `route.sampleTimestamps` array from the
|
||||
response; without it the payload is byte-identical to the v1.4.32 contract. Cross-user rows surface as 404
|
||||
(existence channel sealed).
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
@@ -5671,6 +5673,9 @@ paths:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 500
|
||||
workoutId:
|
||||
type: string
|
||||
maxLength: 64
|
||||
required:
|
||||
- message
|
||||
responses:
|
||||
@@ -10309,13 +10314,13 @@ paths:
|
||||
post:
|
||||
tags:
|
||||
- Documents
|
||||
summary: Summarise or transcribe a document (session-only)
|
||||
description: 'On-demand, SESSION-ONLY description of a stored document. `?mode=summary` (default) returns a short
|
||||
plain-language summary of WHAT the document is; `?mode=text` returns its raw transcribed text. The result is
|
||||
transient — nothing is persisted except the AI-budget ledger + audit log; it never reaches coach memory,
|
||||
snapshots, the structured stores, or the search index. The summary is descriptive only and never a diagnosis.
|
||||
Same VISION (empty body) / TEXT (`application/json` `{ mode: "text", text }`, opt-in local OCR) dispatch as
|
||||
extract. AI-consent / rate / budget gated. 422 with no provider.'
|
||||
summary: Summarise or transcribe a document
|
||||
description: 'On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language
|
||||
summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot,
|
||||
while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw
|
||||
transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The
|
||||
summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode:
|
||||
"text", text }`, opt-in local OCR) dispatch as extract. AI-consent / rate / budget gated. 422 with no provider.'
|
||||
parameters:
|
||||
- name: id
|
||||
in: path
|
||||
@@ -10332,6 +10337,20 @@ paths:
|
||||
- text
|
||||
default: summary
|
||||
description: "`summary` (plain-language description) or `text` (raw)."
|
||||
- name: persist
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
description: "For summary mode only: persist into an empty stored-summary slot."
|
||||
- name: replace
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
description: With `persist=true`, explicitly replace an existing stored summary.
|
||||
requestBody:
|
||||
required: false
|
||||
content:
|
||||
@@ -10361,7 +10380,7 @@ paths:
|
||||
- text
|
||||
responses:
|
||||
"200":
|
||||
description: The session-only summary (`{ summary }`) or extracted text (`{ text }`).
|
||||
description: The summary and its persistence outcome, or transient extracted text.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
@@ -12648,6 +12667,19 @@ components:
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
- type: "null"
|
||||
manufacturer:
|
||||
description: Marketing-authorisation holder / maker as printed on the carton. Free text, max 120 chars.
|
||||
anyOf:
|
||||
- type: string
|
||||
maxLength: 120
|
||||
- type: "null"
|
||||
doseStrength:
|
||||
description: Strength as printed on the container, e.g. "5 mg/0.5 ml". Free text, max 60 chars — deliberately not split
|
||||
into a number + unit because pens state strength per dose, per ml, or per cartridge.
|
||||
anyOf:
|
||||
- type: string
|
||||
maxLength: 60
|
||||
- type: "null"
|
||||
notes:
|
||||
anyOf:
|
||||
- type: string
|
||||
@@ -12681,6 +12713,19 @@ components:
|
||||
type: number
|
||||
minimum: 0
|
||||
maximum: 1000
|
||||
manufacturer:
|
||||
description: Marketing-authorisation holder / maker as printed on the carton. Free text, max 120 chars.
|
||||
anyOf:
|
||||
- type: string
|
||||
maxLength: 120
|
||||
- type: "null"
|
||||
doseStrength:
|
||||
description: Strength as printed on the container, e.g. "5 mg/0.5 ml". Free text, max 60 chars — deliberately not split
|
||||
into a number + unit because pens state strength per dose, per ml, or per cartridge.
|
||||
anyOf:
|
||||
- type: string
|
||||
maxLength: 60
|
||||
- type: "null"
|
||||
notes:
|
||||
anyOf:
|
||||
- type: string
|
||||
@@ -17710,6 +17755,10 @@ components:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
failed:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
skipped:
|
||||
type: array
|
||||
items:
|
||||
@@ -17734,6 +17783,7 @@ components:
|
||||
- inserted
|
||||
- updated
|
||||
- duplicates
|
||||
- failed
|
||||
- skipped
|
||||
- entries
|
||||
additionalProperties: false
|
||||
@@ -17751,9 +17801,10 @@ components:
|
||||
- updated
|
||||
- duplicate
|
||||
- skipped
|
||||
description: "`inserted`/`duplicate` — the row landed (advance the cursor). `updated` — a `stats:` aggregate (per-day
|
||||
cumulative total or hourly heart-rate bucket) overwrote an existing row. `skipped` — not stored (e.g.
|
||||
unmappable identifier, out-of-range value, or `malformed_hr_bucket_id`); see `reason`."
|
||||
- failed
|
||||
description: "`inserted`/`duplicate` — the row landed (advance the cursor). `updated` — a `stats:` aggregate overwrote
|
||||
an existing row. `skipped` — validation no-op; see `reason`. `failed` — retryable database failure that must
|
||||
not advance the entry cursor; the response is marked `Cache-Control: no-store`."
|
||||
reason:
|
||||
type: string
|
||||
required:
|
||||
@@ -18237,12 +18288,13 @@ components:
|
||||
- partial
|
||||
- ready
|
||||
description: "`partial` until enough tracked nights exist (calm 'still learning'); `ready` once the rolling window can
|
||||
assert a cumulative debt."
|
||||
assert a balance."
|
||||
debtMinutes:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
description: Cumulative sleep debt over the window, in minutes, after caps.
|
||||
description: Outstanding sleep-debt balance over the window, in minutes, after caps. A night below need adds its
|
||||
shortfall; a night above need pays the balance down (floored at 0).
|
||||
needMinutes:
|
||||
type: integer
|
||||
minimum: 0
|
||||
@@ -18383,9 +18435,9 @@ components:
|
||||
- chronotype
|
||||
- averagePerNight
|
||||
additionalProperties: false
|
||||
description: "Server-authoritative sleep-rhythm read: cumulative sleep debt over the rolling window + MCTQ chronotype
|
||||
(MSF/MSFsc band, social jetlag). Free vs work nights default to weekend = free in the user's timezone (no work
|
||||
calendar). A view over existing per-stage SLEEP_DURATION rows — no schema, no new type."
|
||||
description: "Server-authoritative sleep-rhythm read: the outstanding sleep-debt balance over the rolling window + MCTQ
|
||||
chronotype (MSF/MSFsc band, social jetlag). Free vs work nights default to weekend = free in the user's timezone
|
||||
(no work calendar). A view over existing per-stage SLEEP_DURATION rows — no schema, no new type."
|
||||
ListWorkoutsResponse:
|
||||
type: object
|
||||
properties:
|
||||
@@ -18648,7 +18700,9 @@ components:
|
||||
- $ref: "#/components/schemas/WorkoutSportContext"
|
||||
- type: "null"
|
||||
aiInsight:
|
||||
type: "null"
|
||||
anyOf:
|
||||
- $ref: "#/components/schemas/WorkoutActivityInsight"
|
||||
- type: "null"
|
||||
canonicalId:
|
||||
type: string
|
||||
required:
|
||||
@@ -18847,6 +18901,19 @@ components:
|
||||
- avgDistanceM
|
||||
- avgAvgHr
|
||||
additionalProperties: false
|
||||
WorkoutActivityInsight:
|
||||
type: object
|
||||
properties:
|
||||
paragraph:
|
||||
type: string
|
||||
generatedAt:
|
||||
type: string
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
required:
|
||||
- paragraph
|
||||
- generatedAt
|
||||
additionalProperties: false
|
||||
BatchWorkoutsResponse:
|
||||
type: object
|
||||
properties:
|
||||
@@ -19727,6 +19794,18 @@ components:
|
||||
format: date-time
|
||||
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
|
||||
- type: "null"
|
||||
manufacturer:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
description: Marketing-authorisation holder / maker as printed on the carton. NULL for a container registered before the
|
||||
field existed, and for plain supply rows that never carried one.
|
||||
doseStrength:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
description: Strength as printed on the container, e.g. "5 mg/0.5 ml". Free text, not split into a number + unit — pens
|
||||
state strength per dose, per ml, or per cartridge. NULL when unknown.
|
||||
notes:
|
||||
anyOf:
|
||||
- type: string
|
||||
@@ -19751,6 +19830,8 @@ components:
|
||||
- expiresAt
|
||||
- printedExpiry
|
||||
- purchasedAt
|
||||
- manufacturer
|
||||
- doseStrength
|
||||
- notes
|
||||
- createdAt
|
||||
- updatedAt
|
||||
@@ -25250,6 +25331,28 @@ components:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
dueCandidates:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
medicationId:
|
||||
type: string
|
||||
medicationName:
|
||||
type: string
|
||||
dueAt:
|
||||
type: string
|
||||
overdue:
|
||||
type: boolean
|
||||
availableFrom:
|
||||
type: string
|
||||
required:
|
||||
- medicationId
|
||||
- medicationName
|
||||
- dueAt
|
||||
- overdue
|
||||
- availableFrom
|
||||
additionalProperties: false
|
||||
required:
|
||||
- activeCount
|
||||
- scheduledToday
|
||||
@@ -25260,12 +25363,11 @@ components:
|
||||
- nextDueMedicationName
|
||||
- nextDueMedicationId
|
||||
additionalProperties: false
|
||||
description: "Today's medication block: active-medication count, today-window tally (scheduled / taken / skipped), and
|
||||
the earliest next-due slot across active medications. `nextDueOverdue: true` marks an OPEN overdue slot
|
||||
(anchor passed, still inside its catch-up band). `nextDueMedicationId` deep-links a consumer straight to the
|
||||
overdue medication's card. Staleness contract: the snapshot is cache-served, so a `nextDueAt` in the past
|
||||
with `nextDueOverdue: false` means the anchor passed after the snapshot was built — render the plain day
|
||||
summary, never an overdue state."
|
||||
description: "Today's medication block: active-medication count, today-window tally (scheduled / taken / skipped), every
|
||||
active medication's current display-due candidate, and legacy scalar fields projected from candidate zero.
|
||||
`overdue: true` marks an OPEN overdue slot (anchor passed, still inside its catch-up band); `availableFrom`
|
||||
is the canonical cadence- and dose-window-derived attribution-band start. `dueCandidates` is optional so
|
||||
older cached snapshots remain valid. Medication ids let consumers deep-link straight to the relevant card."
|
||||
healthScore:
|
||||
anyOf:
|
||||
- type: object
|
||||
@@ -30629,6 +30731,12 @@ components:
|
||||
type: string
|
||||
text:
|
||||
type: string
|
||||
persistence:
|
||||
type: string
|
||||
enum:
|
||||
- stored
|
||||
- withheld
|
||||
- failed
|
||||
additionalProperties: false
|
||||
DocumentIndexEnvelope:
|
||||
type: object
|
||||
@@ -31663,6 +31771,37 @@ components:
|
||||
items:
|
||||
$ref: "#/components/schemas/DailyPriorityItem"
|
||||
description: Bounded 0–3 rail items, never padded.
|
||||
justIn:
|
||||
anyOf:
|
||||
- type: object
|
||||
properties:
|
||||
kind:
|
||||
type: string
|
||||
enum:
|
||||
- sleep_night
|
||||
- workout
|
||||
- weight
|
||||
- blood_pressure
|
||||
- labs_panel
|
||||
description: Closed arrival kind that landed.
|
||||
at:
|
||||
type: string
|
||||
description: ISO-8601 instant of the newest sample. NEVER pre-formatted server-side — the client formats it in its own
|
||||
locale and timezone.
|
||||
required:
|
||||
- kind
|
||||
- at
|
||||
additionalProperties: false
|
||||
- type: "null"
|
||||
description: The day's newest data arrival while it is still news (under three hours old), else null. Additive since
|
||||
v1.31.0.
|
||||
reactionLine:
|
||||
anyOf:
|
||||
- type: string
|
||||
- type: "null"
|
||||
description: One-sentence generated reaction to that arrival, standing for the rest of the local day. Null whenever no
|
||||
line was generated (no provider, no consent, budget exhausted, or generation failed) — consumers fall back
|
||||
to `briefingLead` / `line`. Additive since v1.31.0.
|
||||
required:
|
||||
- generatedAt
|
||||
- phase
|
||||
@@ -31672,6 +31811,8 @@ components:
|
||||
- briefingLead
|
||||
- line
|
||||
- worthALook
|
||||
- justIn
|
||||
- reactionLine
|
||||
additionalProperties: false
|
||||
description: The one data spine of the daily-value system — composed from already-cached data, never a fresh AI call.
|
||||
Consumed by the Today surface, the daily push, and a future iOS widget.
|
||||
|
||||
@@ -112,29 +112,50 @@ mapped set (workout routes, ECG voltage traces) is counted in
|
||||
### Cumulative HK type → daily aggregate
|
||||
|
||||
Cumulative quantity types — steps, active energy, walking/running
|
||||
distance, flights climbed — get **collapsed into one row per
|
||||
user-local day** to match the iOS daily-aggregation convention.
|
||||
distance, flights climbed, time in daylight, and fall count — get
|
||||
**collapsed into one estimated row per user-local day**. `export.xml`
|
||||
contains source-specific records, not HealthKit's canonical daily
|
||||
statistics, so the importer does not sum different devices or apps
|
||||
into a source-blind total.
|
||||
|
||||
- Records are grouped by type, local day, and a SHA-256 hash of the
|
||||
available source name, source version, and device attributes.
|
||||
Values sum within each identified source-day; the largest
|
||||
source-day subtotal is selected deterministically. If every source
|
||||
attribute is absent, records remain separate rather than being
|
||||
trusted as one source. Raw source and device labels are not
|
||||
persisted.
|
||||
- The row records `EXPORT_XML_SOURCE_MAX` provenance, its distinct
|
||||
contributor count, and the selected non-identifying source hash.
|
||||
- External ID format: `stats:<HKType>:<YYYY-MM-DD>` (e.g.
|
||||
`stats:HKQuantityTypeIdentifierStepCount:2026-05-15`).
|
||||
- The day boundary respects the user's timezone preference. The
|
||||
worker defaults to `Europe/Berlin` when no preference is set
|
||||
(`src/lib/jobs/apple-health-import-worker.ts:132-133`).
|
||||
- A second import of the same archive re-folds the same days onto
|
||||
the same external IDs — the values update in place rather than
|
||||
duplicating.
|
||||
(`src/lib/jobs/apple-health-import-worker.ts`).
|
||||
- XML intervals are not reconstructed or split. A record crossing
|
||||
midnight is assigned using its mapped timestamp and remains covered
|
||||
by the explicit estimate contract.
|
||||
- A second import re-folds the same days onto the same external IDs.
|
||||
Equal-authority estimates update idempotently rather than duplicate.
|
||||
|
||||
The terminal job result exposes
|
||||
`cumulativeEstimates: { days, rows }`; the web import card warns when
|
||||
one or more cumulative days used this estimate path.
|
||||
|
||||
### Re-import idempotency
|
||||
|
||||
The two-axis idempotency story:
|
||||
|
||||
1. **File-level** — re-uploading the same `export.zip` (same SHA-256
|
||||
of bytes) short-circuits to the previous job before the parser
|
||||
even starts.
|
||||
of bytes) short-circuits to the previous job only when that job
|
||||
used the current parser revision. Existing jobs are revision 1;
|
||||
new jobs use revision 2, so a pre-fix successful archive can be
|
||||
deliberately processed again under the corrected aggregation.
|
||||
2. **Record-level** — when an older `export.zip` is re-exported from
|
||||
iOS (same history, slightly newer device timestamps), every
|
||||
record's external ID stays stable. The upsert path matches on
|
||||
`(userId, externalId)` and updates instead of inserting.
|
||||
record's external ID stays stable. The serialized reconciliation
|
||||
path matches the canonical identity and updates instead of
|
||||
inserting.
|
||||
|
||||
Practically: a user who exports monthly and re-imports each archive
|
||||
sees fresh data merged in without duplicates. The job result line
|
||||
@@ -150,14 +171,34 @@ is identical to the user-facing flow.
|
||||
|
||||
The `ImportJob` row carries `triggeredByAdminId = admin.id` so the
|
||||
status endpoint admits both the target user and the triggering
|
||||
admin. Idempotency is scoped by target user — an admin re-uploading
|
||||
the same archive for the same user resolves to the previous job.
|
||||
admin. Idempotency is scoped by target user and parser revision — an
|
||||
admin re-uploading the same archive for the same user resolves to the
|
||||
previous current-revision job.
|
||||
|
||||
Typical use: migrating a friend's history into their HealthLog
|
||||
account when they cannot run the import themselves, or backfilling
|
||||
a household member's data after the admin received the `export.zip`
|
||||
out of band.
|
||||
|
||||
## Aggregate authority and recovery
|
||||
|
||||
Native HealthKit daily statistics submitted by the iOS batch endpoint
|
||||
are canonical and carry `HEALTHKIT_STATISTICS` provenance. XML
|
||||
source-maximum estimates carry `EXPORT_XML_SOURCE_MAX`. Both use the
|
||||
same serialized reconciler with this ordering:
|
||||
|
||||
`LEGACY_UNKNOWN < EXPORT_XML_SOURCE_MAX < HEALTHKIT_STATISTICS`
|
||||
|
||||
A later XML import cannot overwrite native statistics. Native
|
||||
statistics repair an XML estimate or legacy row in either arrival
|
||||
order, and every material reconciled update or resurrection increments
|
||||
`syncVersion`. Existing Apple Health `stats:*` rows are migrated to
|
||||
`LEGACY_UNKNOWN`; they are never guessed or heuristically promoted.
|
||||
To recover an already-corrupted legacy total, the user must re-upload
|
||||
the original archive under parser revision 2 or sync native HealthKit
|
||||
statistics. Without either input, the correct per-source total cannot
|
||||
be reconstructed from the stored aggregate.
|
||||
|
||||
## Source-priority interaction
|
||||
|
||||
HealthLog's source ladder is **APPLE_HEALTH ≻ WITHINGS ≻ MANUAL ≻
|
||||
@@ -169,12 +210,12 @@ max). The defaults live in `src/lib/validations/source-priority.ts:205-220`.
|
||||
|
||||
Concrete consequences:
|
||||
|
||||
- If you already sync steps from a Withings ScanWatch and also import
|
||||
Apple Health, the Apple-Health-aggregated stream wins for the day —
|
||||
iOS HealthKit folds the watch sensor + iPhone motion data into a
|
||||
single canonical stream, so it is the most complete cumulative
|
||||
source. The Withings rows stay in the database as an audit trail
|
||||
but drop out of the per-day aggregation.
|
||||
- Native HealthKit cumulative statistics are the canonical Apple
|
||||
Health stream for a day and outrank both XML estimates and Withings
|
||||
cumulative rows. An XML upload chooses the largest source subtotal
|
||||
only; it never claims to reproduce HealthKit's device de-duplication.
|
||||
Lower-priority rows stay in the database as an audit trail but drop
|
||||
out of the displayed per-day aggregation.
|
||||
- If you weigh yourself on a Withings scale and also import Apple
|
||||
Health (which received the same reading via the Health Mate iOS
|
||||
app), the Withings row wins for display. Apple Health is
|
||||
|
||||
@@ -84,9 +84,9 @@ pnpm dlx tsx scripts/restore-backup.ts \
|
||||
/tmp/restored.json
|
||||
```
|
||||
|
||||
The production standalone image strips `tsx`, so a bare
|
||||
`pnpm tsx scripts/...` fails inside the container — always invoke
|
||||
one-shot scripts via `pnpm dlx tsx`.
|
||||
Run this command from a source checkout with the production backup variables
|
||||
exported. The script imports the full application dependency graph, which the
|
||||
minimal production image does not expose as an operator scripting environment.
|
||||
|
||||
The script downloads the object, decrypts it, and writes the JSON dump
|
||||
to disk. Importing the JSON back into a HealthLog instance is left to
|
||||
|
||||
+14
-15
@@ -46,24 +46,23 @@ metadata (`medication_schedules`):
|
||||
Always. The default mode only reports and never mutates:
|
||||
|
||||
```bash
|
||||
# inside the app container (or any checkout) — DATABASE_URL must point
|
||||
# at the target database
|
||||
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts
|
||||
# inside the production app container — DATABASE_URL is inherited
|
||||
healthlog-tsx scripts/repair-intake-anomalies.ts
|
||||
|
||||
# scoped to one account
|
||||
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --user <userId>
|
||||
healthlog-tsx scripts/repair-intake-anomalies.ts --user <userId>
|
||||
|
||||
# source-checkout equivalent
|
||||
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts
|
||||
```
|
||||
|
||||
The script is self-contained: its only import is `pg` and it reads
|
||||
`DATABASE_URL` straight from the environment (no dotenv, no `@/` path
|
||||
alias, no `src/` imports). That matters in the production container —
|
||||
the standalone image ships no project `node_modules`, so the previous
|
||||
revision died there with `Cannot find module 'dotenv/config'`. Inside
|
||||
the image `pg` resolves via `NODE_PATH=/opt/pg-boss/node_modules`; in a
|
||||
checkout it resolves from the project `node_modules`; the
|
||||
`--package pg --package tsx` pins cover any environment with neither.
|
||||
Use `pnpm dlx`, not bare `pnpm tsx` — the standalone image also strips
|
||||
`tsx`.
|
||||
alias, no `src/` imports). The production image provides the pinned
|
||||
`healthlog-tsx` launcher and resolves `pg` from its standalone runtime tree
|
||||
without retaining a package manager. In a source checkout, `pg` resolves from
|
||||
the project `node_modules`; `pnpm dlx --package pg --package tsx ...` also
|
||||
works in an environment where neither dependency is installed.
|
||||
|
||||
The dry-run prints every duplicate group (which row would be kept, which
|
||||
would be tombstoned), a table of implausible rows (id, medication,
|
||||
@@ -74,7 +73,7 @@ would write), and a table of stale-anchor pending rows.
|
||||
## Applying the fix
|
||||
|
||||
```bash
|
||||
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --fix
|
||||
healthlog-tsx scripts/repair-intake-anomalies.ts --fix
|
||||
```
|
||||
|
||||
`--fix` does five things:
|
||||
@@ -92,7 +91,7 @@ pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --fix
|
||||
in explicitly:
|
||||
|
||||
```bash
|
||||
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --fix --tombstone-implausible
|
||||
healthlog-tsx scripts/repair-intake-anomalies.ts --fix --tombstone-implausible
|
||||
```
|
||||
|
||||
`--tombstone-implausible` is refused without `--fix`.
|
||||
@@ -139,7 +138,7 @@ slot anchors:
|
||||
The default run only **reports** the proposals. Apply them explicitly:
|
||||
|
||||
```bash
|
||||
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --backfill-eras
|
||||
healthlog-tsx scripts/repair-intake-anomalies.ts --backfill-eras
|
||||
```
|
||||
|
||||
Review the dry-run table first — the inference is a heuristic. A wrongly
|
||||
|
||||
Reference in new issue
Block a user