hms/docs/superpowers/specs/2026-04-25-hms-v2-iteration-design.md

HMS V2 迭代设计 — 血透专科健康管理平台

日期: 2026-04-25 状态: 待评审 前置文档: 2026-04-23-health-management-module-design.md, 2026-04-24-health-module-iteration-design.md 需求来源: 客户功能需求文档 docs/健康管理/管理系统功能文档(1).xlsx

---

1. 背景与动机

1.1 业务定位变化

V1 的健康管理模块定位为通用健康管理平台，覆盖患者管理、健康数据、预约排班、随访管理、咨询管理五大功能。

客户反馈后，明确业务定位为血透（透析）专科健康管理平台，面向肾病/透析患者和医护群体。这带来三个重大变化：

1. 数据模型专科化 — 从通用健康指标（血压/心率/血糖/体重/体温）扩展为血透专科指标（透析记录、化验报告、日常监测）
2. 新增积分商城 — 替代原计划的完整电商，用积分体系驱动患者活跃度
3. 新增医护端小程序 — 独立入口，医护可查看患者数据、填写透析记录、回复咨询

1.2 客户需求来源

客户通过 Excel 功能文档定义了三端需求：

端	核心功能
患者端小程序	首页、数据上报（透析/化验/日常）、在线咨询、积分商城、预约与随访、个人中心
医护端小程序	数据概览、患者管理、咨询回复、随访管理、报告解读
PC 管理后台	系统管理、患者管理、健康数据中心、咨询管理、商城管理、内容管理、统计报表、系统设置

---

2. 需求-实现差距分析

2.1 已有功能匹配度

客户需求	已有实现	匹配度	需要的工作
患者列表/档案	Patient CRUD + 18 实体	90%	微调
在线咨询（图文）	Consultation 模块	70%	加语音/客服通道
预约管理	Appointment 模块	60%	加透析专项预约
随访任务/台账	Follow-up 模块	80%	微调
科普文章	Article 模块	90%	微调
医护管理	Doctor 模块	80%	微调
账号权限/操作日志	erp-auth RBAC	95%	基本不变
患者标签	Tag 模块	90%	微调
小程序健康数据	6 种指标录入 + ECharts 趋势图	80%	扩展指标 + 透析数据

2.2 全新模块

模块	说明	复杂度
血透透析记录	透析日期/时间、干体重、透前/后血压、心率、超滤量、症状	中
日常监测扩展	饮水量、尿量 + 打卡模式	低
化验报告上传	拍照上传 + 指标录入	中
积分商城	积分获取、商品兑换、二维码核销	高
线下活动	活动管理、报名、扫码签到	中
在线咨询（IM）	客服通道、医生通道、图文/语音消息	高
医护端小程序	独立小程序，医护专属功能	高
统计报表中心	患者增长、咨询量、随访完成率、商城销售	中-高

---

3. 积分商城设计

3.1 核心链路

赚积分 → 攒积分 → 花积分 → 核销

3.2 实现方式

放在 erp-health 原生模块内，直接复用现有患者体系和事件机制。

3.3 积分获取渠道（数据库可配置）

渠道	积分	说明
每日健康打卡	可配置/天	完成日常监测数据填写触发
数据上报	可配置/次	上传化验单、填透析记录
线下活动签到	活动配置	到院参加讲座/义诊等
连续打卡奖励	阶梯配置	连续 7/14/30 天额外加分
医生互动	可配置/次	完成一次咨询、回复随访问卷

积分获取规则通过 points_rule 表配置，管理员可在 PC 端调整积分值、每日上限、连续奖励等参数。

3.4 兑换品类

类型	兑换物	履约方式
实物	血透护理用品、肾病食品、慢病器械	到院自提（二维码核销）
服务券	免费抽血、肾功能检查、营养咨询	生成预约券 → 线下二维码核销
权益	免费停车券、优先预约权	虚拟权益即时生效

3.5 核销方式

用户兑换后生成二维码（UUID），到院后工作人员扫码核销。

服务券类型核销后可自动关联预约系统创建预约。

3.6 积分过期机制

滚动 12 个月过期，FIFO 先进先出结算。

• 每笔积分（earn）有独立 expires_at（创建时间 + 12 个月）
• 每日后台任务扫描并标记过期积分
• 消费时从最老的未过期积分开始扣减
• 每笔积分支持部分消费（remaining_amount 字段）

3.7 数据模型（8 张新表）

points_account（积分账户）

