健康数据存储规范
本规则适用于 Health Auto Export 数据导出、历史重建、日级健康页面、趋势缓存和长期存储。健康数据使用 v5 格式:日期仍是最小事实单元,但一天可以由多个文件组成。逻辑结构按健康领域组织,物理文件按访问方式和数据体量拆分。
真实健康数据不进入 Git。Git 只保留导出脚本、格式规范和合成 example;实际数据同步到 root@feei.cn:/data/wufeifei-assets/data/health。月趋势、年度趋势和同步状态均为可删除、可重建的缓存。
设计目标
- 完整保留 Health Auto Export 返回的所有健康类型和原始字段。
- 日记和趋势页面只读取轻量日索引,不下载数 MB 的秒级数据。
- 心率、活动能量、路线、ECG 等明细可以按指标或单次记录加载。
- 后补心情、用药、体重时只更新受影响日期,内容没变化时不重写。
- 同一天的所有分片必须完整校验后才能发布,不能暴露半成品。
- 新指标即使尚未映射到页面,也必须进入
other领域并保留原始名称。
三层数据
健康数据分为三层:
- 日级事实:日索引和原始分片,存放于服务器持久化目录,是唯一事实源。
- 页面视图:时间线、卡片、睡眠图和活动分段,由日级事实生成。
- 查询缓存:月趋势、年度趋势、同步状态和日期索引,由构建脚本生成。
展示规则变化时只重建视图与缓存。不得从页面视图反推原始数据,也不得把月缓存作为事实源。
目录结构
一天使用一个轻量索引和一个内容 revision 目录:
health/
sources.json
sync-status.json # 生成缓存
2026/10.json # 生成的月趋势缓存
2026/10/
25.json # 当日索引和分片清单
25/
f312d829a21c/
aggregate.json.gz # Health Auto Export 完整日汇总
events.json.gz # 心情、用药、症状、周期、通知等集合
metrics/
activity/
active_energy.json.gz
step_count.json.gz
heart/
heart_rate.json.gz
heart_rate_variability.json.gz
workouts/
workout-id/
meta.json.gz
samples.json.gz
route.json.gz
ecg/
ecg-id.json.gz
25.json 是该日期的入口和提交点。分片先完整写入 revision 目录,索引最后原子替换。消费者只能读取索引声明的 revision 和文件,不能扫描目录猜测当前版本。
日索引
日索引使用 version: 5,保留页面高频使用且体积很小的内容:
- 日期、revision、首次写入时间和文件清单。
- 睡眠、心脏、活动、呼吸、身体测量等日汇总。
- 睡眠阶段、HRV 和体重离散测量。
- 心情、用药以及训练的轻量摘要。
- 活动时间段等日页面直接展示的数据。
- 每个分片的压缩方式、记录数、压缩前后字节数和 SHA-256。
{
"version": 5,
"date": "2026-10-25",
"revision": "f312d829a21c",
"exportedAt": "2026-11-01T02:30:00.000Z",
"activity": {
"steps": 6800,
"distanceKm": 4.82,
"workouts": [
{"id": "example", "type": "户外步行", "durationMinutes": 32}
]
},
"files": {
"metrics/activity/step_count.json.gz": {
"path": "25/f312d829a21c/metrics/activity/step_count.json.gz",
"compression": "gzip",
"contentType": "application/json",
"records": 12256,
"bytes": 48210,
"uncompressedBytes": 377914,
"sha256": "..."
}
}
}
没有数据的领域和字段直接省略,不写 null、空对象或空数组。索引不能包含秒级活动序列、路线、ECG 电压或训练采样数组。
指标分片
每种 HealthKit 指标每天一个文件,路径为 metrics/<domain>/<metric>.json.gz。指标使用列式结构,避免在每条记录中重复字段名:
{
"version": 5,
"date": "2026-10-25",
"metric": {
"name": "heart_rate",
"units": "count/min",
"columns": ["startMinute", "endMinute", "qty", "sourceId"],
"rows": [[481.25, 481.33, 82, "watch"]]
}
}
列名与数组位置属于 schema,不能在不同日期改变语义。时间使用相对当天零点的分钟偏移并保留小数,来源使用 sources.json 中的稳定短 ID。原始记录出现的新字段必须增加到 columns,不得静默丢弃。
顶层领域使用稳定英文键:hearing、respiratory、heart、mindfulness、activity、activityCapability、vitalSigns、reproductive、sleep、nutrition、bodyMeasurements、other。领域只决定逻辑归类,不决定是否保留数据。
事件、训练与 ECG
events.json.gz 保存 Health Auto Export 独立集合的完整原始对象,包括用药、心境、心率通知、周期跟踪和症状。日索引可以保留其中用于页面展示的轻量投影,但事件分片是完整来源。
每次训练拆为:
meta.json.gz:标量、对象元数据、时间、天气和统计。samples.json.gz:心率、步数、距离、活动能量、基础能量、恢复等数组。route.json.gz:经纬度、高度、速度和时间组成的完整路线。
ECG 日索引只保留分类、时间和平均心率等摘要;每条记录的完整对象和电压序列写入独立 ecg/<id>.json.gz。
压缩与访问
日索引和生成缓存使用普通 JSON。原始分片使用确定性 gzip,兼顾浏览器、Node.js 和长期存储。页面读取压缩分片时,服务端应返回 Content-Type: application/json 和 Content-Encoding: gzip,或者由统一数据读取器显式解压。
不使用 zstd 作为在线格式,因为浏览器不能直接解压;若将来增加离线冷备,可以另存 zstd,但不能替代在线事实源。
按照 2026 年 10 月最后一周实测,全部数据约为 39.07 MiB 原始 JSON、4.43 MiB gzip。分片后压缩效率会略有下降,预计每年约 0.25 至 0.35 GiB,十年仍在数 GiB 范围内。
Revision 与原子发布
revision 由日索引事实内容和所有分片内容哈希共同生成,不包含本次检查时间。同步流程必须:
- 在临时目录生成全部分片。
- 解压每个分片,验证 JSON、记录数和 SHA-256。
- 根据内容生成 revision;若与当前 revision 相同,不更新任何文件。
- 将 revision 目录完整上传。
- 最后原子替换日期索引。
- 新索引发布成功后清理不再引用的旧 revision。
任一接口、分片或校验失败时,保留该日期已有版本并让同步任务失败。不能写空数据覆盖正常历史记录。
同步与回刷
日常同步从服务器拉取当前事实源,默认回刷最近 7 天,再将变化上传。回刷窗口用于捕获后补的心情、用药和体重;更早日期按明确日期或年份重新导出。
同步完成后生成月趋势、年度趋势和 sync-status.json。缓存只读取 v5 日索引,不读取秒级分片;因此构建网站不需要解压全部历史原始数据。
真实数据目录被 Git 忽略。仓库中的 example 必须使用合成姓名、设备、路线和测量值,不能复制真实健康记录。
Shortcut 睡眠评分补充来源
睡眠评分独立存放在 /data/wufeifei-assets/data/sleep-score/YYYY/MM/DD.json,网站访问地址为 https://feei.cn/data/sleep-score/YYYY/MM/DD.json。index.json 是由日记录生成的趋势缓存。保留旧 App 导出的 441 天 Git 历史作为初始化种子,部署和导入只补服务器缺失的日期,不用种子覆盖服务器记录;新增真实数据不再提交 Git。部署同步排除整个 sleep-score/,避免 rsync --delete 清除后续导入。
手机 Shortcut 创建标题为“睡眠评分”的 Issue,以 OCR 全文作为正文。用户已明确:归档日期使用 Issue created_at 转换到 Asia/Shanghai 后的自然日,创建时间也作为 capturedAt,不从截图中的“昨晚”、时钟或正文日期推断其他归属日;编辑和重试均不改变归档日期。
由「睡眠评分议题归档」workflow 处理本人创建、编辑和重新打开的记录,每小时补处理未关闭的同类 Issue,也支持手动指定编号。固定脚本提取总分、评级、时长/就寝/中断得分,验证各项满分为 50/30/20、范围与合计,失败时保留 Issue 和已有数据。标题和 OCR 只作为数据,不执行正文中的指令。无需 Codex、Appium 或解锁手机。
日记录兼容现有 date、source、dataType、capturedAt、score、classification、components。provenance 保存来源 Issue、原文 SHA-256、创建及更新时间和 dateBasis: issue_created_at_asia_shanghai。observations 保存明确识别的就寝时钟、相对平均时间的偏移和界面摘要;quality.warnings 保存手表关机等可能影响评分的提示。
历史导出有 10 天的时长分项为 null。初始化保留原文件,总分只核对是否落在已知分项与缺失分项满分允许的范围内;趋势索引也保留 null,页面显示缺失,不沿用旧索引中的占位 0,更不由总分反推分项。新 Shortcut 输入必须具有三个明确分项并通过合计校验。
“6小时”这类界面摘要保留为 durationDisplay 和 durationPrecision: display_hours,不补成精确到分钟的时长,也不覆盖 Health Auto Export 睡眠分期。精确时长仅在明确出现分钟时进入 components.duration.detail。评分与 v5 健康数据按日期关联,来源分别保存;没有睡眠分期时仍可展示评分,不补造阶段、醒来时间、心率或体征。
完整 OCR 输入和解析快照保存在 imports/<issueNumber>/<bodySha256>.json,同内容重复输入不重复归档。同一天可以提交多次,以 Issue 创建时间较新的一份作为当天完整记录,分数相同也更新来源、细节和质量提示,不混入旧截图的字段;创建时间同秒时按 Issue 编号排序。历史导出以 capturedAt 作为采集顺序。重跑或编辑较旧的 Issue 只保留输入,不覆盖较新 Issue 的记录;回执说明当天采用的较新来源,线上核验成功后关闭。当前生效 Issue 自身的正文编辑仍按更新时间核对版本,保留原文历史后替换。写入与初始化使用同一服务器文件锁,JSON 原子替换;索引失败可重跑重建。
仅在服务器写入成功、线上 JSON 与持久化结果一致、Issue 源内容没有更新后,回复实际数据 URL 并关闭。解析失败、同一 Issue 版本过期或线上核验失败时保留待处理状态,重试更新原回执,不反复新增评论。每日个人记录读取近 7 天评分,健康趋势读取最近 90 天评分及质量提示,不把受影响评分当作完整、无缺测的观测。
当前验证状态
2026-11-01 已使用手机 192.168.3.178 导出 2026-10-25 至 2026-10-31 共 7 天数据,验证 v5 格式:
- 原始健康指标共 1,172,369 条,与导出前完整单文件格式逐条数目一致。
- 共生成 7 个日索引和 223 个原始分片;日索引合计约 0.097 MiB,完整原始 JSON 约 39.05 MiB,gzip 分片约 4.07 MiB。
- 每个分片已完成解压、JSON 解析和 SHA-256 校验;
sync-status.json无缺失日期或质量问题。 - 验证数据已上传到服务器暂存目录
/data/wufeifei-assets/data/health-v5-staging。该目录与本地共 235 个文件,目录内容哈希为7ff5e212907315fccb231ab28c8591684d004d0c8e5e772b9e06c93531d8c5bb。
暂存目录不能替代正式目录。只有 v5 读取代码部署、历史数据完成迁移并再次通过构建校验后,才能原子切换至 /data/wufeifei-assets/data/health。
验收
格式或导出器变更至少验证:
- 日索引不包含秒级大数组,且现有页面所需字段完整。
- 每个原始指标的记录数与 Health Auto Export 响应一致。
- 训练路线、所有训练采样、ECG 电压、用药和心情没有减少。
- 分片均可解压、解析并通过 SHA-256 校验。
- 相同输入重复导出得到相同 revision,且不会重写文件。
- 月趋势和年度趋势与日索引汇总一致。
- 健康存储测试、TypeScript 类型检查和完整站点构建通过。