智能随访 v10 业务逻辑设计

范围: 业务流程 / 用户角色 / 数据状态机 / 异常处理 / 入组研究协议 配套: ui-prototype-v10.md (UI 设计) + prototype/index.html (可点击原型) 目标: 把"采集设备 + 后端 + 多患者"的隐性逻辑显性化, 实施前对齐医院/课题组/医生认知

1. 角色定义

关键认知: 主要操作者不是患者, 是医护。这决定了 UX 必须照顾"医护流水线"场景 (快速切换患者, 实时看连接状态, 不能丢数据)。

2. 核心场景 (Use Cases)

场景 A: 门诊一次性采集 (单人)

1. 患者 A 进诊室
2. 护士拿出手表给患者戴上 (或患者自己已戴)
3. 护士拿出手机扫体验版二维码进小程序
4. 输入患者 A 的门诊号 100234
5. 点 "设备扫描" → 选 S101 → 连接
6. 让患者按表测血压 (或表自动测心率)
7. 数据自动同步入库
8. 护士看一眼首页 "今日采集" 确认有数据
9. 摘表给下一个患者

难点: 切换到下一患者时, 必须切换门诊号. v9 已解决: 点"切换患者"输新号即可.

场景 B: 病房床旁连续采集 (一台手表 N 个患者)

1. 护士 8:00 巡房, 同一台手表
2. 给患者 B (床位 1, 门诊号 100235): 戴 → 测 → 摘
3. 切换门诊号 100236 → 给患者 C: 戴 → 测 → 摘
4. ... 一轮巡房 8 个患者
5. 最后回护士站把数据汇总查看

难点:

• 中间忘记切换门诊号 → 数据归错患者 (高风险)
• 切换太频繁 → 误操作概率上升 当前防御: 顶部红色警示条 (未输入门诊号时显示) — 但已经输入后无防御. v10 增强建议:
• 给"切换患者"操作加 5 秒计时倒数, 防误触
• 测量前再次确认门诊号 (modal 弹"将记录到 100236, 确认?")
• 历史记录里高亮显示"快速切换"窗口的数据 (10 分钟内切了 3 次以上 → 标橙色警示运营审核)

场景 C: 居家随访 (家属代采集)

1. 患者 D 出院, 表一并带走
2. 家属 (例如妈妈给俩娃) 用自己微信扫码进小程序
3. 输入孩子 A 门诊号 100237 → 测一周
4. 切换孩子 B 门诊号 100238 → 测一周
5. 数据周期性自动同步
6. 医生在后台 (Tab 3 数据视图) 看趋势

难点:

• 家属不专业, 容易忘切门诊号 → 同 B
• 网络环境差 (老家 / 弱网) → 数据可能堆积
• 设备没电 / 没充电 → 测不了 当前防御: pending 队列 + 6 重 flush 触发 (v9 已就绪) v10 增强建议:
• 首页常驻"未上传 X 条"角标 (storage 里 pending 队列长度)
• 网络恢复后弹 toast "已上传 X 条数据"

场景 D: 入组研究 (定期采集 + 协议)

1. 课题组定义研究协议:
   "高血压研究: 每位患者每天 2 次血压 (早 7:00 / 晚 19:00),
    持续 14 天, 完成率 ≥ 80% 算有效样本"
2. 入组 50 位患者, 每人门诊号唯一
3. 系统应能告诉运营:
   - 当前哪些患者按时测了 (今日完成 X/50)
   - 哪些超过 24 小时没测了 (掉队 Y 人)
   - 哪些数据异常 (高血压2级 N 例, 需医生干预)
4. 研究结束后导出整组数据做统计分析

难点:

• 当前小程序完全没有协议感 — 不知道"应该测但没测"
• 数据导出需要按时间窗 + 门诊号 + 指标过滤 v10 关键缺口:
• 缺"采集任务"概念 (今日待办 / 已完成 / 未完成)
• 缺"研究批次"维度 (50 位患者归一组, 一起统计)

3. 数据状态机

3.1 设备连接状态机

                        ┌──────────────┐
                  ╔════►│  未连接       │◄═════╗
                  ║     └──────┬───────┘      ║
                  ║            │              ║ adapter 关 / 用户主动断
                  ║            │ 用户点扫描+选 ║
                  ║            ▼              ║
                  ║     ┌──────────────┐      ║
                  ║     │  连接中       │      ║
                  ║     └──────┬───────┘      ║
                  ║            │              ║
                  ║   12s 超时 │ SDK 回 connection=true
                  ║   /握手失败 │              ║
                  ║            ▼              ║
                  ║     ┌──────────────┐      ║
                  ║     │  握手中       │      ║
                  ║     └──────┬───────┘      ║
                  ║            │              ║
                  ║   5s VPDevice 空 │ type=1 回包 (含 MAC/版本)
                  ║            │              ║
                  ║            ▼              ║
                  ║     ┌──────────────┐      ║
                  ║     │  已连接       │═════╝
                  ║     └──────┬───────┘
                  ║            │ 90s 无回包 (心跳暗断)
                  ║            │ 或 connection=false
                  ║            ▼
                  ║     ┌──────────────┐
                  ╚═════│  暗断/重连中  │
                        └──────────────┘
                          指数退避 1/2/4s 三次
                          失败 → 提示用户手动重连

