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

- 成功码实测为字符串 "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>

docs/01-OSI接口规范分析.md

@@ -13,14 +13,15 @@
 | 通用 URL | `http://${hostname}/osi/api/...`（各接口在此基础上拼子路径） |
 | 报文格式 | 请求/响应均为 JSON 字符串 |
 | 字符集 | 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 响应统一结构
 
 ```json
-{ "code": "1", "message": "操作成功", "data": { ... } }
+{ "code": "01", "message": "操作成功", "data": [ ... ] }
 ```
 
 - `data` 在创建类接口是对象（如 `{ "phrId": "...", "createUnit": "..." }`）；
@@ -36,7 +37,7 @@
 | --- | --- |
 | `Content-Type` | `application/json` |
 | `orgCode` | 机构编码（机构的社会统一信用代码，约 18~20 位）。接入方先把组织/机构信息提供给平台，由平台生成 |
-| `deviceSN` | 设备序列号（创建/更新/查询类接口均要求必填） |
+| `deviceSN` | 设备序列号。docx 标各类接口必填，但**联调实测** JKDA00002 查询 `deviceSN` 为空仍成功——查询类可空；创建/更新是否必填待联调（docs/06 A6） |
 | `ts` | 13 位毫秒级时间戳 |
 | `userName` | 平台分配的用户名（对应一个 `ask` 密钥；同时也是报文里的第三方接入公司名称编码 `DSFMC`） |
 | `password` | `md5("ts=<时间戳>&ask=<密钥>")`，取 **32 位小写** |
@@ -53,28 +54,31 @@
 
 ## 3. 请求报文信封
 
-请求体（HTTP body）统一为：
+**联调实测**：请求体统一为 `serviceId` + `uploadinfo` 两段，**查询类同样走 `uploadinfo` 信封**（早期依 docx 猜测查询发裸 `baseInfo`，实测不成立）：
 
 ```json
 {
   "serviceId": "<固定服务码>",
-  "uploadinfo": { ... }   // 创建/更新类：写入数据
-}
-```
-或查询类：
-```json
-{
-  "serviceId": "<固定服务码>",
-  "baseInfo": { ... }     // 查询条件
+  "uploadinfo": {
+    "baseInfo":   { ... },   // 查询：查询条件；创建：人口学主键等
+    "manageInfo": { ... },   // 管理节点，查询与创建都要带
+    "...":        { ... }    // 创建/更新再加 healthRecord / pastHistory / jwsjb … 业务节点
+  }
 }
 ```
 
 - `serviceId` 是每个接口的**固定常量**（见第 5 节映射表），平台据此路由业务。
-- 创建/更新类信封内含 `manageInfo`（管理节点）+ 业务数据节点：
-  - `manageInfo.DSFMC` = 第三方接入公司名称编码（与请求头 `userName` 一致）
-  - `manageInfo.operateUnit` = 操作机构编码（与请求头 `orgCode` 一致）
-  - `manageInfo.operateUser` = 责任医生 ID
-- 文档中创建样例外层出现的 `"headers": {...}` 仅用于演示 HTTP 头，**不是 body 的一部分**；实际 POST body 只发 `serviceId`+数据节点。
+- `manageInfo` 三字段（JKDA00002 查询实测携带即成功，是否可省未验证）：
+  - `DSFMC` = 第三方接入公司名称编码（= 请求头 `userName`）
+  - `operateUnit` = 操作机构编码（= 请求头 `orgCode`）
+  - `operateUser` = 操作用户 / 责任医生 ID
+- 文档中创建样例外层出现的 `"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 | 主数据节点 |
 | --- | --- | --- | --- |
 | 创建 | `/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/findrqbj` | `JKDA00005` | `baseInfo`(phrid/idCard 二选一) → `data.personSign` |
 | 列表查询 | （清单第 1 项，文档正文未见独立路径，疑与 `find` 合并或缺漏） | 待确认 | — |
@@ -189,11 +193,12 @@
 
 官方 docx 存在明显的复制粘贴/排版错误，建模前需逐一核对：
 
-1. **serviceId 串台**：`jkda/find` 的请求样例里 serviceId 写成 `TNB00004`（糖尿病接口的码），实际应为 `JKDA00002`。
-2. **字段名不一致**：创建档案家族史父亲在字段定义里叫 `jzsfqn`，在请求样例里叫 `jzsfq`；现住址门牌号在创建里 `addressNumber`、在查询里 `adressNumber`（少一个 d）。
-3. **类型不一致**：`familyMiddle` 在创建接口标 `object`，在查询接口标 `list`；`pastHistory` 同样在不同接口标注不同。
-4. **样例 JSON 非法**：多处查询样例花括号不配对（如 `{ "baseInfo": {...} }, "serviceId": "..." }`），应理解为 `{ "serviceId": "...", "baseInfo": {...} }`。
-5. **列表查询路径缺漏**：xlsx 要求"档案列表查询""自理/体质/中医指导列表查询""自理查询"等，但 docx 正文未给出全部独立路径与 serviceId，需向厂家索要补充。
+1. **serviceId 串台**：`jkda/find` 的请求样例里 serviceId 写成 `TNB00004`（糖尿病接口的码），实际应为 `JKDA00002` —— ✅**联调已确认为 `JKDA00002`**。
+2. **字段名不一致**：创建档案家族史父亲在字段定义里叫 `jzsfqn`，在请求样例里叫 `jzsfq`；现住址门牌号在创建里 `addressNumber`、在查询里 `adressNumber`（少一个 d）—— ✅JKDA00002 **响应实测确实返回 `adressNumber`（缺 d）**，响应侧以错拼写为准；创建侧入参拼写仍待联调核对。
+3. **类型不一致**：`familyMiddle` 在创建接口标 `object`，在查询接口标 `list`；`pastHistory` 同样在不同接口标注不同 —— ✅JKDA00002 **响应实测 `pastHistory`/`familyMiddle` 均为 object**，`jwsjb`/`jwssx`/`jwsss`/`jwsws` 为 array（见 docs/04 §8）。
+4. **样例 JSON 非法**：多处查询样例花括号不配对（如 `{ "baseInfo": {...} }, "serviceId": "..." }`）。⚠实测请求信封为 `{ "serviceId": "...", "uploadinfo": { "baseInfo": {...}, "manageInfo": {...} } }`，查询条件包在 `uploadinfo.baseInfo` 内，**不是**外层裸 `baseInfo`。
+5. **成功码不是 `"1"`**：docx/早期整理写成功 `code="1"`，✅**联调实测为 `code="01"`**（见第 1 节），成功判定需兼容前导零。
+6. **列表查询路径缺漏**：xlsx 要求"档案列表查询""自理/体质/中医指导列表查询""自理查询"等，但 docx 正文未给出全部独立路径与 serviceId，需向厂家索要补充。
 
 > 结论：**不能直接照搬 docx 字段表生成契约**。落地前应整理一份「校验后的接口契约」（见 03 文档 `contract/` 包），
 > 并以厂家沙箱环境的真实请求/响应样本做回归校准。