nc/chis_osi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 依 JKDA00002 联调实测校准接口契约

Browse Source 
- 成功码实测为字符串 "01"（docx 误写 "1"），判定按去前导零
- 查询类同走 uploadinfo 信封（baseInfo+manageInfo），非裸 baseInfo
- 三种机构码分层：18位统信码 / 9位机构码 / 12位区划码
- docs/04 新增 §8 JKDA00002 实测契约（请求信封+响应结构，已脱敏）
- docs/06 回填 A1~A9/B3/B6/C3/D2/D3 联调状态

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ila
2026-07-06 20:09:43 +08:00
co-authored by Claude Opus 4.8
parent 1fd256993b
commit d7b769742b
4 changed files with 108 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-OSI接口规范分析.md
+29 -24
View File
@@ -13,14 +13,15 @@
| 通用 URL | `http://${hostname}/osi/api/...`（各接口在此基础上拼子路径） | | 通用 URL | `http://${hostname}/osi/api/...`（各接口在此基础上拼子路径） |
| 报文格式 | 请求/响应均为 JSON 字符串 | | 报文格式 | 请求/响应均为 JSON 字符串 |
| 字符集 | UTF-8 | | 字符集 | UTF-8 |
| 返回码 | `code == "1"` 成功；其它值失败；`405` = 服务调用超时 | | 返回码 | 成功码 `code`（字符串）；其它值失败；`405` = 服务调用超时 |
> 注意：返回码 `code` 是**字符串** `"1"`，不是数字 `1`；判定成功务必按字符串比较或归一化处理。 > **联调实测（2026-07，JKDA00002）**：成功返回 `code="01"`、`message="操作成功"`，而非早期依 docx 整理的 `"1"`。
> `code` 是**字符串**，落地判定成功建议按「去前导零后 == `"1"`」或落入集合 `{"1","01"}`，不要用数字比较；`405` 仍为服务调用超时（可重试）。其余失败码字典待厂家给全（见 docs/06 C3）。
### 1.1 响应统一结构 ### 1.1 响应统一结构
```json ```json
{ "code": "1", "message": "操作成功", "data": { ... } } { "code": "01", "message": "操作成功", "data": [ ... ] }
``` ```
- `data` 在创建类接口是对象（如 `{ "phrId": "...", "createUnit": "..." }`）； - `data` 在创建类接口是对象（如 `{ "phrId": "...", "createUnit": "..." }`）；
@@ -36,7 +37,7 @@
| --- | --- | | --- | --- |
| `Content-Type` | `application/json` | | `Content-Type` | `application/json` |
| `orgCode` | 机构编码（机构的社会统一信用代码，约 18~20 位）。接入方先把组织/机构信息提供给平台，由平台生成 | | `orgCode` | 机构编码（机构的社会统一信用代码，约 18~20 位）。接入方先把组织/机构信息提供给平台，由平台生成 |
| `deviceSN` | 设备序列号（创建/更新/查询类接口均要求必填） | | `deviceSN` | 设备序列号。docx 标各类接口必填，但**联调实测** JKDA00002 查询 `deviceSN` 为空仍成功——查询类可空；创建/更新是否必填待联调（docs/06 A6） |
| `ts` | 13 位毫秒级时间戳 | | `ts` | 13 位毫秒级时间戳 |
| `userName` | 平台分配的用户名（对应一个 `ask` 密钥；同时也是报文里的第三方接入公司名称编码 `DSFMC`） | | `userName` | 平台分配的用户名（对应一个 `ask` 密钥；同时也是报文里的第三方接入公司名称编码 `DSFMC`） |
| `password` | `md5("ts=<时间戳>&ask=<密钥>")`，取 **32 位小写** | | `password` | `md5("ts=<时间戳>&ask=<密钥>")`，取 **32 位小写** |
@@ -53,28 +54,31 @@
## 3. 请求报文信封 ## 3. 请求报文信封
请求体（HTTP body）统一为： **联调实测**：请求体统一为 `serviceId` + `uploadinfo` 两段，**查询类同样走 `uploadinfo` 信封**（早期依 docx 猜测查询发裸 `baseInfo`，实测不成立）：
```json ```json
{ {
"serviceId": "<固定服务码>", "serviceId": "<固定服务码>",
"uploadinfo": { ... } // 创建/更新类：写入数据 "uploadinfo": {
} "baseInfo": { ... }, // 查询：查询条件；创建：人口学主键等
``` "manageInfo": { ... }, // 管理节点，查询与创建都要带
或查询类： "...": { ... } // 创建/更新再加 healthRecord / pastHistory / jwsjb … 业务节点
```json }
{
"serviceId": "<固定服务码>",
"baseInfo": { ... } // 查询条件
} }
``` ```
- `serviceId` 是每个接口的**固定常量**（见第 5 节映射表），平台据此路由业务。 - `serviceId` 是每个接口的**固定常量**（见第 5 节映射表），平台据此路由业务。
- 创建/更新类信封内含 `manageInfo`（管理节点）+ 业务数据节点： - `manageInfo` 三字段（JKDA00002 查询实测携带即成功，是否可省未验证）：
- `manageInfo.DSFMC` = 第三方接入公司名称编码（与请求头 `userName` 一致） - `DSFMC` = 第三方接入公司名称编码（= 请求头 `userName`）
- `manageInfo.operateUnit` = 操作机构编码（与请求头 `orgCode` 一致） - `operateUnit` = 操作机构编码（= 请求头 `orgCode`）
- `manageInfo.operateUser` = 责任医生 ID - `operateUser` = 操作用户 / 责任医生 ID
- 文档中创建样例外层出现的 `"headers": {...}` 仅用于演示 HTTP 头，**不是 body 的一部分**；实际 POST body 只发 `serviceId`+数据节点。 - 文档中创建样例外层出现的 `"headers": {...}` 仅用于演示 HTTP 头，**不是 body 的一部分**。
> **三种机构相关编码分属不同层级，切勿混用**（实测确认）：
> - 请求头 `orgCode` / `manageInfo.operateUnit`：**18 位统一社会信用代码**（如 `12…G`），是接入机构的鉴权身份。
> - 记录内 `manaUnitId` / `createUnit`：**9 位机构编码**，落在档案数据上。
> - `regionCode` / `addressCode`：**12 位行政区划/网格码**。
> 注意：`config.yaml` 里的 `org_code`（9 位）其实是 `manaUnitId`，**不是**请求头 `orgCode`；请求头 orgCode 需用 18 位码，两者不要填反。
--- ---
@@ -119,7 +123,7 @@
| 业务 | 路径 | serviceId | 主数据节点 | | 业务 | 路径 | serviceId | 主数据节点 |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| 创建 | `/osi/api/jkda/create` | `JKDA00001` | `uploadinfo.healthRecord` + `pastHistory`/`jwsjb`/`jwsss`/`jwsws`/`jwssx`/`familyMiddle` | | 创建 | `/osi/api/jkda/create` | `JKDA00001` | `uploadinfo.healthRecord` + `pastHistory`/`jwsjb`/`jwsss`/`jwsws`/`jwssx`/`familyMiddle` |
| 查询 | `/osi/api/auto/jkda/find` | `JKDA00002` ⚠ 文档样例误写 `TNB00004` | `baseInfo`(idCard/phrid/personName 三选一) | | 查询 | `/osi/api/auto/jkda/find` | `JKDA00002` ✅联调确认（docx 样例误写 `TNB00004`） | `uploadinfo.baseInfo`(idCard/phrid/personName 三选一) + `manageInfo`；响应见 docs/04 §8 |
| 更新 | `/osi/api/jkda/update` | `JKDA00003` | 同创建 | | 更新 | `/osi/api/jkda/update` | `JKDA00003` | 同创建 |
| 人群/子档案标记查询 | `/osi/api/jkda/findrqbj` | `JKDA00005` | `baseInfo`(phrid/idCard 二选一) → `data.personSign` | | 人群/子档案标记查询 | `/osi/api/jkda/findrqbj` | `JKDA00005` | `baseInfo`(phrid/idCard 二选一) → `data.personSign` |
| 列表查询 | （清单第 1 项，文档正文未见独立路径，疑与 `find` 合并或缺漏） | 待确认 | — | | 列表查询 | （清单第 1 项，文档正文未见独立路径，疑与 `find` 合并或缺漏） | 待确认 | — |
@@ -189,11 +193,12 @@
官方 docx 存在明显的复制粘贴/排版错误，建模前需逐一核对： 官方 docx 存在明显的复制粘贴/排版错误，建模前需逐一核对：
1. **serviceId 串台**：`jkda/find` 的请求样例里 serviceId 写成 `TNB00004`（糖尿病接口的码），实际应为 `JKDA00002`。 1. **serviceId 串台**：`jkda/find` 的请求样例里 serviceId 写成 `TNB00004`（糖尿病接口的码），实际应为 `JKDA00002` —— ✅**联调已确认为 `JKDA00002`**。
2. **字段名不一致**：创建档案家族史父亲在字段定义里叫 `jzsfqn`，在请求样例里叫 `jzsfq`；现住址门牌号在创建里 `addressNumber`、在查询里 `adressNumber`（少一个 d）。 2. **字段名不一致**：创建档案家族史父亲在字段定义里叫 `jzsfqn`，在请求样例里叫 `jzsfq`；现住址门牌号在创建里 `addressNumber`、在查询里 `adressNumber`（少一个 d）—— ✅JKDA00002 **响应实测确实返回 `adressNumber`（缺 d）**，响应侧以错拼写为准；创建侧入参拼写仍待联调核对。
3. **类型不一致**：`familyMiddle` 在创建接口标 `object`，在查询接口标 `list`；`pastHistory` 同样在不同接口标注不同。 3. **类型不一致**：`familyMiddle` 在创建接口标 `object`，在查询接口标 `list`；`pastHistory` 同样在不同接口标注不同 —— ✅JKDA00002 **响应实测 `pastHistory`/`familyMiddle` 均为 object**，`jwsjb`/`jwssx`/`jwsss`/`jwsws` 为 array（见 docs/04 §8）。
4. **样例 JSON 非法**：多处查询样例花括号不配对（如 `{ "baseInfo": {...} }, "serviceId": "..." }`），应理解为 `{ "serviceId": "...", "baseInfo": {...} }`。 4. **样例 JSON 非法**：多处查询样例花括号不配对（如 `{ "baseInfo": {...} }, "serviceId": "..." }`）。⚠实测请求信封为 `{ "serviceId": "...", "uploadinfo": { "baseInfo": {...}, "manageInfo": {...} } }`，查询条件包在 `uploadinfo.baseInfo` 内，**不是**外层裸 `baseInfo`。
5. **列表查询路径缺漏**：xlsx 要求"档案列表查询""自理/体质/中医指导列表查询""自理查询"等，但 docx 正文未给出全部独立路径与 serviceId，需向厂家索要补充。 5. **成功码不是 `"1"`**：docx/早期整理写成功 `code="1"`，✅**联调实测为 `code="01"`**（见第 1 节），成功判定需兼容前导零。
6. **列表查询路径缺漏**：xlsx 要求"档案列表查询""自理/体质/中医指导列表查询""自理查询"等，但 docx 正文未给出全部独立路径与 serviceId，需向厂家索要补充。
> 结论：**不能直接照搬 docx 字段表生成契约**。落地前应整理一份「校验后的接口契约」（见 03 文档 `contract/` 包）， > 结论：**不能直接照搬 docx 字段表生成契约**。落地前应整理一份「校验后的接口契约」（见 03 文档 `contract/` 包），
> 并以厂家沙箱环境的真实请求/响应样本做回归校准。 > 并以厂家沙箱环境的真实请求/响应样本做回归校准。
docs/04-字段与接口映射.md
+63 -2
View File
@@ -126,12 +126,14 @@ checkId = 截断20位( 编码( 源系统标识 | dataType | 源记录主键 [ |
## 6. 校验与错误分类（与 pipeline 配合） ## 6. 校验与错误分类（与 pipeline 配合）
> 成功码以 docs/01 §1 为准：实测为字符串 `"01"`（非 `"1"`），判定按去前导零后 == `"1"`。
| 错误来源 | 分类 | 处理 | | 错误来源 | 分类 | 处理 |
| --- | --- | --- | | --- | --- | --- |
| 映射缺必填/码表未命中/格式非法 | 不可重试（数据错） | 直接 failed，回写 PHIS，附 ValidationError 明细 | | 映射缺必填/码表未命中/格式非法 | 不可重试（数据错） | 直接 failed，回写 PHIS，附 ValidationError 明细 |
| 网络错误 / SOCKS / EOF / 超时 | 可重试 | 退避重试，计熔断 | | 网络错误 / SOCKS / EOF / 超时 | 可重试 | 退避重试，计熔断 |
| OSI `code == "405"`（服务超时） | 可重试 | 退避重试 | | OSI `code == "405"`（服务超时） | 可重试 | 退避重试 |
| OSI `code` 非 1 非 405（业务/权限拒绝） | 不可重试 | failed，记 message 供排查 | | OSI `code` 非成功码非 405（业务/权限拒绝） | 不可重试 | failed，记 message 供排查 |
| HTTP 5xx / 429 | 可重试 | 退避重试 | | HTTP 5xx / 429 | 可重试 | 退避重试 |
--- ---
@@ -144,4 +146,63 @@ checkId = 截断20位( 编码( 源系统标识 | dataType | 源记录主键 [ |
- [ ] 老年人自理评估 `lnrzlpg` 字段 - [ ] 老年人自理评估 `lnrzlpg` 字段
- [ ] 中医体质辨识 `lnrzyygl` 字段 - [ ] 中医体质辨识 `lnrzyygl` 字段
- [ ] 中医健康指导 `zyjkzd` 字段 + serviceId - [ ] 中医健康指导 `zyjkzd` 字段 + serviceId
- [ ] 各列表/查询接口的分页与返回数组结构 - [x] 个人档案查询 JKDA00002 的请求信封与返回结构 —— 已联调实测，见 §8
- [ ] 其余列表/查询接口的分页与返回数组结构（体检/老年人/中医指导）
---
## 8. JKDA00002 个人档案查询 · 联调实测契约
> 来源：2026-07 沙箱一次成功查询（`code="01"` 操作成功）。**下方均为脱敏结构**，真实身份证/姓名/联系方式等 PII 只在本地样本，不入库。
> 这是 `contract/` 里 `FindHealthRecord` 请求/响应结构体与 `osi.FindHealthRecord` 的事实基线。
### 8.1 请求（POST `/osi/api/auto/jkda/find`）
```json
{
"serviceId": "JKDA00002",
"uploadinfo": {
"baseInfo": { "idCard": "<idCard>" },
"manageInfo": { "DSFMC": "<userName>", "operateUser": "<operateUser>", "operateUnit": "<orgCode-18位>" }
}
}
```
- `baseInfo` 三选一：`idCard` / `phrid` / `personName`。
- `manageInfo` 三字段来自机构级常量（见 docs/01 §3 三种机构码区分）。
- 请求头另带 `orgCode`(=operateUnit) / `deviceSN`(查询可空) / `ts` / `userName`(=DSFMC) / `password`，签名规则见 docs/01 §2。
### 8.2 响应（`code="01"`，`data` 为**数组**，每元素 = 一份档案聚合）
| 节点 | 类型 | 说明 |
| --- | --- | --- |
| `healthRecord` | object | 档案主体（人口学 + 管理字段），见 8.3 |
| `pastHistory` | object | 既往史**标志位**：`ywgms`(药物过敏)/`jwsjb`标志/`bls`/`ycbs`(遗传病)/`cjqk`(残疾)/`jzsfqn`/`jzsmq`/`jzszn`/`jzsxdjm`(家族史·父/母/子女/兄弟姐妹) 等 code |
| `jwsjb` | array | 既往疾病：`{ jwsjbcode, jwsjbmc, jwsjbqzsj(确诊时间) }` |
| `jwsss` | array | 既往手术：`{ jwssscode, jwsssmc, jwsssqzsj }` |
| `jwsws` | array | 既往外伤：`{ jwswscode, jwswsmc }` |
| `jwssx` | array | 既往输血：`{ jwssxcode, jwssxyy(原因) }` |
| `familyMiddle` | object | 生活环境：`waterSourceCode`/`fuelType`/`cookAirTool`/`washroom`/`livestockColumn`/`isFillShhj` |
> `pastHistory`/`familyMiddle` 实测是 **object**（非 docx 查询侧标的 list）；多选标志仍以码值出现。
### 8.3 `healthRecord` 关键字段（实测字段名，注意坑点拼写）
| 字段 | 语义 | 备注 |
| --- | --- | --- |
| `idCard` `personName` `sexCode` `birthday` | 人口学主键四要素 | 直传+校验 |
| `phrId` | 健康档案号 | 注意驼峰 `phrId`（查询入参用小写 `phrid`） |
| `empiId` | EMPI 主索引 | 32 位十六进制串 |
| `checkId` | 第三方业务唯一码 | 本样本为 `null`（存量档案无 checkId）→ 佐证幂等键需我方生成，见 §5 |
| `manaUnitId` `createUnit` | 管辖/建档机构 | **9 位机构码**，≠ 请求头 orgCode(18位) |
| `manaDoctorId` `createUser` | 责任医生/建档人 | 机构内人员 ID |
| `regionCode` `addressCode` `homePlaceCode` | 行政区划/网格码 | 12 位 |
| `address` `adressNumber` | 现住址/门牌号 | ⚠门牌号字段名少一个 d：`adressNumber` |
| `homePlace` `homePlaceNumber` | 户籍地/门牌 | |
| `nationCode` `educationCode` `workCode` `maritalStatusCode` `bloodTypeCode` `rhBloodCode` `insuranceCode` | 码表字段 | 走 dict.go 双向查表（§3） |
| `personGroup` `otherPersonGroup` | 人群标记 | 与 JKDA00005 `personSign` 联动 |
| `isFillShhj` | 是否填生活环境 | `y`/`n` |
| `contact` `contactPhone` `mobileNumber` `phoneNumber` | 联系人/电话 | PII |
| `status` `createDate` | 档案状态/建档日期 | |
> 建模提示：`data` 用数组承接（可能多档案/多版本）；`insuranceType`、`otherPersonGroup`、`checkId` 等实测可为 `null`，结构体用指针或 `omitempty`，映射层不得因 null 报错。
docs/05-实施路线图.md
+2 -2
View File
@@ -9,7 +9,7 @@
- [ ] 初始化 Go module、单 `main.go`（`-mode server|deliver`）、`config/`（viper）。 - [ ] 初始化 Go module、单 `main.go`（`-mode server|deliver`）、`config/`（viper）。
- [ ] 落地 `osi/sign.go`（MD5 签名）+ 单测：用文档约定的 `ts/ask` 校验 `password` 形态（32 位小写）。 - [ ] 落地 `osi/sign.go`（MD5 签名）+ 单测：用文档约定的 `ts/ask` 校验 `password` 形态（32 位小写）。
- [ ] 移植旧项目 `transport.go`/`http_client.go` → `osi/transport.go`（保留 SOCKS5/超时，去 cookiejar 与拟态头）。 - [ ] 移植旧项目 `transport.go`/`http_client.go` → `osi/transport.go`（保留 SOCKS5/超时，去 cookiejar 与拟态头）。
- [ ] `osi/client.go` 的 `Call(serviceId, body, out)`：注入头+信封+发送+判码（`code=="1"`/`405`）。 - [ ] `osi/client.go` 的 `Call(serviceId, body, out)`：注入头+信封+发送+判码（成功码实测 `"01"`，按去前导零判定；`405` 可重试，见 docs/01 §1）。
- [ ] `contract/envelope.go` + `osi/codes.go`（serviceId 常量 + `pathOf` 路由）。 - [ ] `contract/envelope.go` + `osi/codes.go`（serviceId 常量 + `pathOf` 路由）。
- **验收**：对任一最简查询接口（如机构查询 CXJG00002）发真实请求，拿到 `code/message`。 - **验收**：对任一最简查询接口（如机构查询 CXJG00002）发真实请求，拿到 `code/message`。
@@ -26,7 +26,7 @@
- [ ] `osi/jkda.go`：Create/Update/Find/FindRqbj。 - [ ] `osi/jkda.go`：Create/Update/Find/FindRqbj。
- [ ] `handler` + `router`：暴露 `/api/health-record/save`（server 模式联调用）。 - [ ] `handler` + `router`：暴露 `/api/health-record/save`（server 模式联调用）。
- [ ] 用 01 文档样例 + 联调样本写映射单测。 - [ ] 用 01 文档样例 + 联调样本写映射单测。
- **验收**：一条 PHIS 档案 → 映射 → create → 平台返回 `code:"1"` 与 `phrId`；重复投递被幂等跳过。 - **验收**：一条 PHIS 档案 → 映射 → create → 平台返回成功码（实测 `"01"`）与 `phrId`；重复投递被幂等跳过。
## 阶段 3 · 投递流水线 ## 阶段 3 · 投递流水线
docs/06-厂家联调清单.md
+14 -14
View File
@@ -13,15 +13,15 @@
| # | 需要的数据 | 说明 / 对应文档 | 状态 | 厂家答复 | | # | 需要的数据 | 说明 / 对应文档 | 状态 | 厂家答复 |
|---|---|---|---|---| |---|---|---|---|---|
| A1 | 沙箱/测试环境 OSI 主机地址 | 接口里的 `${hostname}`（内网地址，不可直连） | 待要 | | | A1 | 沙箱/测试环境 OSI 主机地址 | 接口里的 `${hostname}`（内网地址，不可直连） | 已确认 | 见本地 `docs/账号.txt`（不入库） |
| A2 | **SOCKS5 代理地址** | 到达 A1 内网主机的唯一通路（host+proxy 组合，参照 chis_upload 的 `172.29.20.71:9002` + 代理 `192.168.3.148:11003`） | 待要 | | | A2 | **SOCKS5 代理地址** | 到达 A1 内网主机的唯一通路（host+proxy 组合，参照 chis_upload 的 `172.29.20.71:9002` + 代理 `192.168.3.148:11003`） | 已确认 | 见本地 `config.yaml` `socks5_proxy` |
| A3 | `orgCode` | 机构编码（机构社会统一信用代码） | 待要 | | | A3 | `orgCode` | 机构编码（机构社会统一信用代码） | 已确认 | **18 位统一社会信用代码**；注意≠config 里 9 位 `org_code`(=manaUnitId)，见 docs/01 §3 |
| A4 | `userName` | 平台分配用户名（同报文 `DSFMC` 第三方公司编码） | 待要 | | | A4 | `userName` | 平台分配用户名（同报文 `DSFMC` 第三方公司编码） | 已确认 | 见本地 config（= manageInfo.DSFMC） |
| A5 | `ask` 密钥 | 仅用于签名 `password=md5("ts=<ts>&ask=<ask>")`，**敏感、走环境变量不入库** | 待要 | | | A5 | `ask` 密钥 | 仅用于签名 `password=md5("ts=<ts>&ask=<ask>")`，**敏感、走环境变量不入库** | 已确认 | 在本地 `config.yaml`（敏感不展示） |
| A6 | `deviceSN` 取值规则 | 设备序列号——一机构一值？一设备一值？ | 待要 | | | A6 | `deviceSN` 取值规则 | 设备序列号——一机构一值？一设备一值？ | 部分 | 查询实测**可空**；创建/更新是否必填仍待确认 |
| A7 | `operateUser` / `manaDoctorId` | 默认责任医生 ID（创建类必填） | 待要 | | | A7 | `operateUser` / `manaDoctorId` | 默认责任医生 ID（创建类必填） | 部分 | 查询用 operateUser 已确认（见本地 config）；创建的 manaDoctorId 口径待联调 |
| A8 | `manaUnitId` / `operateUnit` | 管辖/操作机构编码（创建类必填） | 待要 | | | A8 | `manaUnitId` / `operateUnit` | 管辖/操作机构编码（创建类必填） | 部分 | `operateUnit`=orgCode(18位) 已确认；数据侧 `manaUnitId`(9位) 见响应样本 docs/04 §8 |
| A9 | **签名校验样例** | 给一组 `ts` 与对应正确的 `password`，用来逐字节校验我方 MD5 实现与平台一致 | 待要 | | | A9 | **签名校验样例** | 给一组 `ts` 与对应正确的 `password`，用来逐字节校验我方 MD5 实现与平台一致 | 已确认 | JKDA00002 已打通 → 我方 MD5 头签名实现与平台一致 |
| A10 | 生产环境地址+凭据 | 可后置，先拿沙箱 | 待要 | | | A10 | 生产环境地址+凭据 | 可后置，先拿沙箱 | 待要 | |
## B. 接口契约补漏（docx 缺漏/坑点，见 docs/01 §7、docs/03 §8） ## B. 接口契约补漏（docx 缺漏/坑点，见 docs/01 §7、docs/03 §8）
@@ -30,10 +30,10 @@
|---|---|---|---| |---|---|---|---|
| B1 | 缺失的**列表/查询接口路径 + serviceId**：档案列表查询、老年人自理评估「列表」与「查询」、中医体质辨识「列表」、中医健康指导「列表」与「查询」 | 待要 | | | B1 | 缺失的**列表/查询接口路径 + serviceId**：档案列表查询、老年人自理评估「列表」与「查询」、中医体质辨识「列表」、中医健康指导「列表」与「查询」 | 待要 | |
| B2 | **中医健康指导 zyjkzd** 的 serviceId + 完整字段表 | 待要 | | | B2 | **中医健康指导 zyjkzd** 的 serviceId + 完整字段表 | 待要 | |
| B3 | 确认 `jkda/find` 的 serviceId 是否为 `JKDA00002`（docx 样例误写成 `TNB00004`） | 待要 | | | B3 | 确认 `jkda/find` 的 serviceId 是否为 `JKDA00002`（docx 样例误写成 `TNB00004`） | 已确认 | ✅联调实测 `JKDA00002` 正确 |
| B4 | 老年人自理/体质**查询**的 serviceId（我方推断 `LNRZLPG00002`/`LNRZYTZ00002`） | 待要 | | | B4 | 老年人自理/体质**查询**的 serviceId（我方推断 `LNRZLPG00002`/`LNRZYTZ00002`） | 待要 | |
| B5 | 体检 `jktj/create` 的**完整字段表**（hcData/lsData/exaData/aeData，体量最大） | 待要 | | | B5 | 体检 `jktj/create` 的**完整字段表**（hcData/lsData/exaData/aeData，体量最大） | 待要 | |
| B6 | 字段名/类型不一致点核对：`jzsfqn` vs `jzsfq`、`addressNumber` vs `adressNumber`、`familyMiddle`/`pastHistory` 是 object 还是 list | 待要 | | | B6 | 字段名/类型不一致点核对：`jzsfqn` vs `jzsfq`、`addressNumber` vs `adressNumber`、`familyMiddle`/`pastHistory` 是 object 还是 list | 部分 | JKDA00002 **响应**侧确认：`adressNumber`(缺 d)、`pastHistory`/`familyMiddle`=object（docs/04 §8）；创建**入参**拼写仍待核 |
## C. 业务规则确认（决定关键设计） ## C. 业务规则确认（决定关键设计）
@@ -41,7 +41,7 @@
|---|---|---|---|---| |---|---|---|---|---|
| C1 | **checkId 规则**：长度上限、是否要求全局唯一、平台是否以 checkId 去重、同一 checkId 再次 create 是更新还是报错、create/update 幂等语义 | 幂等键设计（docs/04 §5） | 待要 | | | C1 | **checkId 规则**：长度上限、是否要求全局唯一、平台是否以 checkId 去重、同一 checkId 再次 create 是更新还是报错、create/update 幂等语义 | 幂等键设计（docs/04 §5） | 待要 | |
| C2 | **完整度**：`completeLevel`/`perfection` 由平台计算还是接入方上送？除 `isFillShhj` 外是否还需完整度入参 | 是否移植旧项目完整度逻辑（docs/03 §8-1） | 待要 | | | C2 | **完整度**：`completeLevel`/`perfection` 由平台计算还是接入方上送？除 `isFillShhj` 外是否还需完整度入参 | 是否移植旧项目完整度逻辑（docs/03 §8-1） | 待要 | |
| C3 | **错误码字典**：除 `1`(成功)/`405`(超时) 外的失败码清单 | 重试分类（docs/04 §6） | 待要 | | | C3 | **错误码字典**：除成功/`405`(超时) 外的失败码清单 | 重试分类（docs/04 §6） | 部分 | ⚠成功码实测为 `"01"` 非 `"1"`（docs/01 §1）；完整失败码字典仍待要 |
| C4 | **官方码表**：民族 56 项、行政区划/网格代码、医保支付方式等是否有官方完整版下发 | 字典层（docs/04 §3） | 待要 | | | C4 | **官方码表**：民族 56 项、行政区划/网格代码、医保支付方式等是否有官方完整版下发 | 字典层（docs/04 §3） | 待要 | |
| C5 | 各创建接口的**必填字段最终口径**（以平台实际校验为准） | 映射校验 | 待要 | | | C5 | 各创建接口的**必填字段最终口径**（以平台实际校验为准） | 映射校验 | 待要 | |
@@ -50,8 +50,8 @@
| # | 需要的样本 | 状态 | 厂家答复 | | # | 需要的样本 | 状态 | 厂家答复 |
|---|---|---|---| |---|---|---|---|
| D1 | 每个 **create 接口**一组真实成功的请求 JSON + 响应 JSON | 待要 | | | D1 | 每个 **create 接口**一组真实成功的请求 JSON + 响应 JSON | 待要 | |
| D2 | 各查询/列表接口一组真实响应样本（data 是数组还是对象、分页结构） | 待要 | | | D2 | 各查询/列表接口一组真实响应样本（data 是数组还是对象、分页结构） | 部分 | JKDA00002 已获（`data` 为数组，结构见 docs/04 §8）；其余接口仍待要 |
| D3 | 一个**测试身份证/测试档案**，联调用、不污染生产数据 | 待要 | | | D3 | 一个**测试身份证/测试档案**，联调用、不污染生产数据 | 已回 | 已有可查档案（本地样本，含 PII 不入库） |
## E. 联调支持 ## E. 联调支持