Files
faceclaw/docs/validation-health-export.md
T

86 lines
5.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# R1 health export
Android Settings → Health export uses the existing toggle and text/password
editors. Export defaults off; URL and API key default empty. Only the API key
uses AES-GCM with Android Keystore and an AtomicFile in noBackupFilesDir. Keys
are masked on both glasses and phone. The URL/cursor use shared settings.
The API/image pipeline lives in the dedicated Infrastructure/FaceclawHealth Git
repository. Kubernetes manifests live in the Infrastructure repository under
FaceclawHealth, and SQL dashboards in GrafanaDashboards/Health. Protocol v1 sends normalized HealthSample/SleepSession
fields with original millisecond timestamps. Batches contain at most 200 records
and 240 KB. HTTPS is mandatory, redirects are refused, and only HTTP 200 with
accepted:true advances the cursor. No health content or keys are logged.
The exporter reads existing append journals, including revisions to old months,
without extra BLE pulls. Partial trailing lines are retried. Unresolved sleep
sessions and sample fixtures are excluded. Replayed data is upserted server-side.
A new URL/key resets delivery history safely. One batch runs per minute while
the Android process is alive; this adds no background service or wake lock and
does not promise synchronization while the app is stopped. Disable preserves
local history and existing server data. Watch/iOS export is outside this change.
Software validation: exporter tests for replay, revisions, failed/malformed
acknowledgements, redirects, destination/credential edits, fixtures, partial
records and overlapping requests; full JS suite, TypeScript and Android release
compilation. API tests additionally cover PostgreSQL rollback and deduplication.
Hardware/end-to-end validation remains pending: enable ring health sync, configure
the deployed URL/key, then compare measured timestamps/values and sleep durations
with Grafana. Test offline/reconnect, app restart, disable/re-enable and rotated
keys. Check key masking, log redaction and preservation of other preferences.
No firmware modification is needed.
Companion PRs: [Faceclaw #11](https://git.undefined-dev.fr/Blendman974/faceclaw/pulls/11),
[Infrastructure #1685](https://git.undefined-dev.fr/Infrastructure/Infrastructure/pulls/1685),
and [dashboards #6](https://git.undefined-dev.fr/Infrastructure/GrafanaDashboards/pulls/6).
Combined validation: 1137 JS tests passed, 2 skipped; TypeScript and Android
release build passed, including all seven native libraries' 16 KiB page check.
## Latest heart-rate observations
Live HR pages also carry a last-measured timestamp and value. These are now
stored as `heartRate` with `spanMs: 1`, at the exact measurement timestamp:
this denotes a point observation, **not** a ten-minute average. Existing hourly
records retain `spanMs: 3600000`. The existing local and PostgreSQL keys include
span, so readings and summaries coexist without collisions. Equal BPM at a new
timestamp is a new measurement; repeated timestamps are deduplicated across
restarts and corrected values update the same observation. Local bucket charts
and daily rollups exclude points, including when the cache is rebuilt.
The existing aligned ring pull changes from :01/:31 to :01/:11/:21/:31/:41/:51.
This is a collection cadence, not a sensor setting or a guarantee of six readings
per hour. It uses the same ring worker, connection windows and anti-spam guards;
it makes more collection attempts than before. Offline gaps remain gaps and
there is no new background service. The exporter still sends at most one batch
per minute while the Android process runs.
Timestamp handling deliberately retains the current handshake's legacy clock
convention, inverting its existing phone-timezone offset once. Only a live point
within 20 minutes of page reception and no more than two minutes in the future
is accepted; invalid/missing timestamps and BPM outside 1–300 are skipped.
Reception time is never substituted for measurement time. Old frame-journal
replay continues restoring hourly history but does not reconstruct point readings:
old pages may mix clock domains. No firmware/time-sync migration is attempted.
A timezone change around measurement or an older value can therefore leave a gap;
correct placement across such transitions still requires hardware validation.
The deployed v1 API already accepts span 1 and upserts on device/metric/time/span.
No API image, schema migration, Infrastructure change or key rotation is needed.
The Grafana overview shows separate hourly-average and latest-reading series,
with point markers for readings, not interpolated ten-minute averages.
Software checks cover latest-page conversion, invalid/stale/future readings,
timezone offsets, restart/deduplication, unchanged hourly rollups, export and
all six scheduling slots. Hardware checks remain pending: record raw/current
measurement times across several pulls, compare BPM/time with the stock app,
and check reconnect, timezone/DST transitions and collection battery impact.
Integration validation (2026-11-08): 1154 JS tests passed, 2 skipped;
TypeScript and Android release build passed, and all seven packaged native
libraries passed the 16 KiB page check. Point-ingestion code was verified in the
release bundle. Three synthetic Grafana SQL/style checks passed; the current API
accepted hourly and point records at one timestamp in a mocked persistence test.
No production database writes, firmware changes or ADB installation were performed.
Companion dashboard update: [GrafanaDashboards #7](https://git.undefined-dev.fr/Infrastructure/GrafanaDashboards/pulls/7).