字段	类型	说明
id	UUID v7	PK
patient_id	UUID	FK → patient，唯一约束
balance	i32	当前可用积分
total_earned	i32	累计获得
total_spent	i32	累计消耗
total_expired	i32	累计过期
version	i32	乐观锁
tenant_id	UUID	租户
created_at / updated_at / created_by / updated_by / deleted_at	—	标准字段

points_rule（积分规则，数据库可配置）

字段	类型	说明
id	UUID v7	PK
event_type	String	触发事件：daily_checkin / data_report / lab_upload / event_checkin / consultation_complete / followup_complete
name	String	规则名称（展示用）
description	String	规则描述
points_value	i32	单次获得积分
daily_cap	i32	每日上限（0 = 无限制）
streak_7d_bonus	i32	连续 7 天额外奖励
streak_14d_bonus	i32	连续 14 天额外奖励
streak_30d_bonus	i32	连续 30 天额外奖励
is_active	bool	是否启用
tenant_id	UUID	租户
标准字段	—	—

points_transaction（积分流水，FIFO 桶模型）

字段	类型	说明
id	UUID v7	PK
account_id	UUID	FK → points_account
type	Enum	earn / spend / expired / refund
amount	i32	正数=获得，负数=消耗
remaining_amount	i32	该笔积分剩余可用量（earn 类型）
status	Enum	active / expired / consumed
expires_at	DateTime	过期时间（earn 类型：创建 + 12 个月）
balance_after	i32	操作后账户余额快照
rule_id	UUID	FK → points_rule（earn 类型）
order_id	UUID	FK → points_order（spend 类型，可空）
description	String	流水描述
tenant_id	UUID	租户
标准字段	—	—

points_product（兑换商品）

字段	类型	说明
id	UUID v7	PK
name	String	商品名称
type	Enum	physical / service / privilege
points_cost	i32	兑换所需积分
stock	i32	库存数量（-1 = 无限）
image_url	String	商品图片
description	Text	商品描述
service_config	JSON	服务类型配置（service 类型：关联检查项目、有效期等）
is_active	bool	是否上架
sort_order	i32	排序权重
tenant_id	UUID	租户
标准字段	—	—

points_order（兑换订单）

字段	类型	说明
id	UUID v7	PK
patient_id	UUID	FK → patient
product_id	UUID	FK → points_product
points_cost	i32	消耗积分（冗余，防商品价格变化）
status	Enum	pending / verified / cancelled / expired
qr_code	UUID	核销二维码（UUID v4）
verified_by	UUID	核销人 FK → user
verified_at	DateTime	核销时间
expires_at	DateTime	订单过期时间（实物/服务券有效期）
notes	String	备注
tenant_id	UUID	租户
标准字段	—	—

points_checkin（每日打卡）

字段	类型	说明
id	UUID v7	PK
patient_id	UUID	FK → patient
checkin_date	Date	打卡日期
consecutive_days	i32	连续打卡天数（计算值）
tenant_id	UUID	租户
created_at	DateTime	—

唯一约束：(patient_id, checkin_date)

offline_event（线下活动）

字段	类型	说明
id	UUID v7	PK
title	String	活动标题
description	Text	活动描述
event_date	Date	活动日期
start_time / end_time	Time	活动时间
location	String	活动地点
points_reward	i32	参与奖励积分
max_participants	i32	最大参与人数（0 = 无限制）
current_participants	i32	已报名人数
status	Enum	draft / published / ongoing / completed / cancelled
image_url	String	活动封面图
tenant_id	UUID	租户
标准字段	—	—

offline_event_registration（活动报名 + 签到）

字段	类型	说明
id	UUID v7	PK
event_id	UUID	FK → offline_event
patient_id	UUID	FK → patient
status	Enum	registered / checked_in / cancelled
checked_in_at	DateTime	签到时间
checked_in_by	UUID	签到确认人 FK → user
points_granted	bool	是否已发放积分
tenant_id	UUID	租户
标准字段	—	—

唯一约束：(event_id, patient_id)

3.8 积分获取链路

健康打卡 → 触发事件 → points_rule 匹配规则 → 写入 points_transaction → 更新 points_account.balance
数据上报 → 同上                                          ↓
咨询完成 → 同上                                     连续打卡检查
线下签到 → 同上                                     → 达到 7/14/30 天？
                                                    → 额外 bonus transaction

3.9 兑换核销链路

用户浏览商品 → 兑换（扣积分）→ 生成 points_order + QR（UUID v4）
                                        ↓
                            用户到院出示二维码
                                        ↓
                            工作人员扫码（小程序/PC）→ 状态变 verified
                                        ↓
                            type=service → 自动创建预约券
                            type=physical → 库存扣减

3.10 后台任务

