diff --git a/docs/superpowers/specs/2026-06-07-export-indicator-trends-design.md b/docs/superpowers/specs/2026-06-07-export-indicator-trends-design.md new file mode 100644 index 0000000..f1a3473 --- /dev/null +++ b/docs/superpowers/specs/2026-06-07-export-indicator-trends-design.md @@ -0,0 +1,117 @@ +# 导出身体档案 — 指标趋势段 设计 + +> 2026-06-07 · 在「导出身体档案」(`HealthExportService`)的输出里,为本次就诊相关、且有历史记录的指标补一段确定性计算的趋势摘要。 + +## 背景 + +当前导出是「快照式」:`HealthExportService.retrieve()` 在时间窗内每个指标只取最近一条,`serializeData()` 序列化成单点数值(name/value/unit/range/status/date),交给 LLM 拼成「## 关键指标」一段。医生看不到指标随时间的变化方向。 + +需求:导出要带上**相关指标的趋势信息**(同一指标多次记录的变化)。 + +## 决策(已与用户确认) + +| 维度 | 决定 | +|---|---| +| 覆盖范围 | 本次就诊相关(命中关键词或异常)且时间窗内有 **≥2 次**记录的指标 | +| 粒度 | 一行摘要(首值→末值 + 方向箭头 + 时间跨度 + 次数) | +| 生成方式 | **确定性计算**(模板拼装,不经 LLM),与 `ReportCompareService` 同思路,零编造风险 | +| 呈现位置 | LLM 输出 6 段之后,**追加**独立一段 `## 指标趋势`;无数据则整段省略 | + +## 架构 + +``` +retrieve() ──► 全量 in-window 指标(裁剪前) ┐ + └─► 相关指标集(裁剪后,决定哪些 series 出趋势) ┤ + ▼ + ExportTrendBuilder.build(...) → [TrendSummary] + ▼ + Snapshot.trends ──► export() 在 completed 前追加 "## 指标趋势" +``` + +LLM 链路(prompt / `serializeData`)**完全不变**——趋势不进 JSON,LLM 不知情。 + +## 组件 + +### 1. `TrendSummary`(值类型) + +一个 series 的趋势结果。字段: + +- `title: String` — 显示名(如「收缩压」「血压」) +- `unit: String` +- `firstValue: Double`、`lastValue: Double` +- `firstDate: Date`、`lastDate: Date` +- `count: Int` — 时间窗内记录次数 +- `direction: Direction`(`.up` / `.down` / `.flat`) +- `range: String` — 参考范围原文(可空) +- `flagged: Bool` — 末值仍异常 **或** 跨越参考范围边界,为真时行首加 `⚠️` + +方法 `line() -> String`,一行中文,格式: + +``` +收缩压 152→138 mmHg ↓(参考 90-140),近 21 天 4 次 +``` + +- 方向箭头:`.up` → `↑`、`.down` → `↓`、`.flat` → `→` +- `flagged` 为真前缀 `⚠️ ` +- `range` 为空时省略「(参考 …)」括号 +- 数值用与现有指标一致的格式化(去掉无意义小数;血压等整数不带小数点) + +> 血压合并行:`title` = 「血压」,数值写成「收缩/舒张」对,如 `血压 152/96→138/88 mmHg ↓…`;方向以收缩压为准。 + +### 2. `ExportTrendBuilder`(纯函数,可单测) + +```swift +enum ExportTrendBuilder { + static func build(allInWindow: [Indicator], + relevant: [Indicator]) -> [TrendSummary] +} +``` + +逻辑: + +1. **确定相关 series**:从 `relevant` 收集 series 标识(优先 `seriesKey`,无则 `name|unit`)。 +2. **分组全量点**:把 `allInWindow` 按同一 series 标识分组;血压 `bp.systolic` + `bp.diastolic` 归到合成 series「血压」。 +3. **过滤**:只保留(a)属于相关 series、(b)点数 ≥2 的组。 +4. 每组按 `capturedAt` 升序,取首/末点,算: + - `direction`:相对变化 `|last-first|/first`,<5% → `.flat`,否则按符号 `.up`/`.down`(first 为 0 时退化按绝对差判定) + - `flagged`:末点 `status != .normal`,或首点 normal 而末点非 normal(或反之,跨界) + - `count`、`firstDate`、`lastDate`、`range`(取末点的 range) +5. 排序:`flagged` 优先,其次按 `lastDate` 倒序。 +6. 返回 `[TrendSummary]`。 + +数值解析复用现有方式(`Double(indicator.value)`);解析失败的点跳过,若有效点 <2 则该 series 不出趋势。 + +### 3. 接入 `HealthExportService` + +- `Snapshot` 加 `trends: [TrendSummary]`。 +- `retrieve()`:在现有第 268 行 fetch 全量 in-window 指标后,保留该全量列表;裁剪逻辑不变得到 `indicators`(相关集);调用 `ExportTrendBuilder.build(allInWindow: 全量, relevant: indicators)` 填入 `Snapshot.trends`。 +- `serializeData()`:**不改**(趋势不进 LLM)。 +- `export()`:在发出 `completed` 事件、把内容存进 `HealthExport.content` 之前,若 `snapshot.trends` 非空,把 `## 指标趋势` 段追加到 LLM markdown 末尾。空数据兜底路径(`isEffectivelyEmpty`)trends 自然为空,不追加。 + +`## 指标趋势` 段渲染: + +```markdown +## 指标趋势 +⚠️ 收缩压 152→138 mmHg ↓(参考 90-140),近 21 天 4 次 +空腹血糖 6.8→6.2 mmol/L ↓(参考 3.9-6.1),近 28 天 3 次 +``` + +## 测试 + +`ExportTrendBuilder.build` 是纯函数,单测覆盖: + +- 升 / 降 / 平稳(阈值边界)方向判定 +- 血压双 series 合并成一行 +- 点数 <2 的 series 被过滤 +- 不相关 series(不在 relevant 集)被过滤 +- 跨参考范围边界 → `flagged = true` +- 数值无法解析的点被跳过 + +## 不做 + +- 不改 LLM prompt / `serializeData`(零编造风险的前提) +- 不引入 embedding、不加新颜色/字体 token +- 不改导出 UI 布局(仅输出内容多一段;`HealthExportSheet` / `HealthExportDetailView` 的 `MarkdownView` 已能渲染新段落) +- 不做逐点列表 / 峰谷均值(本次只要一行摘要) +``` +