mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 15:23:29 +00:00
feat(measurements): hourly heart-rate batch upload contract
Define the go-forward aggregated heart-rate upload shape so clients can stop posting one Measurement per raw HealthKit sample. A heart-rate row keyed `stats:HKQuantityTypeIdentifierHeartRate:<bucket-start-hour>` carries the hour's average bpm as a single PULSE row and rides the existing `stats:` overwrite path: a re-post within the hour overwrites the value instead of duplicating, identical to the per-day cumulative rows. The hour boundary is UTC so the key is timezone-stable. The batch route rejects a row that targets the heart-rate bucket prefix with a malformed hour suffix as a per-entry skip (`malformed_hr_bucket_id`) rather than persisting an un-overwriteable row; well-formed buckets, per-sample uuid ingest, and the per-day cumulative overwrite path are all unchanged. Average-only for now — the measurement row carries a single value column, so hourly min/max would need a schema change and is left as a follow-up. Documents all three externalId shapes plus the `updated` status in the OpenAPI contract.
This commit is contained in:
1 parent
7540d0b508
commit
f38c4bed05
6 files changed
+540
-19
No files matched your search
+48
-6
@@ -7206,6 +7206,9 @@ components:
|
||||
description: HealthKit identifier (e.g. `HKQuantityTypeIdentifierBodyMass`).
|
||||
value:
|
||||
type: number
|
||||
description: Raw HealthKit reading in Apple's native unit; the server applies any canonical scaling at ingest. For an
|
||||
hourly heart-rate bucket (see `externalId`) this is the hour's AVERAGE bpm — v1.19.0 ships avg-only; min/max
|
||||
are a documented fast-follow.
|
||||
unit:
|
||||
type: string
|
||||
minLength: 1
|
||||
@@ -7235,7 +7238,21 @@ components:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 120
|
||||
description: HKSample.uuid string — the dedup key.
|
||||
description: >-
|
||||
Dedup key for the `(userId, type, source, externalId)` composite index. Three shapes:
|
||||
|
||||
• `HKSample.uuid` — a per-sample reading. First-write-wins: a re-post returns `duplicate` and the stored row
|
||||
is immutable.
|
||||
|
||||
• `stats:<HKQuantityTypeIdentifier>:<YYYY-MM-DD>` — a per-day cumulative total (Steps, Active Energy, Sleep
|
||||
Duration, Walking/Running Distance, Flights Climbed). A re-post OVERWRITES the row and returns `updated`.
|
||||
|
||||
• `stats:HKQuantityTypeIdentifierHeartRate:<bucket-start-hour>` — v1.19.0 (iOS #34) hourly heart-rate bucket
|
||||
carrying the hour's AVERAGE bpm as one PULSE row. `<bucket-start-hour>` is the ISO-8601 UTC hour boundary
|
||||
with zeroed minutes/seconds/millis and a trailing `Z` (e.g. `2026-06-21T14:00:00.000Z`). A re-post within
|
||||
the hour OVERWRITES the row and returns `updated`, so iOS uploads ~24 rows/day instead of one per raw HR
|
||||
sample. A row that targets this prefix with a malformed hour suffix is `skipped` with reason
|
||||
`malformed_hr_bucket_id`.
|
||||
externalSourceVersion:
|
||||
type: string
|
||||
minLength: 1
|
||||
@@ -11283,25 +11300,46 @@ components:
|
||||
AppleHealthBatchResponse:
|
||||
type: object
|
||||
properties:
|
||||
processed:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
inserted:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
duplicate:
|
||||
updated:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
duplicates:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
skipped:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 9007199254740991
|
||||
reason:
|
||||
type: string
|
||||
required:
|
||||
- index
|
||||
- reason
|
||||
additionalProperties: false
|
||||
entries:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/AppleHealthBatchEntryResult"
|
||||
required:
|
||||
- processed
|
||||
- inserted
|
||||
- duplicate
|
||||
- updated
|
||||
- duplicates
|
||||
- skipped
|
||||
- entries
|
||||
additionalProperties: false
|
||||
@@ -11316,8 +11354,12 @@ components:
|
||||
type: string
|
||||
enum:
|
||||
- inserted
|
||||
- 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`."
|
||||
reason:
|
||||
type: string
|
||||
required:
|
||||
|
||||
Reference in new issue
Block a user