任务	频率	说明
积分过期扫描	每日	扫描 expires_at < now 的 earn 记录，标记 expired，扣减 balance
订单过期扫描	每日	扫描未核销且过期的订单，标记 expired，退还积分
连续打卡计算	每日	计算各患者连续打卡天数，触发阶梯奖励

3.11 API 端点

患者端：

方法	路径	说明
GET	/api/v1/points/account	查看我的积分账户
POST	/api/v1/points/checkin	每日打卡
GET	/api/v1/points/checkin/status	打卡状态（连续天数等）
GET	/api/v1/points/transactions	积分流水（分页）
GET	/api/v1/points/products	商品列表（分页、按类型筛选）
GET	/api/v1/points/products/{id}	商品详情
POST	/api/v1/points/exchange	兑换商品
GET	/api/v1/points/orders	我的兑换订单
GET	/api/v1/points/orders/{id}	订单详情（含二维码）
GET	/api/v1/offline-events	线下活动列表
GET	/api/v1/offline-events/{id}	活动详情
POST	/api/v1/offline-events/{id}/register	报名活动

医护/管理员端：

方法	路径	说明
POST	/api/v1/points/verify	扫码核销
CRUD	/api/v1/admin/points/rules	积分规则管理
CRUD	/api/v1/admin/points/products	商品管理
GET	/api/v1/admin/points/orders	订单管理（导出）
GET	/api/v1/admin/points/statistics	积分统计
CRUD	/api/v1/admin/offline-events	线下活动管理
POST	/api/v1/admin/offline-events/{id}/checkin	活动扫码签到

3.12 PC 管理后台新增页面

页面	功能
积分规则管理	增删改规则、启用/禁用、调整积分值和上限
商品管理	增删改兑换品、设置库存、上传图片、设置积分价格
订单管理	查看兑换记录、手动核销、导出
线下活动管理	创建活动、设置积分奖励、查看报名/签到名单
积分统计	总发放/总消耗/活跃用户排行、积分流水查询

---

4. 血透专科数据模型

4.1 设计决策

• 独立实体表：不复用现有 health_data 键值对结构，每类数据一张独立表
• 医护+患者协同上报：透析记录由医护填写，化验报告由患者上传/医护审阅，日常监测由患者填写

4.2 权限矩阵

数据	患者端	医护端	PC 管理后台
透析记录	查看（只读）	创建/编辑	查看/导出/统计
化验报告	上传照片/查看	审阅/标注/解读	查看/导出
日常监测	创建/查看	查看/预警	查看/统计
AI 健康报告	查看	查看/编辑	查看/导出

4.3 新增实体

dialysis_record（透析记录）

字段	类型	说明
id	UUID v7	PK
patient_id	UUID	FK → patient
dialysis_date	Date	透析日期
start_time	Time	开始时间
end_time	Time	结束时间
dry_weight	Decimal(5,1)	干体重 (kg)
pre_weight	Decimal(5,1)	透前体重 (kg)
post_weight	Decimal(5,1)	透后体重 (kg)
pre_bp_systolic	i32	透前收缩压
pre_bp_diastolic	i32	透前舒张压
post_bp_systolic	i32	透后收缩压
post_bp_diastolic	i32	透后舒张压
pre_heart_rate	i32	透前心率
post_heart_rate	i32	透后心率
ultrafiltration_volume	i32	超滤量 (ml)
dialysis_duration	i32	透析时长 (min)
blood_flow_rate	i32	血流量 (ml/min)
dialysis_type	Enum	HD / HDF / HF
symptoms	JSON	不适症状数组 ["低血压","恶心","抽筋"]
complication_notes	Text	并发症备注
status	Enum	draft / completed / reviewed
reviewed_by	UUID	FK → user，审阅医生
reviewed_at	DateTime	审阅时间
tenant_id	UUID	租户
标准字段	—	created_at / updated_at / created_by / updated_by / deleted_at / version

lab_report（化验报告）

字段	类型	说明
id	UUID v7	PK
patient_id	UUID	FK → patient
report_date	Date	化验日期
report_type	Enum	kidney_function / blood_routine / electrolyte / liver_function / other
source	Enum	manual_input / photo_upload
image_urls	JSON	化验单照片 URL 数组
items	JSON	指标数据数组（见下方结构）
doctor_notes	Text	医生解读/批注
reviewed_by	UUID	FK → user，审阅医生
reviewed_at	DateTime	审阅时间
status	Enum	pending / reviewed
tenant_id	UUID	租户
标准字段	—	—

items JSON 结构：

