docs: 新增厂家联调清单(docs/06)

可直接发对接人的索要清单,分 A 凭据/环境、B 契约补漏、C 业务规则、
D 真实样本、E 联调支持五组,带回填状态;含 OSI 内网 host + SOCKS5
代理地址、签名校验样例、checkId/完整度等关键确认项。同步 docs/README 索引。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ila
2026-05-30 16:00:48 +08:00
co-authored by Claude Opus 4.8
parent 4594f02378
commit 1fd256993b
2 changed files with 73 additions and 0 deletions
+72
View File
@@ -0,0 +1,72 @@
# 06 · 厂家联调清单
向厂家(和宇健康科技)索要的对接数据与待确认项。**A 组是能发出第一个请求的最小集;C/D 组决定能不能做对。**
每项带「状态」便于回填:`待要 / 已要 / 已回 / 已确认`。回填后据此校准 `docs/01`(接口规范)与 `docs/04`(字段映射)。
> 用法:把 A~E 直接发给对接人;回填厂家答复到「厂家答复」列;确认无误后更新对应设计文档并勾掉。
---
## A. 接入凭据与环境(最高优先级)
没有这些,一个请求都发不出。
| # | 需要的数据 | 说明 / 对应文档 | 状态 | 厂家答复 |
|---|---|---|---|---|
| A1 | 沙箱/测试环境 OSI 主机地址 | 接口里的 `${hostname}`(内网地址,不可直连) | 待要 | |
| A2 | **SOCKS5 代理地址** | 到达 A1 内网主机的唯一通路(host+proxy 组合,参照 chis_upload 的 `172.29.20.71:9002` + 代理 `192.168.3.148:11003`) | 待要 | |
| A3 | `orgCode` | 机构编码(机构社会统一信用代码) | 待要 | |
| A4 | `userName` | 平台分配用户名(同报文 `DSFMC` 第三方公司编码) | 待要 | |
| A5 | `ask` 密钥 | 仅用于签名 `password=md5("ts=<ts>&ask=<ask>")`,**敏感、走环境变量不入库** | 待要 | |
| A6 | `deviceSN` 取值规则 | 设备序列号——一机构一值?一设备一值? | 待要 | |
| A7 | `operateUser` / `manaDoctorId` | 默认责任医生 ID(创建类必填) | 待要 | |
| A8 | `manaUnitId` / `operateUnit` | 管辖/操作机构编码(创建类必填) | 待要 | |
| A9 | **签名校验样例** | 给一组 `ts` 与对应正确的 `password`,用来逐字节校验我方 MD5 实现与平台一致 | 待要 | |
| A10 | 生产环境地址+凭据 | 可后置,先拿沙箱 | 待要 | |
## B. 接口契约补漏(docx 缺漏/坑点,见 docs/01 §7、docs/03 §8)
| # | 需要确认 | 状态 | 厂家答复 |
|---|---|---|---|
| B1 | 缺失的**列表/查询接口路径 + serviceId**:档案列表查询、老年人自理评估「列表」与「查询」、中医体质辨识「列表」、中医健康指导「列表」与「查询」 | 待要 | |
| B2 | **中医健康指导 zyjkzd** 的 serviceId + 完整字段表 | 待要 | |
| B3 | 确认 `jkda/find` 的 serviceId 是否为 `JKDA00002`(docx 样例误写成 `TNB00004`) | 待要 | |
| B4 | 老年人自理/体质**查询**的 serviceId(我方推断 `LNRZLPG00002`/`LNRZYTZ00002`) | 待要 | |
| B5 | 体检 `jktj/create` 的**完整字段表**(hcData/lsData/exaData/aeData,体量最大) | 待要 | |
| B6 | 字段名/类型不一致点核对:`jzsfqn` vs `jzsfq`、`addressNumber` vs `adressNumber`、`familyMiddle`/`pastHistory` 是 object 还是 list | 待要 | |
## C. 业务规则确认(决定关键设计)
| # | 需要确认 | 影响 | 状态 | 厂家答复 |
|---|---|---|---|---|
| C1 | **checkId 规则**:长度上限、是否要求全局唯一、平台是否以 checkId 去重、同一 checkId 再次 create 是更新还是报错、create/update 幂等语义 | 幂等键设计(docs/04 §5) | 待要 | |
| C2 | **完整度**:`completeLevel`/`perfection` 由平台计算还是接入方上送?除 `isFillShhj` 外是否还需完整度入参 | 是否移植旧项目完整度逻辑(docs/03 §8-1) | 待要 | |
| C3 | **错误码字典**:除 `1`(成功)/`405`(超时) 外的失败码清单 | 重试分类(docs/04 §6) | 待要 | |
| C4 | **官方码表**:民族 56 项、行政区划/网格代码、医保支付方式等是否有官方完整版下发 | 字典层(docs/04 §3) | 待要 | |
| C5 | 各创建接口的**必填字段最终口径**(以平台实际校验为准) | 映射校验 | 待要 | |
## D. 真实样本(校准字段映射,避免照 docx 猜)
| # | 需要的样本 | 状态 | 厂家答复 |
|---|---|---|---|
| D1 | 每个 **create 接口**一组真实成功的请求 JSON + 响应 JSON | 待要 | |
| D2 | 各查询/列表接口一组真实响应样本(data 是数组还是对象、分页结构) | 待要 | |
| D3 | 一个**测试身份证/测试档案**,联调用、不污染生产数据 | 待要 | |
## 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` 开放问题结论。
+1
View File
@@ -22,6 +22,7 @@
| [03-目标架构设计.md](03-目标架构设计.md) | `chis_osi` 的整体架构、分层、目录结构、数据流与时序、关键设计决策 | | [03-目标架构设计.md](03-目标架构设计.md) | `chis_osi` 的整体架构、分层、目录结构、数据流与时序、关键设计决策 |
| [04-字段与接口映射.md](04-字段与接口映射.md) | OSI 接口↔内部能力映射、PHIS→OSI 字段/字典映射策略、checkId 幂等键 | | [04-字段与接口映射.md](04-字段与接口映射.md) | OSI 接口↔内部能力映射、PHIS→OSI 字段/字典映射策略、checkId 幂等键 |
| [05-实施路线图.md](05-实施路线图.md) | 分阶段落地计划、配置项、可观测性、测试与联调清单 | | [05-实施路线图.md](05-实施路线图.md) | 分阶段落地计划、配置项、可观测性、测试与联调清单 |
| [06-厂家联调清单.md](06-厂家联调清单.md) | 向厂家索要的凭据/环境/契约/样本清单,带回填状态,可直接发对接人 |
## 一句话结论 ## 一句话结论