哈尔滨膳质舍上禾体检一体机对接方案
手机号确认会员关系，设备测量完成后主动上传；Token 与无 Token 两种模式统一兼容。
1. 方案结论
设备不建会员档案，用户测量前输入手机号，设备把手机号放入 V3.06 协议的 userID，测量完成后主动上传。康比特只使用标准化手机号匹配会员；deviceNo 只用于设备鉴权、来源记录和项目归属，不参与会员身份匹配。
Token 模式
设备先获取访问令牌，上传时携带 X-Access-Token。
无 Token 模式
设备不取令牌，直接上传；仅对明确配置为 NONE 的登记设备开放。
关键规则：两种模式共用结果接口，但由设备档案固定选择；无效或缺失 Token 不得自动降级。
2. 已确认事实与边界
已确认
- 设备不建立会员档案。
- 用户输入11位手机号，作为
userID。 - 上传地址配置在设备端。
- 测量完成后设备主动上传。
- 访问令牌可选，两种模式都要兼容。
recordNo为测量唯一编号。
V3.06技术口径
datas[]兼容单条和多条。- 网络恢复后补传失败报告整体数据。
- 整体数据包含已经上传的字段。
- 同一报告复用session并合并指标。
- V3.06字段全部接收并写raw。
匹配与处理边界
- 不以姓名、性别、年龄做自动会员匹配。
- 不把手机号作为会员主键。
- 不因会员未匹配而拒绝已可靠接收的结果。
3. 总体流程
↓
deviceNo 完成设备鉴权 → 幂等判断 → 手机号匹配
↓
同一请求和事务内直接写原始报文、测量会话、健康指标 → 返回结果
4. 双模式兼容设计
设备档案
| 字段 | 说明 |
|---|---|
device_no | 设备编号 |
store_id | 所属商城/租户，必须与回调域名上下文一致 |
auth_mode | TOKEN 或 NONE |
app_id / app_secret_hash | Token 模式凭据 |
status | 设备启停状态 |
Token 模式
POST /openapi/v1/shanghe/token获取令牌。- Token 绑定设备并设置有效期。
- 缺失或失效返回
2001。 - Token 与设备不一致返回
1000。 - 绝不自动降级。
无 Token 模式
- 仅允许
auth_mode=NONE的登记设备。 - 必须使用 HTTPS。
- 出口 IP 稳定时叠加白名单。
- 未登记或停用设备返回
1000。 - 是兼容能力，不是默认安全推荐。
模式切换
由后台设备档案控制并与现场配置同步；保留变更人、时间和原因。从无 Token 切换到 Token 时先完成取 Token 测试，不在请求处理中自动探测模式。
5. 结果接口与手机号匹配
POST /openapi/v1/shanghe/measurements Content-Type: application/json; charset=utf-8 X-Access-Token: 可选，仅 Token 模式必填
协议指标多为字符串，且可能为空或不传。接入层先保留原始值，再按指标定义转换，不能因某个选配字段缺失拒绝整批报文。
匹配键
normalized_mobile
会员身份只按标准化手机号查询。deviceNo、tenant_id、org_id 只作为设备鉴权、数据来源和项目归属信息保存，不能参与会员匹配。手机号去空格、短横线及可识别的中国国家码，保留字符串并在日志中脱敏。
| 匹配结果 | 处理 |
|---|---|
| 唯一有效会员 | 写有效会话、raw、健康指标和体重业务 |
| 没有会员 | 写 ai_user_id=0、is_valid=0 无效会话和raw |
| 多个会员 | 写无效会话和raw，禁止自动归属 |
| 手机号无效 | 写无效会话和raw |
| 会员已停用 | 写无效会话和raw |
身份边界：这是用户声明手机号，不是短信验证或实名验证；不能仅凭这次关联自动执行高风险医疗干预。
6. 接收、应答与幂等
接口在同一个请求中完成结构校验、设备鉴权、幂等判断、手机号匹配、原始报文保存、测量会话和健康指标写入。现场通常1条，但服务端必须循环全部 datas[]，不能只处理 datas[0]。
| recode | 场景 |
|---|---|
| 1000 | 设备无权访问、未登记、停用或 Token 与设备不一致 |
| 2000 | 报文已可靠接收，包括会员未匹配但无效会话和raw已保存 |
| 2001 | Token 模式下 Token 缺失或失效 |
| 4000 | JSON 或基础结构错误 |
| 5000 | 无法解析或无法可靠保存 |
报告幂等与补传合并
报告键：vendor=shanghe + device_no + record_no payload摘要：device_no + record_no + 当前measurement完整内容
- 同一报告始终复用同一session。
- 完全相同payload不重复写raw和指标。
- 网络恢复后的整体报告保留新raw快照，已有指标更新、新指标插入。
- 指标按session、metric_code和segment保持唯一。
- 补传继续使用原始测量时间。
同步事务
BEGIN 计算 vendor + raw_hash 并匹配手机号 唯一匹配：写有效会话、raw、批量指标 无法匹配：写 ai_user_id=0、is_valid=0 无效会话和raw COMMIT → 返回 recode=2000
未匹配会话不写健康指标、体重、积分或营养业务。实施前验证目标表允许 ai_user_id=0，且业务查询均过滤 is_valid=1。
单条/多条兼容
datas必须是非空数组，否则返回4000。- 每个元素独立使用自己的记录号、手机号和测量时间，生成独立session和raw。
- raw保存外层设备信息、当前measurement、数组序号和请求摘要。
- 全部成功返回
2000；任一技术失败返回5000。 - 整包重传时，已成功元素按幂等跳过，失败元素重新处理。
7. 数据库存储与对应关系
复用现有统一健康数据模型，不新增专用上传接收表。未匹配原始结果也使用无效会话和raw保存。
| 数据用途 | 表/服务 | 使用方式 |
|---|---|---|
| 手机号匹配会员 | zhct.user | 按标准化手机号查询有效记录，取得 ai_user_id |
| 员工有效性辅助核验 | zhct.staff | 通过 ai_user_id 核验，不参与手机号匹配 |
| 一次完整测量 | ydy_measurement_session | 一条 datas[] 元素生成一个会话；未匹配时 ai_user_id=0、is_valid=0 |
| 厂家原始报文 | ydy_measurement_session_raw | 保存匹配或未匹配的完整原始 JSON |
| 单项健康指标 | ydy_health_record | 只有匹配成功时写入 |
| 指标字典 | ydy_health_metric | 维护编码、名称、单位、类型和分段能力 |
| 体重趋势 | UserWeight 服务 | 只有匹配成功时同步身高、体重、BMI和测量日期 |
| 设备鉴权 | ydy_health_device（按配置需要决定） | 设备、Token模式、凭据摘要和启停状态 |
手机号到健康数据
datas[n].userID（手机号） → zhct.user.mobile → zhct.user.ai_user_id → ydy_measurement_session.ai_user_id → ydy_health_record.ai_user_id + session_id
未命中、重复命中或 ai_user_id 无效时，写无效会话和raw，不能写入其他会员的健康数据。
新增：设备配置表 ydy_health_device
| 字段组 | 字段 | 说明 |
|---|---|---|
| 设备 | vendor, device_no, store_id, mac_addr, device_model | 唯一识别设备并绑定商城 |
| 来源 | unit_no, unit_name | 仅作来源记录 |
| 鉴权 | auth_mode, app_id, app_secret_hash, token_ttl | 兼容 TOKEN/NONE，不保存明文密钥 |
| 控制 | status | 设备启停 |
| 生命周期 | is_delete, create_by, create_time, update_time | 项目标准字段 |
UNIQUE KEY uk_vendor_device (vendor, device_no) KEY idx_status_auth (status, auth_mode)
测量会话写入
ydy_measurement_session 字段 | 写入值 |
|---|---|
ai_user_id | 手机号匹配出的会员ID |
event_type | measurement |
start_time/end_time | 上禾 measureTime |
source_platform/vendor | vendor_api / shanghe |
device_type/device_model | body_scale / deviceModel；沿用现有小程序最新体脂查询条件 |
raw_hash | 设备、记录号和报文摘要组合 |
business_context/is_valid | health / 1 |
全字段接收与核心指标映射
V3.06普通字段完整写raw，核心指标写标准健康记录；wave/ecgImg解码后复用现有Upload服务，按商户设置自动走阿里云OSS或本地存储，数据库和raw保存附件URL、file_id、storage、大小、SHA-256和MIME，不保存大段Base64。
| 上禾字段 | 含义 | 康比特落点 | 单位 |
|---|---|---|---|
height | 身高 | height | cm |
weight | 体重 | weight | kg |
bmi | BMI | bmi | - |
fatRate | 体脂率 | bfp | % |
muscle | 肌肉量 | muscle_mass | kg |
idealWeight | 理想体重 | weight_target | kg |
sbp/dbp/hr | 血压/心率 | 标准健康指标 | mmHg/bpm |
pi | 血氧灌注指数 | perfusion_index | - |
wave/ecgImg | 波形/心电图 | ydy_measurement_asset + yoshop_upload_file | URL |
zwtqq | 坐位体前屈最佳值 | sit_and_reach | cm |
protein 在上禾协议中是“蛋白质量 kg”，不能误写到现有表示百分比的 protein 指标，应使用 protein_mass。
正常范围、状态和分段
数值字段写 ydy_health_record.value；_n 正常范围与 _s 原始状态先完整保存在 raw 表。统一状态转换为 LOW/NORMAL/HIGH/ABNORMAL/UNKNOWN，血氧等专用枚举按指标单独配置。
| 分段字段 | metric_code | segment |
|---|---|---|
fatTrunk / fatLeftArm / fatRightArm / fatLeftLeg / fatRightLeg | bodyfat_mass | trunk / left_arm / right_arm / left_leg / right_leg |
muscleTrunk / muscleLeftArm / muscleRightArm / muscleLeftLeg / muscleRightLeg | muscle_mass | 对应部位 |
上述部位的 *Rate | bfp 或 muscle | 对应部位 |
小程序读取
- 按
measureTime日期写yoshop_user_weight：无则新增、有则更新，只允许实际测量时间较新的记录更新当日体重。 - 最新测量同步更新员工档案身高体重和智慧餐厅员工；旧补传不覆盖当前值。
- 上禾计入每日首次体重积分，同日任何来源已加分时不重复。
- 当天最新测量刷新推荐能量；历史补传不刷新今天推荐能量。
- 会话使用
device_type=body_scale，所有厂家统一按实际测量时间取最新。 - 附属业务失败不影响已保存成功的统一体测会话和指标。
8. 安全与隐私
设备与接口
- 正式环境只用 HTTPS。
- 密钥不写日志、仓库或明文存储。
- Token 绑定设备并设置有效期。
- 限制报文大小、频率并保留审计。
会员与健康数据
- 手机号使用安全索引并脱敏展示。
- 原始报文受权限控制并设置保留期限。
- 未匹配结果不得写入任何会员健康档案。
- 小程序不返回厂家原始报文。
9. 联调与上线
| 类别 | 必须覆盖 |
|---|---|
| 鉴权 | 合法 Token、缺失/过期 Token、设备不一致、无 Token 登记设备、未登记/停用设备、禁止自动降级 |
| 身份 | 手机号唯一、不存在、重复、无效、不同设备上传同一手机号 |
| 可靠性 | 首次部分数据、网络恢复整体报告、完全重复、单条/多条 datas、延迟和乱序 |
| 数据 | V3.06全部字段raw留存，新增字段及可结构化指标逐项核验 |
- 登记设备、租户、机构和鉴权模式。
- 部署 Token 接口与统一结果接口。
- 分别联调 Token、无 Token。
- 验证手机号匹配和无效会话保存。
- 完成重复、延迟、幂等和单条/多条测试。
- 小范围试运行后正式启用。
10. 请审核的5项决策
- 只以标准化手机号作为会员匹配方式，
deviceNo仅用于鉴权和来源记录。 - 结果接口兼容
TOKEN、NONE，模式由设备档案固定，禁止自动降级。 - 未匹配时写
ai_user_id=0、is_valid=0无效会话和raw，不新增专用接收表。 - 无 Token 模式仅作为兼容能力，正式环境优先 Token。
- 为语义不同或现有字典缺失的指标新增标准编码，禁止错误复用同名指标。
11. 证据状态
直接材料：上禾 V3.06 为当前开发基线，明确网络恢复整体补传，并新增理想体重、灌注指数、容积波形和坐位体前屈。现有代码已验证会员和统一健康业务复用路径。
数据库门禁：隔离环境只读核验发现raw.data为TEXT、会话缺少报告唯一索引、每日体重缺少同日复合唯一约束。正式持久化前必须确认版本SQL并核验无效会话查询边界；不得绕过门禁。
兼容核验：zwtqqs 与示例 zwtqq2/zwtqq3 均需测试，V3.06全字段raw容量和指标upsert必须通过。