[
  {
    "name": "肌酐",
    "value": "856",
    "unit": "μmol/L",
    "reference_low": 44,
    "reference_high": 133,
    "is_abnormal": true
  },
  {
    "name": "血钾",
    "value": "6.2",
    "unit": "mmol/L",
    "reference_low": 3.5,
    "reference_high": 5.3,
    "is_abnormal": true
  }
]

daily_monitoring（日常监测）

字段	类型	说明
id	UUID v7	PK
patient_id	UUID	FK → patient
record_date	Date	记录日期
morning_bp_systolic	i32	晨起收缩压
morning_bp_diastolic	i32	晨起舒张压
evening_bp_systolic	i32	晚间收缩压
evening_bp_diastolic	i32	晚间舒张压
weight	Decimal(5,1)	体重 (kg)
blood_sugar	Decimal(4,1)	血糖 (mmol/L)
fluid_intake	i32	饮水量 (ml)
urine_output	i32	尿量 (ml)
notes	Text	备注
tenant_id	UUID	租户
标准字段	—	—

唯一约束：(patient_id, record_date)

4.4 与现有模块的关系

patient（已有）
  ├── dialysis_record（新增）   1:N  每次透析一条
  ├── lab_report（新增）        1:N  每次化验一份
  ├── daily_monitoring（新增）  1:N  每天一条
  ├── health_data（已有，保留） 1:N  通用指标仍可用
  ├── appointment（已有）       1:N  透析预约走这里
  └── follow_up（已有）         1:N  随访任务

4.5 化验报告 items 用 JSON 的原因

• 化验项目数量和类型因报告而异（肾功能 8 项 vs 血常规 20+ 项）
• 不需要按单个指标做复杂查询（都是按患者+日期范围查整份报告）
• JSON 内含 is_abnormal 标记，前端直接渲染异常标红
• PostgreSQL JSONB 支持按单个指标查询趋势（未来可加物化视图展平）

4.6 数据上报协同流程

透析记录：医护在医护端小程序/PC 填写 → 患者端只读查看

化验报告：患者拍照上传照片 + 手动填写指标 → 医护审阅/标注/解读 → 患者查看异常标红+医生解读

日常监测：患者每日填写（血压/体重/血糖/饮水量/尿量）→ 触发积分获取 → 医护端查看趋势+异常预警

4.7 新增 API 端点

透析记录：

方法	路径	说明
GET	/api/v1/health/patients/{id}/dialysis-records	患者透析记录列表
GET	/api/v1/health/dialysis-records/{id}	透析记录详情
POST	/api/v1/health/dialysis-records	创建透析记录（医护）
PUT	/api/v1/health/dialysis-records/{id}	更新透析记录（医护）

化验报告：

方法	路径	说明
GET	/api/v1/health/patients/{id}/lab-reports	患者化验报告列表
GET	/api/v1/health/lab-reports/{id}	报告详情
POST	/api/v1/health/lab-reports	上传化验报告（患者/医护）
PUT	/api/v1/health/lab-reports/{id}/review	医生审阅（标注+解读）

日常监测：

方法	路径	说明
GET	/api/v1/health/patients/{id}/daily-monitoring	患者日常监测列表
POST	/api/v1/health/daily-monitoring	上报日常监测（患者）
GET	/api/v1/health/daily-monitoring/trend	趋势数据查询

---

5. 小程序迭代设计

5.1 患者端小程序

新 TabBar 结构

首页 | 上报 | 咨询 | 商城 | 我的

替换现有：首页 | 健康 | 预约 | 资讯 | 我的

首页（改造）

• 公告轮播（Banner 组件）
• 功能入口 Grid：数据上报、我的医生、在线咨询、血透预约、积分商城
• 今日健康打卡入口（未打卡时醒目提示）
• 健康概览卡片：血压、体重、最近透析记录
• 今日提醒列表：透析预约、血压测量、用药提醒

上报 Tab（改造自"健康"）

• 打卡区：血压/体重/血糖/饮水/尿量 快捷填写入口
• 数据类型切换：日常监测 / 透析记录（只读）/ 化验报告
• 趋势图（ECharts）：血压/体重/血糖 折线图
• 子页面：
  • 日常监测填写表单
  • 化验报告上传（拍照 + 指标填写）
  • 透析记录详情（只读）
  • 化验报告详情（含医生批注）
  • 趋势分析详情（大图 + AI 解读）

咨询 Tab（全新）

• 咨询类型切换：医生 / 客服
• 最近对话列表（未读红点）
• 子页面：
  • 选择医生
  • 聊天界面（图文/语音 + 上传报告）
  • 客服对话

商城 Tab（全新）

