# 后端汇总与分页查询设计

日期：2026-10-17。状态：用户确认设计及实施计划；实现、本机验证与最终审查通过，2026-10-17 15:25经用户确认部署NAS并完成就绪核对。

## 目标与范围

减少近7天、30天查询时浏览器接收、解析和遍历密集健康样本的负担。保持现有八类健康数据查询页面、指标口径、参考线、纵轴下限、工作日颜色与分页交互。所有开发、合成数据和性能测试在本机执行。NAS只做正式部署和必要的就绪核对。

代码主目录为 `D:\CodeProject\mi-fitness-health`，保留上游Git历史及此前已经完成的本地修复，建立当前版本的本地基线提交。后续修改首先写入此目录；旧Codex工作区通过受控镜像保留兼容副本，冲突时停止，不覆盖用户另外改动。不上传密码、数据库、健康导出、镜像包、运行日志或密钥。未经另行授权不推送远端。

## 方案选择

采用后端按范围汇总、服务端明细分页和服务端CSV导出。浏览器只接收图表点、数值统计、参考线所需均值，以及当前页最多10条明细。保留已有原始查询接口，避免破坏其他客户端或未来只读接入。

不采用仅把JavaScript循环平移到后端并继续返回全部样本的方式：传输和JSON解析负担仍在。也不引入新数据库、预计算历史表或常驻任务，以免增加同步一致性、存储迁移和维护成本。

## 数据读取与接口

新增只读查询入口，例如 `GET /api/views/{kind}`，kind仅允许八类已支持的数据。接收北京时间日期范围、原有类型/压力/小睡/最新记录/数量限制，以及页码。返回：

- 统计数值、记录数、覆盖日期数、参考线均值。
- 按天图表数据；长范围沿用最多120个汇总桶。
- 当前页的规范化明细、总条数、页码和固定页长10。
- 查询范围及筛选说明，便于前端拒绝晚到的旧请求。

分页换页只读取新一页明细，不重复下载全部原始样本，也不必重新汇总。汇总与首次明细采用同一SQLite读取事务；后续分页采用稳定的时间和主键排序，避免相同时间记录随机换位。同步期间记录更新时允许下次查询看到新数据，不长期持有数据库快照。

新增带相同筛选参数的只读CSV导出入口。用户点击导出时由服务器生成附件，不在浏览器重建完整样本数组；服务端采用游标分批写出，限制内存峰值。保留中文表头、全部查询结果、源字段和公式注入防护。

总览页也使用后端汇总，不再为了六个卡片拉取六份完整明细。原有API、同步端、worker和历史数据保持兼容。

## 统计与筛选口径

- 所有时间戳按北京时间归入日期，明确处理带UTC/时区偏移的记录。睡眠依醒来日期汇总；实际睡眠时长优先，缺失时才用旧时长字段回退。
- 步数按有数值记录的日期求日均；缺失日期不补0。距离与热量使用原有单位。
- 心率保留被动、静息、其他类型的每日均值；总平均使用筛选后的全部样本，静息平均仅用静息样本，不以每日均值再平均冒充样本均值。
- 睡眠包含或排除小睡，阶段缺失与阶段合计不一致仍按现有逻辑显示未分期。均值按有记录醒来日计算。
- 体重图保留每日最近一次测量，均值按全部筛选体重测量记录计算。
- 血氧、压力均值按全部筛选样本计算。压力使用1–25放松、26–50轻度、51–80中度、81–100重度，保留源level字段；0和越界值继续未分类。
- 数量限制先按北京时间日期和类型筛选，再选最近N条；统计、图表、明细和导出使用同一集合。最新体重筛选遵守同一原则。
- 固定参考值仍由现有前端配置控制；服务端返回统计均值。前端只做格式化、图表坐标与布局，不扫描全部健康样本。

## 查询与安全

使用SQLite聚合、条件筛选和LIMIT/OFFSET读取，优先复用user_id与时间字段已有索引；必要时先以宽时间范围缩小候选，再按北京时间精确过滤。不要为本次变化重写历史时间戳或改变数据表结构。所有动态排序、字段、数据类型均采用白名单，条件参数化；样本详情白名单投影，不泄露设备标识、账号或鉴权信息。

新增接口沿用现有API授权与网页代理。数据库不增加对外端口，不改Tailscale/Nginx。请求日期范围和页码设上限，避免异常查询放大负载。日历仍由网页服务缓存，更新不会阻塞健康查询。

## 验证与验收

1. 用同一批合成样本对照现有前端统计，覆盖八类数据、缺失/零值、跨午夜、睡眠小睡、相同时间记录、筛选与最近N条；新旧总数、均值、分期与导出一致。
2. 验证分页无重复漏项，非法参数/未授权请求被拒绝；原有接口仍可调用。
3. 在本机SQLite准备30天密集样本，记录旧版与新版响应体积、服务端耗时、浏览器加载耗时和页面节点。验收重点：前端首屏明细不超过10条、图表不超过120桶；随着原始样本增加，首屏传输不随样本数量线性增加。
4. 浏览器检查近7天/30天、翻页、导出、日期切换取消旧响应，确认页面布局与图例不变；本机容器验证认证、持久化挂载与升级回退。

## 部署与回退

本机验证完成后制作可审阅的离线包，明确后端和网页镜像版本、变更范围、对照结果。正式更新前按用户要求再次确认将替换的现有容器。默认仅替换健康项目backend和web；worker继续原镜像，其他生产服务、密码、端口、数据库和数据目录不改。保留旧镜像与覆盖配置，失败恢复原配置。没有数据结构迁移，回退不需恢复或删除健康数据。

## 已知边界

SQLite仍需读取/聚合选中范围；目标是降低浏览器负担与传输，而非承诺任意规模下固定响应时间。极长范围和大导出可能耗时，应通过实测说明。年份日历更新和健康数据统计独立。本设计审阅通过后再形成实施顺序并开始修改接口。