江西体科所 InBody 数据中心接入与体重管理实施方案

1. 评审结论

方案已在 datacenter 与 kxxl 当前任务分支完成实现，并通过 PHP 5.6、前端构建和开发数据库端到端自测。

InBody770 已经完成设备对接。本次不重新设计设备协议、请求格式、鉴权、重试或脱敏规则，只增加江西项目的业务处理分支。

实现口径：USER_ID = staff.id；使用开发环境；设备数据优先；同日多测沿用现状；权限继续使用后台配置；kxxl 一期不展示报告图片。

2. 已确认事实

3. 系统边界

3.1 本期范围

• InBody 设备通过 datacenter 查询江西运动员。
• datacenter 接收并保存完整 InBody 测试结果。
• datacenter 将完整结果同步到 kxxl 设备结果表。
• datacenter 将体重管理所需核心指标投影到 ydy_body_composition。
• kxxl 根据最新体成分记录更新 ydy_staff.weight、weight_date。
• kxxl 现有体重管理页面显示、维护、筛选和导出设备数据。
• kxxl“综合管理 → 组织结构”列表展示人员 ID，方便客户在 InBody 设备中录入 USER_ID。
• 组织结构导出文件同步包含人员 ID。
• 保持现有重复上传、历史补传和失败处理行为。
• 对 datacenter 已接入客户执行回归，证明行为未改变。

3.2 本期非目标

• 不重构 datacenter 所有设备接入框架。
• 不迁移广东体科所完整设备报告、预约、统计和分析模块。
• 不修改既有客户的商户配置、接口路径、响应格式或人员匹配规则。
• 不在 kxxl 体重管理页面展示 InBody 报告图片。
• 不在本方案中执行生产部署或生产数据库写入。

4. 目标架构

InBody 设备
    │
    ├─ 查询人员
    ▼