• 我的积分 + 签到按钮
• 商品分类：全部 / 实物 / 检查 / 权益
• 商品列表（网格）
• 线下活动入口
• 子页面：
  • 商品详情 + 兑换
  • 兑换确认（生成二维码）
  • 我的订单（待核销/已核销/已过期）
  • 线下活动详情 + 报名
  • 积分明细

我的 Tab（改造）

• 个人信息 + 积分展示 + 连续打卡天数
• 就诊人管理（已有）
• 健康档案
• 我的医生
• 我的预约（从 TabBar 降级为菜单入口）
• 我的报告（已有）
• 我的随访（已有）
• 我的订单（积分商城）
• 消息通知（新增）
• 用药提醒（已有，需接入后端）
• 设置（已有）

5.2 医护端小程序（V2）

医护端为独立小程序（独立 AppID），V2 实现。V1 阶段医护功能通过 PC 管理后台覆盖。

V2 页面结构（约 18 页）

TabBar：概览 | 患者 | 咨询 | 随访 | 我的

• 概览：今日待回复咨询数、异常预警列表、今日透析患者数、随访任务数
• 患者：患者列表（按透析/高危/标签筛选）、患者详情（档案+透析记录+化验+趋势图+标签）、填写透析记录、报告解读
• 咨询：未读消息列表、图文/语音回复、发送科普文章
• 随访：随访任务列表、填写记录、台账导出
• 我的：医生信息、我的患者、排班日历、科普文章管理

5.3 页面工作量统计

端	改造页	新增页	总计
患者端	5（首页/健康/我的/预约/资讯改造）	~15（咨询3+商城6+上报子页4+通知2）	~20 页
医护端（V2）	0	18	18 页

---

6. 在线咨询设计（V2 详情待补充）

6.1 核心需求

• 客服通道：订单/物流/使用问题
• 医生通道：选择医生、发送问题、上传报告、语音/文字沟通
• 留言功能：医生离线时留存问题

6.2 技术方向

• V1 可先实现基于轮询的图文消息（复用现有 Consultation 模块）
• V2 升级为 WebSocket 实时通信 + 语音消息
• 客服通道可对接第三方客服系统（如美洽、智齿）

---

7. PC 管理后台新增页面

7.1 健康数据中心（新增）

页面	功能
透析数据统计	透析次数趋势、干体重变化、超滤量统计
异常指标排行	血钾/血磷/肌酐异常患者排行
上报率统计	患者数据上报活跃度、打卡率

7.2 商城管理（新增）

页面	功能
积分规则管理	增删改积分获取规则
商品管理	增删改兑换商品、库存管理
订单管理	兑换记录查看、手动核销、导出
线下活动管理	活动创建、报名/签到管理
积分统计	发放/消耗/活跃排行

7.3 统计报表（新增）

页面	功能
患者增长	新增患者趋势、活跃度
咨询量	咨询次数/回复率/满意度
随访完成率	随访任务执行统计
商城数据	兑换排行、库存周转

---

8. AI 分析能力（V2）

8.1 V1 预留

• 趋势图已通过 ECharts 实现（现有 TrendChart 组件）
• 异常指标通过 is_abnormal 标记和阈值校验实现
• 健康报告可生成基础版（数据汇总 + 异常标注）

8.2 V2 增强

• LLM 集成：自然语言健康报告生成
• AI 辅助：化验单 OCR 自动识别
• 智能预警：基于历史数据的异常趋势预测

---

9. 分期建议

V1.1（建议优先）

1. 血透专科数据模型（3 张新表 + API）
2. 患者端小程序改造（TabBar + 首页 + 上报扩展）
3. 积分商城后端 + 小程序前端
4. 线下活动管理

V1.2

1. 在线咨询（轮询版）
2. 化验报告上传 + 审阅流程
3. PC 管理后台新增页面
4. 统计报表

V2

1. 医护端小程序
2. 在线咨询升级（WebSocket + 语音）
3. AI 分析增强（LLM + OCR）
4. Redis 缓存层

---

10. 风险与缓解

风险	影响	缓解措施
积分 FIFO 结算复杂度	并发消费时积分桶冲突	使用数据库事务 + 乐观锁（account.version）
在线咨询工作量超预期	V1.2 延期	V1 先做轮询图文，WebSocket 推迟到 V2
医护端小程序工作量大	V2 延期	V1 阶段用 PC 后台替代医护端功能
化验单 OCR 准确率	用户体验差	V1 先做手动填写，OCR 作为 V2 AI 增量
积分通胀	积分价值稀释	可配置每日上限 + 过期机制 + 运营调整积分价格