新设备接入手册

读者：医院 PM / 护士 / 项目运营人员。 患者本人请看 医院交付使用指南.md。

本手册说明如何把一只新的 Veepoo 兼容手表绑定到智能随访数据链路。每位新患者入组前按此手册走一遍即可。

1. 适用场景

✅ 适用：

• 新患者入组，需要发表
• 患者原表损坏、更换新表
• 医院入库新型号（同为 Veepoo 协议族）

❌ 不适用：

• 非 Veepoo 厂家的智能手表（Apple Watch / 小米 / 华为 / Garmin / Fitbit 等）
• 患者更换微信号（属于"重新接入"，按本手册全流程重做）

2. 设备硬件要求

为什么只支持 Veepoo 兼容机型：本项目使用 Veepoo 私有 BLE 协议（GATT UUID、密钥认证、字节解码全套都是 Veepoo 定义的）。其他厂家手表协议不通，无法用同一份代码接入。详见 §7。

3. 一次性前置配置（全院共用，已配置请跳过）

这一节只做一次，新患者入组不需要重复做。如果医院 PM 是第一次接手项目，先和工程师确认下面三项是否已就绪。

详细操作步骤：见 4.25plan.md 的 Step 10.1（加合法域名）/ 10.4-10.5（上传 + 设体验版）/ 10.7（导出二维码）。

4. 每位新患者接入 5 步流程

Step 1：收集患者微信号

让患者在微信里告诉你他自己的微信号（不是手机号、不是姓名）：

1. 患者打开微信 → 我 → 头像下方
2. 看到「微信号：xxxxxxx」 → 截图或抄写
3. 发给医院 PM

💡 微信号是字母+数字组成的（如 wxid_a1b2c3 或 lisi_2025）。不是 8 个数字的微信号 = 那是手机号，不能用。

收集模板（医院 PM 在 Excel 维护）：

Step 2：医院 PM 转给工程师 → 加体验成员白名单

⚠️ 这一步只能由 AppID wxbc5453a4c53dbee8 主体的管理员做（普通医院员工没权限）。

1. 医院 PM 把微信号清单发给工程师
2. 工程师登录 https://mp.weixin.qq.com（用管理员微信扫码）
3. 左侧菜单 → 管理 → 成员管理 → 体验成员 标签页
4. 点「+ 添加成员」→ 输入微信号 → 提交
5. 重复直到所有人都加完

完成后：被加的人微信里会收到一条"被添加为体验成员"的消息。

⚠️ 100 人天花板：体验成员（含开发者）总和 ≤ 100。逼近上限时联系工程师评估走正式版。

Step 3：把手表 + 二维码发给患者

发给患者三样东西：

1. 一只已充电的兼容手表
2. 医院交付使用指南.md 的 PDF 版（已嵌入二维码）
3. 一句话提醒：「微信扫这张码就能用，蓝牙记得打开」

Step 4：患者自己完成绑定（约 3 分钟）

患者按 医院交付使用指南.md 操作：

1. 微信扫体验版二维码 → 进入小程序
2. 首页右上角看到橙色「测试版」字样 = 进对了
3. 点「设备扫描」→ 列表里选自己的表
4. 等约 5-10 秒「连接成功」

期望结果：小程序自动调 POST /api/device/register → 六元 MySQL 的 wearable_device 表新增一行 → 拿到 deviceId。这一切对患者透明。

如果患者卡住 → 看 §6 故障排查。

Step 5：通知六元 / 医生端建立绑定关系

患者首次连接成功后，告诉六元/医生端该患者的：

• 受试者编号（医院给的，如 2026-001）
• 设备 sign（去六元 wearable_device 表查最新的一行，或工程师 vConsole 里看）
• deviceId

这一步不归本仓代码，由六元产品方在 patients 表手工 INSERT 一行（绑定关系）。详见 4.25plan.md 「不在本次范围」段。

5. 验证接入成功

接入完成后，让患者测一组心率，预期：