datacenter /jxtks/Inbody770/*
    │
    ├─ 保存完整原始指标
    │    ├─ datacenter.equipment_result
    │    └─ datacenter.equipment_result_extend
    │
    ├─ 同步江西业务设备数据
    │    ├─ kxxl.equipment_result
    │    └─ kxxl.equipment_result_extend
    │
    └─ 投影体重管理数据
         ├─ kxxl.body_composition
         └─ 更新 kxxl.staff.weight / weight_date
                    │
                    ▼
          机能监控 → 体重管理页面

数据职责：

• equipment_result*：完整设备原始数据真源。
• body_composition：体重管理页面的业务投影。
• staff.weight/weight_date：人员最新体重摘要。
• 体重管理页面不得直接解析 k1～k225。

5. 主流程

1. InBody 使用 USER_ID 调用 /jxtks/Inbody770/getUserInfo。
2. datacenter 只在江西适配器中匹配有效运动员，并返回设备所需人员资料。
3. 设备完成测试，调用 /jxtks/Inbody770/setInbodyData 上传测试时间与指标。
4. datacenter 校验必填字段、时间、类型、范围、商户和设备。
5. datacenter 按现有 InBody770 行为新增中央设备结果记录。
6. datacenter 在 kxxl 业务库事务中写入 equipment_result 与 equipment_result_extend，成功后立即提交设备数据。
7. 设备数据提交后，独立写入或更新 body_composition。
8. 体重投影成功后，独立更新 staff.weight、weight_date。
9. 接口以设备数据保存成功为主；体重投影失败不得回滚已经保存的设备数据。
10. 用户进入“机能监控 → 体重管理”，查看趋势、列表和详情。

6. 业务规则

BR-001 人员唯一标识

使用 InBody.USER_ID = ydy_staff.id：不补零、不截断，不使用已确认存在重复的 personnel_umber。

江西按 staff.id 精确查询人员。只要 ID 匹配到人员即可测试，不附加 is_show、is_athlete 或其他状态条件；只有 ID 不存在时返回失败。

BR-002 完整设备数据

每次设备上传都按现有 InBody770 行为完整保存到 datacenter 和 kxxl 的 equipment_result、equipment_result_extend。本次不新增设备结果去重规则；同一报文重传时设备明细仍按现有行为新增，体重管理投影继续按人员和测试日期覆盖当天记录。

BR-003 体重管理指标投影

禁止照搬现有江苏适配中的不兼容字段：

• 不把 PBF 写入江西不存在的 PhFatRate。
• 不把 USER_AGE 当作 BodyAge。
• 不向江西 body_composition 写入不存在的 date、record_time、mineral 等字段。

BR-004 人员最新体重

写入体成分后，必须重新查询该人员 ExamTime 最新记录，再更新 staff.weight、weight_date。历史补传不得把当前体重回退成历史值。

BR-005 同日多次测试

沿用现有处理方式：

• equipment_result* 按精确测试时间保留每次测试。
• body_composition 同一人员同一天保留一条，以当天最新测试覆盖。
• staff 始终取所有体成分记录中测试时间最新的一条。

该规则已由用户确认：江西沿用现有 InBody 体重管理逻辑。

BR-006 组织结构人员 ID 展示与导出

• “综合管理 → 组织结构”列表在现有“编号”列前增加“ID”列。
• 新列取值为 ydy_staff.id，与 InBody 请求中的 USER_ID 完全一致。
• 现有“编号”列及其数据保持不变。
• 组织结构导出文件在现有“编号”列前增加同名“ID”列，值同样取 ydy_staff.id。
• 不修改导入模板和人员编号生成规则。

7. 既有 API（保持不变）

三个接口及其方法、Content-Type、字符集、时间格式、图片、失败响应、重试和鉴权全部保持现状。本次只在接口内部增加江西业务落库逻辑，不改变设备请求与响应。

8. 保存顺序与失败处理

kxxl 业务库只有设备主表和扩展表处于同一事务：

1. equipment_result
2. equipment_result_extend

body_composition 和 staff.weight/weight_date 是设备数据提交后的业务投影，不加入设备数据事务。

处理优先级固定为：datacenter 设备数据 → kxxl 设备数据 → body_composition → staff。设备数据保存成功后，即使体重投影或人员摘要更新失败，也不得删除、回滚或判废设备数据；记录投影失败信息，后续可依据设备结果重新执行投影。

接口设备上传结果以设备数据是否保存成功为准，避免体重管理投影异常导致设备重复上传。

业务接口接收和处理真实原始报文；应用日志不得复制完整图片、身份证、数据库凭据或整份设备报文，只记录排障必需的字段摘要、traceId 和结果 ID。

9. 既有客户零影响

江西逻辑必须仅在 business=jxtks 时生效。在现有 InBody770 处理中增加最小化的江西业务分支，不新增设备接口和设备端配置。

保护规则：

• 不修改旧商户配置。
• 不修改旧接口路径、参数和响应结构。
• 不修改旧客户人员匹配规则。
• 不修改江苏 tnxljstks 现有体成分行为。
• 不修改广东 gdtkskx/gdtkskxdc 设备结果行为。

必须覆盖的旧客户回归：默认人员编号客户、广东体科所、江苏体科所、秦皇岛特殊设备表客户。回归必须使用隔离测试库或固定夹具，不对真实客户库发起写请求。

10. 实施计划

阶段一：datacenter 江西业务适配（已完成）

• 江西专属人员查询。
• 中央设备结果按现有行为写入。
• kxxl 设备结果事务写入。

阶段二：体重管理投影（已完成）

• 核心指标映射。
• body_composition 同日幂等更新。
• staff 最新体重更新。
• 历史补传和投影失败隔离。

阶段三：组织结构人员 ID 展示与导出（已完成）

• 组织结构列表接口返回人员 id。
• 前端列表在“编号”前展示“ID”。
• 导出数据在“编号”前增加人员 ID 列。

阶段四：开发环境验收与旧客户回归（已完成自动化与数据层自测）

• 人员列表、趋势、列表、详情、新增、编辑、导入、导出。
• 检查设备上传后四类江西数据是否一致。
• 验证重复上传、同日两测和历史补传。
• datacenter 既有客户契约与数据库结果回归。

11. 测试与验收

12. 实现与自测结果

代码已落在两个仓库的当前任务分支，未提交、未推送，保留给用户审核。开发环境自测结果：

• InBody770 的 225 条指标映射连续完整，完整测试报文在 datacenter 与 kxxl 均验证为 225/225。
• staff.id 存在时人员查询成功，不存在时返回失败；未附加 is_show、is_athlete 条件。
• 同日两次测试产生两条设备明细，body_composition 保持一条并覆盖为当天最新测试。
• 历史补传没有回退 staff.weight/weight_date，人员摘要仍取所有体重记录中的最新日期。
• 人为制造体重投影失败时，设备结果仍保存且接口返回上传成功；不完整隔离测试数据已软删除。
• kxxl 组织结构列表和导出 ID 静态回归通过，PHP 5.6 语法检查通过。
• kxxl 前端热更新编译与生产构建通过；本地前后端继续运行在 9090/9091。
• 2026-09-17 使用用户提供的 2026-09-09 原始报文复测：双端 224 个已提供映射字段逐项比对均为 0 差异，体重投影 18 项检查为 0 差异，历史体重日期未回退。

详细记录见 jxtks-inbody-self-test-20260916.md。

真实联调使用真实设备请求和真实业务数据，不修改或脱敏接口报文。仅当个人信息或凭据被复制到聊天、文档、截图等外部材料时，才保护该材料中的敏感值；这不属于业务接口处理。

13. 已确认实施口径

• 同意 USER_ID = staff.id，不补零。
• 人员只按 staff.id 精确匹配，不附加状态条件。
• 组织结构列表和导出增加 staff.id，供客户录入设备 USER_ID。
• 同意设备结果按现有 InBody770 行为处理。
• 同意 body_composition 沿用现有同日覆盖逻辑。
• 同意 staff 沿用现有最新体重更新逻辑。
• 设备数据优先提交；body_composition 与 staff 不加入设备数据事务。
• 江西逻辑仅对 business=jxtks 生效，不修改旧客户路径和行为。
• 确认设备失败响应、重试和鉴权沿用现有 InBody770。
• 确认一期不在 kxxl 页面展示报告图片。
• 确认普通用户权限由后台现有勾选功能管理，不纳入本次开发。
• 确认使用开发环境联调，不建设独立 test 环境。
• 真实联调使用原始设备请求，不对接口报文脱敏。

实现与开发环境自测已经完成，下一步由用户审核代码与页面；未执行提交、推送、流水线或生产部署。