3.2 数据归属状态机

saveData() 触发
    │
    ▼
┌────────────────────┐
│ 立即写 storage 队列 │ (任何时候都先入队, 防丢数据)
└────────┬───────────┘
         │
         ▼
    deviceId 已知?
    ┌───┴───┐
    │  否    │  是
    ▼       ▼
┌──────┐  ┌──────────────────┐
│ 留   │  │ 立即 POST /api/    │
│ pending│  │ health-data         │
└──────┘  └────────┬─────────┘
等 type=1     成功? │ 失败?
回包后 flush  ┌──┴──┐
              ▼     ▼
          ┌─────┐ ┌─────────┐
          │ 入库 │ │ 留 pending│
          └─────┘ └────┬────┘
                       │
                  6 重 flush 兜底:
                  - 2h 定时
                  - 23:59 兜底
                  - app.onShow
                  - 网络恢复
                  - BLE 重连
                  - 队列堆 80

3.3 患者归属状态机 (v9 门诊号)

小程序启动
    │
    ▼
读 storage.patientNo
    │
    ▼
patientNo 存在?
    ┌─┴─┐
    否    是
    │     │
    ▼     ▼
首页红警  首页蓝条
"未输入  "当前 100234"
门诊号"
    │     │
    ▼     ▼
点[输入]  点[切换]
    │     │
    └──┬──┘
       ▼
   wx.showModal editable
       │
       ▼
   输入新门诊号 → storage.patientNo = "100235"
       │
       ▼
   后续 saveData payload 带 patientNo: "100235"
       │
       ▼
   服务端 to_chinese_record 写入 record['门诊号']: "100235"

4. 业务规则

4.1 数据归属规则

4.2 异常数据判定规则 (建议在客户端高亮)

当前实施: 服务端 classify_bp 已经做血压风险等级 (写入大 JSON 的 风险等级 字段). 其他指标尚未实施. v10 应补齐.

4.3 入组研究采集规则 (v12 才上, v10 先打基础)

研究协议示例:
  name: "高血压晨晚血压观察"
  duration_days: 14
  daily_tasks:
    - time_window: "07:00-08:30"
      indicator: "bloodPressure"
      times_per_day: 1
      description: "晨起血压"
    - time_window: "19:00-20:30"
      indicator: "bloodPressure"
      times_per_day: 1
      description: "晚间血压"
  completion_threshold: 0.8
  alert_rules:
    - if: "missed_consecutive >= 2"
      action: "通知研究员"
    - if: "高血压2级 数 >= 3 in 7 天"
      action: "通知主治医生"

4.4 数据保留与清理规则

4.5 单台手表多人区分规则

• 首要: 测量前必须先输/切门诊号 (UI 强制)
• 次要 (建议): 在测量页加"将记录到 XXX, 确认?" 二次确认
• 降级: 没输门诊号时数据照常入库 (兼容历史), 但 UI 红色警示

5. 异常处理矩阵

6. 权限与角色矩阵

当前小程序: 无角色概念, 谁拿到二维码谁能用全部功能. v10 不打算实施角色权限 (太重), 仅在 UI 层把"调试"功能折叠到 Tab 4 末尾, 正式版 IS_TEST_BUILD=false 时隐藏即可.

长期方向: 走微信小程序 wx.login 拿 openid → 服务端建用户表 → 角色与权限. 但客户当前不需要, 暂不做.

7. 数据接入与导出对接

7.1 当前已有

• POST /api/health-data (写入)
• GET /api/data (查询全部)
• GET /api/data?patientNo=xxx (按门诊号过滤)
• POST /api/device/register (设备注册)
• POST /api/device/merge (设备合并, 运维用)
• DELETE /api/device/:id (设备删除, 运维用)

7.2 v10 应补齐

7.3 v12+ 路线图 (不在 v10 范围)

• HIS 对接 (医院信息系统集成)
• 入组研究协议引擎 (上面 4.3 那套)
• 医生端 Web 后台 (不用小程序)
• 患者主动测量提醒 (定时推送)

8. 通知与提醒 (v10 仅前端轻量)

9. 关键决策待用户/客户拍板

10. 实施优先级建议

v10 必做 (跟着 4-tab UI 一起)

1. 4-tab 信息架构 (UI)
2. 顶部患者条 + 连接条 (沿用 v10)
3. 异常数据视觉高亮 (血压风险等级渲染颜色)
4. 数据 Tab 趋势图 (ECharts/F2)
5. 数据 Tab CSV 导出
6. 调试入口折叠

v10 增强 (有时间就做)

1. 测量前门诊号二次确认 (5 秒倒计时)
2. 首页 "未上传 X 条" 角标
3. 患者切换历史 (近 5 个门诊号快速切回)
4. 网络恢复 toast "已上传 X 条"

v12 (留作下一版)

1. 患者列表概念 + 增删改
2. 入组研究协议引擎
3. 医生端 Web 后台
4. 角色权限模型
5. HIS 对接