From ca16f6126392cf273030efc50a90bdd46430c661 Mon Sep 17 00:00:00 2001 From: QiuSW Date: Thu, 9 Jul 2026 20:35:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=99=BB=E8=AE=B0=E4=BA=BA=E7=BE=A4?= =?UTF-8?q?=E5=88=86=E7=B1=BB=E6=9F=A5=E8=AF=A2=E4=BC=98=E5=8C=96=E4=BB=BB?= =?UTF-8?q?=E5=8A=A1=EF=BC=88T-209=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/01-OSI接口规范分析.md | 2 +- docs/04-字段与接口映射.md | 47 +++++++++++++++++++++++++++++++++++++- progress.md | 7 ++++++ tasks.md | 1 + 4 files changed, 55 insertions(+), 2 deletions(-) diff --git a/docs/01-OSI接口规范分析.md b/docs/01-OSI接口规范分析.md index ab61502..3ec55dc 100644 --- a/docs/01-OSI接口规范分析.md +++ b/docs/01-OSI接口规范分析.md @@ -125,7 +125,7 @@ | 创建 | `/osi/api/jkda/create` | `JKDA00001` | `uploadinfo.healthRecord` + `pastHistory`/`jwsjb`/`jwsss`/`jwsws`/`jwssx`/`familyMiddle` | | 查询 | `/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` | +| 人群/子档案标记查询 | `/osi/api/auto/jkda/findrqbj` | `JKDA00005` ✅联调确认（2026-07-09） | `baseInfo`(idCard/phrid 二选一) → `data.personSign/idCard/phrId` | | 列表查询 | （清单第 1 项，文档正文未见独立路径，疑与 `find` 合并或缺漏） | 待确认 | — | `findrqbj` 返回的 `personSign` 取值：`PU` 普通 / `GRQY` 已签约 / `LAO` 老年人 / `GAO` 高血压 / `TANG` 糖尿病 / `FU` 孕产妇 / `ER` 儿童 / `FEI` 肺结核 / `JING` 精神障碍 / `CAN` 残疾人，多个以逗号分隔。 diff --git a/docs/04-字段与接口映射.md b/docs/04-字段与接口映射.md index dbf5299..8c784f7 100644 --- a/docs/04-字段与接口映射.md +++ b/docs/04-字段与接口映射.md @@ -11,7 +11,7 @@ | JKDA00001 | `/jkda/create` | `CreateHealthRecord` | `health_record` | | JKDA00003 | `/jkda/update` | `UpdateHealthRecord` | `health_record` | | JKDA00002 | `/auto/jkda/find` | `FindHealthRecord` | （查询） | -| JKDA00005 | `/jkda/findrqbj` | `FindPersonSign` | （查询） | +| JKDA00005 | `/auto/jkda/findrqbj` | `FindRqbj` | （查询） | | JKTJ00001 | `/jktj/create` | `CreateHealthCheck` | `health_check` | | JKTJ00003 | `/jktj/update` | `UpdateHealthCheck` | `health_check` | | JKTJ00002 | `/auto/jktj/query` | `QueryHealthCheck` | （查询） | @@ -315,3 +315,48 @@ T-206 已建立本地契约与客户端方法，真实写入验收暂未执行 - **响应 `data`（list，每人一行）· 实测字段名**（⚠ 与 docx 多处不符，以实测为准）： `idCard`/`personName`/`age`/**`birthday`**(docx 误写 birthDay)/`sexCode`/`regionCode`/`regionCodeText`/`manaUnitId`/`manaUnitText`/**`manaDoctorId`**(docx 误写 manadoctorId)/**`manaDocterName`**(拼写 Docter)/**`phrId`**(docx 误写 phrid，此处驼峰)/**`empiId`**/`signFlag`(y/n 签约)/`address`/`mobileNumber`/`contact`/`contactPhone`/**`checkType`(0已检/1未检)**/`rqbj`(人群标志，同 personSign 码表)。 +--- + +## 12. JKDA00005 人群分类查询 · 联调实测契约（T-209） + +> 来源：2026-07-09 本地探针 `scripts/query_crow_with_idcard.py` 与返回样本 `scripts/query_crow_with_idcard.json`。样本含真实身份证和档案号，只本地留存、不入库；本文只记录脱敏结构。 + +### 12.1 请求 + +```json +{ + "serviceId": "JKDA00005", + "uploadinfo": { + "baseInfo": { "idCard": "" }, + "manageInfo": { "DSFMC": "", "operateUser": "", "operateUnit": "" } + } +} +``` + +- 路径：`/osi/api/auto/jkda/findrqbj`。 +- `baseInfo` 支持 `idCard` / `phrid` 二选一；实测样本使用 `idCard`。 +- 注意：早期代码/文档登记为 `/jkda/findrqbj`，本次实测脚本使用 `auto/jkda/findrqbj` 返回 `code="01"`，T-209 需同步修正 `osi/codes.go`。 + +### 12.2 响应 + +```json +{ + "code": "01", + "message": "操作成功", + "data": { + "personSign": "LAO", + "idCard": "", + "phrId": "" + } +} +``` + +字段说明： + +| 字段 | 类型 | 说明 | +| --- | --- | --- | +| `personSign` | string | 人群分类码，可能为逗号分隔多值；码表见 §3 `personSign` | +| `idCard` | string | 身份证号，PII | +| `phrId` | string | 健康档案号，响应为驼峰 `phrId` | + +Go 侧契约应从只承接 `personSign` 优化为完整承接 `personSign/idCard/phrId`，server 端点原样回写平台 JSON，避免裁掉后续可能新增字段。 diff --git a/progress.md b/progress.md index 6018506..7a1b24e 100644 --- a/progress.md +++ b/progress.md @@ -249,3 +249,10 @@ - 变更：新建 `docs/07-本项目HTTP接口.md`，整理 server 模式 5 个查询端点（档案 find + 体检 last/all/list）的参数/上游 serviceId/返回形态/PII 警示/通用约定；`docs/README.md` 导航登记；`CLAUDE.md` 文档同步表加"HTTP 端点增改 → docs/07"。 - 决策：区分两层接口文档——上游 OSI 契约以 docs/01+04（实测）为准，本项目对外接口以 docs/07 为单一事实来源；docx 反复被证明不可靠，只作参考。 - 下一步：新增端点时同步 docs/07；对外前补鉴权/日志/限流。 +## 2026-07-09 登记 T-209 人群分类查询优化 + +- 状态：DONE（看板+契约文档维护） +- 来源：用户更新 `scripts/query_crow_with_idcard.py`，并提供本地响应样本 `scripts/query_crow_with_idcard.json`（含真实身份证/phrId，不入库）。 +- 发现：JKDA00005 实测请求路径为 `/osi/api/auto/jkda/findrqbj`，响应 `data` 是对象，字段含 `personSign`、`idCard`、`phrId`；当前 Go 侧只建模 `personSign`，且路径仍是早期 `/jkda/findrqbj`。 +- 变更：`tasks.md` 新增 T-209；`docs/01`、`docs/04 §12` 登记实测契约和待改点。 +- 下一步：实现 T-209，修正 `osi` 路由/响应结构，并补 server 模式人群分类查询端点。 diff --git a/tasks.md b/tasks.md index 639b1a4..d559c2d 100644 --- a/tasks.md +++ b/tasks.md @@ -45,6 +45,7 @@ | T-201 | `contract/jkda.go`：以 docs/04 §8 实测契约建**查询响应**结构体 | T-004 | Find 响应能完整反序列化本地联调样本（`data` 数组、null 字段用指针/omitempty、`adressNumber` 坑点拼写）；创建请求结构体延到 T-206 补 | DONE | | T-203 | `osi/jkda.go`：**Find + FindRqbj** | T-201 | 用 JKDA00002 真实请求打通，拿到 `code="01"` 与档案数据，与 Python 脚本结果一致 | DONE | | T-208 | `server` 模式健康档案查询端点 `GET /api/health-record/find` | T-203 | server 模式起 HTTP 服务，curl 按 idCard/phrid/personName/empiId 查询返回平台完整档案 JSON；默认仅绑本机 | DONE | +| T-209 | 优化人群分类查询 JKDA00005（路径/契约/HTTP 端点） | T-203, T-208 | 按实测 `auto/jkda/findrqbj` 查询，响应结构含 `personSign/idCard/phrId`；server 模式提供人群分类查询端点并原样回写平台 JSON | TODO | ## Phase M · 映射层（码表 + 纯函数，注入假字典快照）