chis_osi/docs/06-厂家联调清单.md

# 06 · 厂家联调清单

向厂家（和宇健康科技）索要的对接数据与待确认项。**A 组是能发出第一个请求的最小集；C/D 组决定能不能做对。**
每项带「状态」便于回填：`待要 / 已要 / 已回 / 已确认`。回填后据此校准 `docs/01`（接口规范）与 `docs/04`（字段映射）。

> 用法：把 A~E 直接发给对接人；回填厂家答复到「厂家答复」列；确认无误后更新对应设计文档并勾掉。

---

## ★ 当前批次优先催办（读先行阶段，2026-07-08）

查询链路已打通，接下来"其余业务线查询 + 将来写入"被以下三件卡着，**建议同一封邮件一起催**，避免写入阶段既缺授权又缺规则双重卡壳：

1. **写入授权 + 安全测试档案**（见 D3）——解 T-215（档案 create/update 真实验收）阻塞，进而完成 T-204 真实 curl 验收。
2. **缺失的列表/查询接口 serviceId + 路径**（见 B1、B2、B4）——解 T-304 列表查询、T-303 老年人查询的 serviceId 缺口。
3. **写入业务规则**：checkId 去重语义 + 完整度谁算（见 C1、C2）——写入阶段前置，现在问以免后置返工。

---

## A. 接入凭据与环境（最高优先级）

没有这些，一个请求都发不出。

| # | 需要的数据 | 说明 / 对应文档 | 状态 | 厂家答复 |
|---|---|---|---|---|
| A1 | 沙箱/测试环境 OSI 主机地址 | 接口里的 `${hostname}`（内网地址，不可直连） | 已确认 | 见本地 `docs/账号.txt`（不入库） |
| A2 | **SOCKS5 代理地址** | 到达 A1 内网主机的唯一通路（host+proxy 组合，参照 chis_upload 的 `172.29.20.71:9002` + 代理 `192.168.3.148:11003`） | 已确认 | 见本地 `config.yaml` `socks5_proxy` |
| A3 | `orgCode` | 机构编码（机构社会统一信用代码） | 已确认 | **18 位统一社会信用代码**；注意≠config 里 9 位 `org_code`(=manaUnitId)，见 docs/01 §3 |
| A4 | `userName` | 平台分配用户名（同报文 `DSFMC` 第三方公司编码） | 已确认 | 见本地 config（= manageInfo.DSFMC） |
| A5 | `ask` 密钥 | 仅用于签名 `password=md5("ts=<ts>&ask=<ask>")`，**敏感、走环境变量不入库** | 已确认 | 在本地 `config.yaml`（敏感不展示） |
| A6 | `deviceSN` 取值规则 | 设备序列号——一机构一值？一设备一值？ | 部分 | 查询实测**可空**；创建/更新是否必填仍待确认 |
| A7 | `operateUser` / `manaDoctorId` | 默认责任医生 ID（创建类必填） | 部分 | 查询用 operateUser 已确认（见本地 config）；创建的 manaDoctorId 口径待联调 |
| A8 | `manaUnitId` / `operateUnit` | 管辖/操作机构编码（创建类必填） | 部分 | `operateUnit`=orgCode(18位) 已确认；数据侧 `manaUnitId`(9位) 见响应样本 docs/04 §8 |
| A9 | **签名校验样例** | 给一组 `ts` 与对应正确的 `password`，用来逐字节校验我方 MD5 实现与平台一致 | 已确认 | JKDA00002 已打通 → 我方 MD5 头签名实现与平台一致 |
| A10 | 生产环境地址+凭据 | 可后置，先拿沙箱 | 待要 | |

## B. 接口契约补漏（docx 缺漏/坑点，见 docs/01 §7、docs/03 §8）