任何一条不过都不算成功接入。在 §6 自助排查；解决不了找工程师。

6. 常见故障排查

6.1 患者扫码进不去（提示"未授权，请联系开发者"）

原因：微信号没加白名单，或加错了。 解决：

1. 让患者截图错误页给你
2. 核对 Excel 里的微信号 vs 患者实际微信号（区分大小写、容易把 0 / O 看错）
3. 在 mp.weixin 后台搜该微信号是否在体验成员列表里
4. 不在 → 重新加；在但还是进不去 → 让患者退出微信重启再扫

6.2 列表里看不到我的表

逐项排查：

• 手表充电了吗？看屏幕有没有显示时间
• 手表是否被其他设备占用？关掉其他设备的蓝牙
• 手机蓝牙开了吗？
• 手机定位权限给微信了吗？（Android：BLE 扫描在微信上强制要求定位权限）
• 手表型号对吗？设备名必须以 VP- / S101 / VPR 开头
• 距离够近吗？把手表凑到手机 30 cm 内

6.3 连接成功但数据没传上去

vConsole 排查（让工程师远程看）：

• 看到 register 调用失败 → 服务端 dc.ncrc.org.cn 不通（看 §6.4）
• 看到 register 返回无 deviceId → 服务端 wearable_device 表写入失败，工程师介入
• 看到 HTTP同步...失败入队待补传 → 患者侧网络问题，让他换 WiFi 或 4G 重试；数据已在本地缓存，不会丢，下次有网自动补传

6.4 vConsole 报 request:fail url not in domain list

原因：合法域名没配置（§3.1 漏了） 解决：工程师按 §3.1 / 4.25plan.md Step 10.1 配置后，让患者重新扫码进入

6.5 100 人体验版上限快满了

当前数量：mp.weixin 后台 → 成员管理 → 体验成员 → 列表底部显示总数 逼近上限的处理：

1. 提前 1 个月联系工程师评估走正式版
2. 正式版需要：隐私协议页 + 医疗免责 + 微信审核（1-7 天）+ 可能需要药监器械证
3. 临时方案：删除已离组的患者微信号腾位置（mp.weixin → 体验成员 → 移除）

7. 为什么必须是 Veepoo 兼容机型

整个数据链路从 BLE 协议层就是Veepoo 私有的：

S101 之所以能用，是因为它不是 Veepoo 自牌但运行 Veepoo 兼容固件——这种兼容机型可以直接接。

7.1 如果将来 Veepoo 发了新机型（比如 VPS200）

通知工程师改 services/env.ts 一行即可：

SUPPORTED_DEVICE_PREFIXES: ['VP-', 'S101', 'VPR', 'VPS'],  // ← 加新前缀

其他代码、API、数据库都不变。约 30 分钟工作量。

7.2 如果医院想接入非 Veepoo 厂家手表

工程师评估约 3-6 周工作量：

• 重写 miniprogram/miniprogram_dist/ SDK 部分
• 该厂家的密钥认证流程
• dataStorage 字段映射
• 服务端 TYPE_TO_CHINESE / toChineseRecord 适配新字节格式
• 需要新厂家提供完整 SDK 文档

不是一两行代码改完的事，预算评估请提前 1 个月报。

8. 联系方式

9. 相关文档

• 医院交付使用指南.md — 给患者本人看的（怎么扫码、连蓝牙、故障排查）
• 4.25plan.md — 完整开发交付规划，含 Step 10 微信发布 SOP 全套
• 真机测试checklist.md — 17 步真机端到端验证（工程师用）
• code/demo/WeiXinSDKTSDemo/miniprogram/services/env.ts — 体验版/正式版开关 + 设备白名单单一来源
• code/demo/WeiXinSDKTSDemo/miniprogram/services/dataStorage.ts — 数据上传 + 断网重传 + 动态 deviceId 解析

本手册由开发团队维护。本文档版本：v1（2026-04-26）。如发现错误或不清楚的地方请反馈给工程师。