hms/docs/superpowers/specs/2026-04-24-hms-miniprogram-iteration-design.md

HMS 患者小程序迭代设计规格

版本: v1.0 日期: 2026-04-24 状态: 草案 关联: 小程序初版设计 2026-04-23-hms-miniprogram-design.md

---

1. 概述

1.1 背景

小程序初版已完成 21 个页面、7 个 API service 的基础实现，覆盖登录、健康数据、预约挂号、检验报告、随访管理、用药提醒、健康资讯、个人中心。当前处于开发阶段，工程质量和用户体验存在明显短板，距测试阶段尚有差距。

1.2 问题全景

优先级	问题	影响
P0	大量重复代码（profile/reports ≈ report/index, profile/followups ≈ followup/index）	维护成本翻倍
P0	预约详情通过 Storage 缓存传递而非 API 获取	数据不一致
P0	EmptyState 导入方式不一致导致运行时报错	页面崩溃
P0	手机号绑定后端硬编码 "13800000000"	无法上线
P0	getTodaySummary() 调用的后端端点不存在	首页/健康页数据无法加载
P1	ErrorState 组件定义但未使用	错误处理不统一
P1	mixins.scss 定义但未使用	样式重复内联
P1	无全局错误边界	页面崩溃无兜底
P1	tryRefreshToken 静默吞异常	调试困难
P1	趋势图缓存永不过期	数据过时
P1	随访详情获取低效（listTasks().find()）	性能浪费
P1	首页/健康页缺少 loading 状态	体验空白
P1	用药提醒纯本地 Storage	换设备即丢失（后续版本解决）
P2	路径别名 @/* 未使用	代码可读性差
P2	无 schema 验证库	表单验证脆弱
P2	趋势图纯 CSS 柱状图	无交互能力
P2	用药提醒时间选择器未实现	功能不完整
P2	无日志/埋点/上报	无法追踪问题

1.3 迭代策略：混合策略

采用先基建再模块的混合策略，分 4 个 Sprint 交付：

Sprint 0 (2-3天)     Sprint 1 (3-4天)      Sprint 2 (3-4天)      Sprint 3 (4-5天)
┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  工程基础修复  │ →  │ 健康数据打磨  │ →  │ 预约+通知    │ →  │ 报告/随访/   │
│              │    │              │    │              │    │ 安全+增长    │
│ · 消除重复代码│    │ · ECharts图表│    │ · 步骤指示器  │    │ · 指标卡片   │
│ · 统一错误处理│    │ · 缓存TTL    │    │ · 周视图日历  │    │ · Token加密  │
│ · 修复数据传递│    │ · zod验证     │    │ · 订阅消息    │    │ · 手机号解密 │
│ · 统一Loading │    │ · 状态色卡片  │    │ · 时段可视化  │    │ · 埋点+分享  │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘

原则：Sprint 0 铺路，后续每个 Sprint 都受益于基础设施改善。Sprint 0 只修不建，不引入新依赖。

---

2. Sprint 0：工程基础修复

目标：消除最痛的工程问题，为后续所有 Sprint 铺路。约束 2-3 天完成。

2.1 修复阻断性 API 端点缺失

现状：前端 services/health.ts 的 getTodaySummary() 调用 GET /health/vital-signs?date=today，但后端路由中不存在此端点。后端仅有 GET /health/patients/{id}/vital-signs（需 patient_id 路径参数）。这意味着首页"今日健康"卡片和健康页的数据从一开始就无法加载。

方案：

• 后端在 erp-health 新增小程序专用端点 GET /health/vital-signs/today，通过 JWT user_id 自动关联 patient（类似已有的 GET /health/vital-signs/trend 模式）
• 前端 services/health.ts 的 getTodaySummary() 调整为调用新端点
• 此项为 Sprint 0 最高优先级，阻塞首页和健康页基本功能

涉及文件：

• 后端新增：erp-health handler + 路由注册
• 修改：services/health.ts

2.2 消除重复页面

现状：pages/report/index 与 pages/profile/reports/index 几乎完全重复，pages/followup/index 与 pages/profile/followups/index 同理。且 report/index 和 followup/index 没有明确的导航入口。

方案：

1. 删除 pages/report/index 和 pages/followup/index 及其 SCSS 文件
2. 从 app.config.ts 移除对应路由注册
3. 首页快捷入口和 profile 菜单统一指向 profile/reports 和 profile/followups
4. 如果后续需要独立入口，则抽取共享组件 components/ReportList 和 components/FollowupList，两个页面只做薄壳路由

涉及文件：

• 删除：pages/report/index.tsx、pages/report/index.scss
• 删除：pages/followup/index.tsx、pages/followup/index.scss
• 修改：app.config.ts（移除路由）
• 修改：pages/index/index.tsx（快捷入口路径）

2.2 统一错误处理

现状：ErrorState 组件已定义但未被任何页面使用，各页面内联 showToast 错误提示。无全局错误边界。

方案：

1. 所有列表页、详情页统一使用 ErrorState 组件，替换内联错误提示
2. 在 app.tsx 添加 React Error Boundary 组件，兜底页面崩溃
3. 新建 components/ErrorBoundary/index.tsx
4. 修复 tryRefreshToken 的 catch 块，添加 console.error 日志

涉及文件：

• 新增：components/ErrorBoundary/index.tsx
• 修改：app.tsx（包裹 ErrorBoundary）
• 修改：所有列表页和详情页（替换内联错误处理为 ErrorState）
• 修改：services/request.ts（tryRefreshToken 日志）

2.3 修复数据传递问题

预约详情：

• 移除 appointment_detail_cache Storage 传递
• 改为进入页面时通过 GET /health/appointments/:id 获取数据
• 后端需新增此端点（当前仅有列表 GET、创建 POST、状态更新 PUT，缺少单条查询 GET）

随访详情：

• 后端需新增 GET /health/follow-up-tasks/:id 单条查询端点（当前 {id} 路由仅注册了 PUT 和 DELETE，缺少 GET）
• 前端替换 listTasks().find() 为直接按 ID 查询

注意：以上后端新增端点为 Sprint 0 前置阻塞项。如果后端资源有限，前端先做"调用端点"的准备代码，后端并行实现。

涉及文件：

• 修改：pages/appointment/detail/index.tsx
• 修改：services/appointment.ts（新增 getDetail 方法）
• 修改：services/followup.ts（新增 getTaskDetail 方法）
• 后端新增：erp-health 预约单条查询 + 随访单条查询端点

2.4 统一 Loading 状态

现状：首页和健康页的 loading 状态已在 store 中定义但未在 UI 层消费。详情页使用内联 <Text>加载中...</Text>。

方案：

1. 首页和健康页在数据加载时展示 Loading 组件
2. 所有详情页统一使用 Loading 组件替换内联文字
3. 预约创建页三步骤切换时也展示 loading

涉及文件：

• 修改：pages/index/index.tsx（消费 loading 状态）
• 修改：pages/health/index.tsx（消费 loading 状态）
• 修改：所有详情页 tsx（替换内联加载文字）

2.5 杂项修复

项目	方案
EmptyState 导入 bug	首页 import { EmptyState } 改为 import EmptyState（默认导入）
路径别名启用	services/ 和 stores/ 层的 import 逐步改为 @/ 别名
mixins.scss 复用	新写的页面样式使用 @include card、@include flex-center、@include safe-bottom

---

3. Sprint 1：健康数据模块打磨

目标：升级健康数据录入、展示和趋势分析体验，从"能用"到"好用"。

3.1 健康卡片状态色

现状：四张健康卡片（血压/心率/血糖/体重）样式统一灰色，无状态区分。

方案：

每张卡片根据指标状态着色：

• 正常：左侧绿色边条 + 绿色"正常 ─"标签
• 偏高：左侧红色边条 + 红色"偏高 ▲{差值}"标签
• 偏低：左侧红色边条 + 红色"偏低 ▼{差值}"标签
• 无数据：灰色，保持现状

异常指标数值变红，卡片底部显示参考范围。

后端配合：后端需在新增的 GET /health/vital-signs/today 端点中返回 status（normal/high/low）和 reference_range。前端 TodaySummary 类型同步新增 reference_range 字段（当前已有 status 字段但后端无对应返回）。

涉及文件：

• 修改：pages/health/index.tsx（卡片样式逻辑）
• 修改：pages/index/index.tsx（首页健康卡片同步更新）
• 修改：services/health.ts（类型定义增加 status 字段）

3.2 ECharts 趋势图

现状：纯 CSS div 柱状图，无交互、无缩放、无 tooltip。

方案：

引入 echarts-taro3-react（设计规格中已规划）。前置条件：Sprint 1 开始前需做技术预研（spike），验证 echarts-taro3-react 在 Taro 4.2.0 + webpack5 下的兼容性。如果不可用，备选方案为 echarts-for-weixin + 手动封装为 React 组件。

实现：

• 折线图：数据点连线，异常点标红放大
• 参考范围色带：正常值区间以半透明绿色背景显示
• Tooltip：长按/点击显示具体数值和日期
• 时间范围切换：7天/30天/90天 三个 tab
• 缓存 TTL：趋势数据缓存 5 分钟后自动过期，强制重新请求

涉及文件：

• 新增：components/TrendChart/index.tsx、components/TrendChart/index.scss
• 重写：pages/health/trend/index.tsx
• 修改：stores/health.ts（缓存 TTL 机制）
• 新增依赖：echarts-taro3-react

3.3 表单验证升级

现状：所有表单验证为手动 if 判断，无 schema 约束。

方案：

引入 zod（~3KB gzip），为每个表单定义验证 schema：

// 示例：体征录入验证
const vitalSignSchema = z.object({
  indicator_type: z.enum(['blood_pressure', 'heart_rate', 'blood_sugar', 'weight']),
  value: z.number().positive(),
  extra: z.object({ systolic: z.number().min(60).max(250).optional(),
                     diastolic: z.number().min(40).max(150).optional() }).optional(),
  measured_at: z.string().datetime().optional(),
  note: z.string().max(200).optional()
});

异常值即时警告（如收缩压 > 180 显示红色提示"请及时就医"）。

录入成功后自动刷新首页卡片 + 清除趋势缓存。

涉及文件：

• 修改：pages/health/input/index.tsx（zod schema 验证）
• 修改：stores/health.ts（录入成功后清除缓存）
• 新增依赖：zod

---

4. Sprint 2：预约挂号 + 通知触达

目标：优化预约三步流程体验，建立微信订阅消息通知机制。

4.1 三步流程升级

现状：三个步骤（选科室 → 选医生 → 选日期时段）无进度指示，排班信息为纯文字列表。

方案：

步骤指示器：

• 新增 components/StepIndicator/index.tsx
• 顶部固定 1→2→3 步骤条，当前步骤高亮，已完成步骤可点击回退
• 步骤间切换带过渡动画

科室选择：

• 从文字列表改为宫格卡片（图标 + 科室名 + 医生数）
• 每个科室卡片可点击，选中后高亮边框

排班日历：

• 新增 components/WeekCalendar/index.tsx 周视图日历
• 有排班的日期标记绿点，无排班的日期灰色
• 点击日期展示该日可用时段卡片
• 时段卡片按剩余名额着色：>3 绿色、1-3 橙色、0 灰色不可选

涉及文件：

• 新增：components/StepIndicator/index.tsx
• 新增：components/WeekCalendar/index.tsx
• 重写：pages/appointment/create/index.tsx

4.2 微信订阅消息

现状：无任何推送通知机制。

方案：

1. 后端在微信公众平台注册订阅消息模板：

   • 预约就诊提醒（就诊前 1 天推送）
   • 随访任务提醒（截止前 1 天推送）
   • 报告出具通知（新报告发布时推送）

2. 前端在关键场景引导用户订阅：

   • 预约成功后弹出订阅授权
   • 随访提交后引导订阅下次提醒

3. 后端定时任务检查待推送消息并触发

4. 降级设计：用户拒绝订阅时，消息仍写入 erp-message 消息中心。小程序"我的"页面顶部显示未读消息数量红点，作为消息触达的备选渠道。

涉及文件：

• 修改：pages/appointment/detail/index.tsx（预约成功后订阅引导）
• 修改：pages/followup/detail/index.tsx（随访提交后订阅引导）
• 后端新增：erp-server 订阅消息模板注册 + 定时推送任务

---

5. Sprint 3：报告/随访/个人中心 + 安全 + 增长

目标：打磨剩余模块，完成安全加固和增长基础建设，达到可测试状态。

5.1 报告详情页升级

现状：所有指标卡片样式相同，无法一眼区分正常/异常。

方案：

指标卡片按状态着色：

• 正常：绿色背景 + 绿色"✓ 正常"标签 + 绿色数值
• 偏高：红色背景 + 红色"↑ 偏高"标签 + 红色数值
• 偏低：红色背景 + 红色"↓ 偏低"标签 + 红色数值

顶部汇总标签：2 项异常 · 1 项正常，一眼掌握整体状况。

涉及文件：

• 修改：pages/report/detail/index.tsx
• 修改：pages/profile/reports/index.tsx（如果仍独立存在）

5.2 随访 UX 细节

• 任务卡片增加截止日期倒计时（"还剩 2 天"，红色紧迫）
• 过期任务灰色标记
• 提交记录后增加"提交成功"确认动画（checkmark 缩放）

涉及文件：

• 修改：pages/profile/followups/index.tsx
• 修改：pages/followup/detail/index.tsx

5.3 个人中心改进

用药提醒：

• 实现时间选择器 Picker（替换当前静态文本）
• 增加"提醒开关"（enabled/disabled）
• 注：用药提醒数据仍为本地 Storage 存储，后端同步作为后续版本事项。MVP 阶段接受"换设备即丢失"的限制。

就诊人管理：

• 增加编辑功能（当前只能添加不能编辑）
• 复用 family-add 页面，传入已有数据进入编辑模式

涉及文件：

• 修改：pages/profile/medication/index.tsx（时间 Picker）
• 修改：pages/profile/family/index.tsx（编辑入口）
• 修改：pages/profile/family-add/index.tsx（编辑模式支持）

5.4 安全加固

5.4.1 Token 安全

现状：Access Token 和 Refresh Token 明文存储在 Taro.setStorageSync。

方案：

MVP 阶段采用简化方案：微信小程序的 Storage 本身有沙箱隔离，明文存储的边际风险有限。做以下最低成本改进：

• 使用 wx.getRandomValues() 生成随机密钥，单独 key 存储
• Token 存储时用此密钥做简单混淆（XOR 或 AES-ECB 单块加密）
• 目的：防止 Storage 被直接明文读取，非追求密码学安全级别

后续版本：如果合规要求提高，再升级为完整的 AES-GCM 方案。

涉及文件：

• 新增：utils/crypto.ts（轻量混淆工具）
• 修改：stores/auth.ts（Storage 读写走混淆层）

5.4.2 手机号真实解密

现状：wechat_service.rs 第 82 行硬编码 "13800000000"。

方案：

• 后端接入微信 phonenumber.getPhoneNumber 接口
• 使用 encryptedData + iv + session_key 解密真实手机号
• 前端无需改动（已传递正确的 encryptedData 和 iv）

涉及文件：

• 修改：crates/erp-auth/src/service/wechat_service.rs

5.4.3 用户协议与隐私政策

• 新增 pages/agreement/index.tsx 页面
• 登录页增加"阅读并同意《用户协议》和《隐私政策》"勾选
• 权限使用说明文案（获取手机号用途声明）

涉及文件：

• 新增：pages/agreement/index.tsx
• 修改：pages/login/index.tsx（协议勾选）
• 修改：app.config.ts（新增路由）

5.5 增长基础

5.5.1 数据埋点

新增 services/analytics.ts，轻量事件记录：

// 核心事件类型
type AnalyticsEvent =
  | { type: 'page_view'; page: string; duration_ms?: number }
  | { type: 'feature_use'; feature: string; action: string }
  | { type: 'error'; message: string; stack?: string }

• 页面进入/离开自动记录 page_view
• 关键操作（录入数据、创建预约、提交随访）记录 feature_use
• 捕获的错误记录 error
• MVP 阶段：事件写入本地 console.info + Taro Storage 缓存（最近 100 条）
• 后续版本：批量上报到后端 POST /api/v1/analytics/events

涉及文件：

• 新增：services/analytics.ts
• 修改：app.tsx（全局页面进入/离开监听）

5.5.2 分享能力

• 文章详情页支持分享到微信好友/朋友圈
• 自定义分享卡片（标题 + 摘要 + 封面图）通过 onShareAppMessage 和 onShareTimeline 实现

后续版本：健康报告 Canvas 分享图片生成、PC 扫码登录。

涉及文件：

• 修改：pages/article/detail/index.tsx（onShareAppMessage + onShareTimeline）

---

6. 文件变更总览

新增文件

文件	说明	Sprint
components/ErrorBoundary/index.tsx	全局错误边界	0
components/TrendChart/index.tsx	ECharts 趋势图	1
components/StepIndicator/index.tsx	步骤指示器	2
components/WeekCalendar/index.tsx	周视图日历	2
pages/agreement/index.tsx	用户协议/隐私政策	3
utils/crypto.ts	Token 加密工具	3
services/analytics.ts	数据埋点	3

删除文件

文件	原因	Sprint
pages/report/index.tsx	与 profile/reports 重复	0
pages/report/index.scss	同上	0
pages/followup/index.tsx	与 profile/followups 重复	0
pages/followup/index.scss	同上	0

新增依赖

依赖	用途	体积	Sprint
echarts-taro3-react	交互式图表	封装层 ~5KB + echarts 按需 ~100-200KB (gzip)	1
zod	表单 schema 验证（长期投资）	~3KB (gzip)	1

---

7. 约束与风险

风险	应对策略
ECharts 增大包体积	按需引入 echarts 模块，不引入全量包；监控主包大小不超过 2MB
微信订阅消息需用户主动触发	在预约成功、随访提交等高意愿场景引导订阅
Token 加密增加启动耗时	AES-GCM 加解密 < 1ms，可忽略
zod 增加包体积	3KB gzip，远小于自写验证代码量
Sprint 0 范围膨胀	严格只修不建，不引入新依赖，不重构架构
后端端点未实现阻塞前端	Sprint 0/1 的端点基本已实现；Sprint 2 订阅消息、Sprint 3 analytics 需后端配合

---

8. 验收标准

每个 Sprint 完成时必须满足：

• pnpm build:weapp 生产构建通过
• 微信开发者工具无编译错误
• 所有涉及页面真机预览功能正常
• 无 console.error 或未捕获异常
• 已修改的页面 loading/error/empty 三态完整
• 所有代码已提交