| # | 需要确认 | 状态 | 厂家答复 |
|---|---|---|---|
| B1 | 缺失的**列表/查询接口路径 + serviceId**：档案列表查询、老年人自理评估「列表」、中医体质辨识「列表」、中医健康指导「列表」与「查询」 | 部分 | 自理评估「查询」已收到独立文档：`/auto/lnr/query` + `LNRZLPG00002`，待真实联调确认 |
| B2 | **中医健康指导 zyjkzd** 的 serviceId + 完整字段表 | 待要 | |
| B3 | 确认 `jkda/find` 的 serviceId 是否为 `JKDA00002`（docx 样例误写成 `TNB00004`） | 已确认 | ✅联调实测 `JKDA00002` 正确 |
| B4 | 老年人自理/体质**查询**的 serviceId（我方推断 `LNRZLPG00002`/`LNRZYTZ00002`） | 部分 | 自理查询文档给出 `LNRZLPG00002`，仍需真实请求确认；体质查询仍待厂家提供 |
| B5 | 体检 `jktj/create` 的**完整字段表**（hcData/lsData/exaData/aeData，体量最大） | 待要 | |
| B6 | 字段名/类型不一致点核对：`jzsfqn` vs `jzsfq`、`addressNumber` vs `adressNumber`、`familyMiddle`/`pastHistory` 是 object 还是 list | 部分 | JKDA00002 **响应**侧确认：`adressNumber`(缺 d)、`pastHistory`/`familyMiddle`=object（docs/04 §8）；创建**入参**拼写仍待核 |

## C. 业务规则确认（决定关键设计）

| # | 需要确认 | 影响 | 状态 | 厂家答复 |
|---|---|---|---|---|
| C1 | **checkId 规则**：长度上限、是否要求全局唯一、平台是否以 checkId 去重、同一 checkId 再次 create 是更新还是报错、create/update 幂等语义 | 幂等键设计（docs/04 §5） | 待要 | |
| C2 | **完整度**：`completeLevel`/`perfection` 由平台计算还是接入方上送？除 `isFillShhj` 外是否还需完整度入参 | 是否移植旧项目完整度逻辑（docs/03 §8-1） | 待要 | |
| C3 | **错误码字典**：除成功/`405`(超时) 外的失败码清单 | 重试分类（docs/04 §6） | 部分 | ⚠成功码实测为 `"01"` 非 `"1"`（docs/01 §1）；完整失败码字典仍待要 |
| C4 | **官方码表**：民族 56 项、行政区划/网格代码、医保支付方式等是否有官方完整版下发 | 字典层（docs/04 §3） | 待要 | |
| C5 | 各创建接口的**必填字段最终口径**（以平台实际校验为准） | 映射校验 | 待要 | |

## D. 真实样本（校准字段映射，避免照 docx 猜）

| # | 需要的样本 | 状态 | 厂家答复 |
|---|---|---|---|
| D1 | 每个 **create 接口**一组真实成功的请求 JSON + 响应 JSON | 待要 | |
| D2 | 各查询/列表接口一组真实响应样本（data 是数组还是对象、分页结构） | 部分 | JKDA00002 已获（`data` 为数组，结构见 docs/04 §8）；其余接口仍待要 |
| D3 | 一个**测试身份证/测试档案**，联调用、不污染生产数据 | 已回 | 已有可查档案（本地样本，含 PII 不入库） |

## E. 联调支持

| # | 需要 | 状态 | 厂家答复 |
|---|---|---|---|
| E1 | 对接技术人联系方式 / 对接群 | 待要 | |
| E2 | 平台侧**失败日志查询方式**（请求失败时能否提供 trace 协助排查） | 待要 | |
| E3 | 网络/白名单：接入方出口 IP 是否需在平台报备开通 | 待要 | |

---

## 回填驱动的后续动作

- A 组齐 → 可做阶段 0 验收（用机构查询 CXJG00002 打通真实请求，见 docs/05）。
- B 组回 → 更新 `docs/01` §5 serviceId 映射表、`osi/codes.go` 常量与 `pathOf` 路由。
- C1/C2 定论 → 定型 `mapping/checkid.go` 幂等策略、决定是否移植完整度逻辑。
- C4/D1 回 → 校准 `docs/04` 码表与字段映射，补 `mapping/*` 单测基线。
- D3 到位 → 端到端联调，回写 `docs/03 §8` 开放问题结论。