nc/chis_osi
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
74748c084bde42c8162288ab9d1472a8f548468c
chis_osi/docs/04-字段与接口映射.md
T

240 lines
13 KiB
Markdown
Raw Normal View History

docs: 初始化 chis_osi 设计文档与协作规范
2026-05-30 00:37:34 +08:00
# 04 · 字段与接口映射
本文是 `mapping/` 与 `contract/` 两层的落地指引：接口能力映射、PHIS→OSI 字段映射策略、码表清单、checkId 幂等键设计。
---
## 1. 接口能力 → 内部方法映射
| OSI serviceId | 路径 | 内部方法（`osi` 包） | dataType（pipeline 分流） |
| --- | --- | --- | --- |
| JKDA00001 | `/jkda/create` | `CreateHealthRecord` | `health_record` |
| JKDA00003 | `/jkda/update` | `UpdateHealthRecord` | `health_record` |
| JKDA00002 | `/auto/jkda/find` | `FindHealthRecord` | （查询） |
| JKDA00005 | `/jkda/findrqbj` | `FindPersonSign` | （查询） |
| JKTJ00001 | `/jktj/create` | `CreateHealthCheck` | `health_check` |
| JKTJ00003 | `/jktj/update` | `UpdateHealthCheck` | `health_check` |
| JKTJ00002 | `/auto/jktj/query` | `QueryHealthCheck` | （查询） |
| JKTJLIST00002 | `/auto/jktjlist/query` | `ListHealthCheckPeople` | （查询） |
| JKTJLSJL00002 | `/auto/jktjlscx/query` | `LastHealthCheck` | （查询） |
| LNRZLPG00001 | `/lnrzlpg/create` | `CreateElderlySelfCare` | `elderly_self_care` |
| LNRZLPG00003 | `/lnrzlpg/update` | `UpdateElderlySelfCare` | `elderly_self_care` |
| LNRZYTZ00001 | `/lnrzyygl/create` | `CreateTCMConstitution` | `tcm` |
| LNRZYTZ00003 | `/lnrzyygl/update` | `UpdateTCMConstitution` | `tcm` |
| （待确认） | `/auto/zyjkzd/create` | `SaveTCMGuidance` | `tcm_guidance` |
| （待确认） | `/auto/zyjkzd/update` | `UpdateTCMGuidance` | `tcm_guidance` |
| WGDZ00001 | `/auto/wgdzcx/query` | `QueryGridAddress` | （字典） |
| ZRYS00001 | `/auto/zryscx/query` | `QueryDoctors` | （字典） |
| YPML00001 | `/auto/ypmlcx/query` | `QueryDrugs` | （字典） |
| CXJG00002 | `/auto/cxjg/query` | `QueryOrgs` | （字典） |
> ⚠ "（待确认）"项以 01 文档第 7 节为准，联调回填后更新 `osi/codes.go` 的 serviceId 常量与 `pathOf` 路由表。
---
## 2. 字段映射策略
### 2.1 三类字段，三种处理
1. **直传字段**：PHIS 与 OSI 同义且同形（如姓名、出生日期 `yyyy-MM-dd`）。直接拷贝，做必填/长度校验。
2. **码表字段**：枚举值需经字典转换（性别、民族、血型、职业…）。统一走 `dict.go` 双向查表，未命中报 `ValidationError`，**绝不静默置空**。
3. **结构/多选字段**：嵌套节点（既往史/家族史/手术/外伤/输血/生活环境）、逗号拼接多选。集中在各业务域映射函数里组装。
### 2.2 映射函数约定
```go
// 返回结构化校验错误，pipeline 在投递前据此拦截，避免把脏数据打到平台。
func MapHealthRecord(src phis.HealthRecord, ctx MapContext) (contract.HealthRecordCreate, []ValidationError)
```
- `MapContext` 携带机构级常量：`orgCode/userName/operateUser/regionCode` 默认值与字典快照。
- 校验项：必填（idCard/personName/sexCode/birthday/mobileNumber/regionCode/manaDoctorId/manaUnitId…）、长度上限、码表合法性、日期格式。
- 映射是**纯函数**，便于用 01 文档样例 + 联调真实样本做单测（对齐旧项目"可测试改动补最小必要测试"）。
---
## 3. 码表清单（`dict.go` 初始内容）
> 取值来自 docx 字段说明，建模时全部落为常量表，并加注释标"来源：OSI 文档 §字段名"。
| 维度 | 取值（节选） |
| --- | --- |
| 性别 sexCode | 0 未知 / 1 男 / 2 女 / 9 未说明 |
| 户籍 registeredPermanent | 1 户籍 / 2 非户籍 |
| 血型 bloodTypeCode | 1 A / 2 B / 3 O / 4 AB / 5 不详 |
| RH rhBloodCode | 1 阳性 / 2 阴性 / 3 不详 |
| 文化程度 educationCode | 10 研究生 / 20 本科 / 31 大专 / 41 中专 / 47 技校 / 60 高中 / 70 初中 / 80 小学 / 90 文盲 / 91 不详 |
| 职业 workCode | 0 负责人 / 1·2 专技 / 3 办事 / 4 商业服务 / 5 农林牧渔 / 9-9 生产运输 / X 军人 / Y 其他 / 8 无职业 |
| 婚姻 maritalStatusCode | 10 未婚 / 20 已婚 / 30 丧偶 / 40 离婚 / 90 未说明 |
| 医保 insuranceCode（多选） | 01 城镇职工 / 02 城乡居民 / 04 贫困救助 / 05 商业 / 06 全公费 / 07 全自费 / 99 其他 |
| 民族 nationCode | 01 汉 … 56 基诺 / 99 其他（56 项全表） |
| 人群标记 personSign | PU 普通 / GRQY 已签约 / LAO 老年 / GAO 高血压 / TANG 糖尿病 / FU 孕产妇 / ER 儿童 / FEI 肺结核 / JING 精神 / CAN 残疾 |
| 药物过敏 ywgms（多选） | 0101 无 / 0102 青霉素 / 0103 磺胺 / 0104 链霉素 / 0109 其他 |
| 既往疾病 jwsjbcode | 0201 无 / 0202 高血压 / 0203 糖尿病 / … / 0299 其他 |
| 残疾 cjqk（多选） | 1101 无 / 1102 视力 / 1103 听力 / 1104 言语 / 1105 肢体 / 1106 智力 / 1107 精神 / 1108 孤独症 / 1109 脑瘫 / 1199 其他 |
| 厨房排风 cookAirTool | 1 无 / 2 油烟机 / 3 换气扇 / 4 烟囱 / 9 其他 |
| 燃料 fuelType | 1 液化气 / 2 煤 / 3 天然气 / 4 沼气 / 5 柴火 / 9 其他 |
| 饮水 waterSourceCode | 1 自来水 / 2 净化水 / 3 井水 / 4 河湖水 / 5 塘水 / 9 其他 |
| 厕所 washroom | 1 卫生厕所 / 2 粪池式 / 3 马桶 / 4 露天粪坑 / 5 简易棚厕 / 6 其他 |
| 机构类型 organizType | A 医院 / B 社区中心(站) / C 卫生院 / D 门诊诊所村室 / D6 村卫生室 / R 市卫生局 |
> 多选字段统一用英文逗号拼接（文档示例如 `"0102,0103"`）。注意 docx 个别返回样例用了中文逗号，解析时两者都要兼容。
---
## 4. 主数据依赖：字典服务先行
创建类接口的若干必填字段依赖公共服务查询结果，建议在投递前用字典缓存解析：
```
regionCode ← QueryGridAddress(parentCode) // 网格地址
manaDoctorId/operateUser ← QueryDoctors(manaUnitId) // 责任医生
manaUnitId/organizCode ← QueryOrgs(...) // 机构
```
策略：启动或定时拉取这些字典，缓存到本地（redis 可选 + 内存），映射时按 PHIS 的地址/医生/机构名称反查 OSI 码。命中失败计入校验错误，不投递。
---
## 5. checkId 与幂等键设计
`checkId`（第三方业务唯一识别码，长度 20）是新项目幂等的核心。
### 5.1 生成规则（`mapping/checkid.go`）
要求**确定性**：同一源记录无论重试多少次，都得到同一 checkId。
```
checkId = 截断20位( 编码( 源系统标识 | dataType | 源记录主键 [ | 版本/更新时间] ) )
```
- 同一条源记录的"创建"应使用稳定 checkId → 平台据此识别为同一档案，避免重复建档。
- "更新"沿用原 checkId（走 update 接口）。
- 若源记录内容变更需视为新版本上送，可把"更新时间/版本号"纳入 checkId 计算——**取决于平台是否以 checkId 去重**（见 03 文档开放问题 5）。
### 5.2 幂等存储
- 键：`checkId`（替代旧项目 `account|idCard|dataType|sha1(saveBody)`）。
- 值：`{status: success|failed, phrId, lastTs, attempts}`。
- 命中 `success`：跳过，不重复投递。
- `failed`：允许后续重试。
- 存储：redis 优先、本地 JSON 降级（沿用旧项目 `idempotency_store` 思路）。
> 用 checkId 做幂等键的好处：与平台对账口径一致（平台也认 checkId），且不受报文字段微调影响。
---
## 6. 校验与错误分类（与 pipeline 配合）
docs: 依 JKDA00002 联调实测校准接口契约
2026-07-06 20:09:43 +08:00
> 成功码以 docs/01 §1 为准：实测为字符串 `"01"`（非 `"1"`），判定按去前导零后 == `"1"`。
docs: 初始化 chis_osi 设计文档与协作规范
2026-05-30 00:37:34 +08:00
| 错误来源 | 分类 | 处理 |
| --- | --- | --- |
| 映射缺必填/码表未命中/格式非法 | 不可重试（数据错） | 直接 failed，回写 PHIS，附 ValidationError 明细 |
| 网络错误 / SOCKS / EOF / 超时 | 可重试 | 退避重试，计熔断 |
| OSI `code == "405"`（服务超时） | 可重试 | 退避重试 |
docs: 依 JKDA00002 联调实测校准接口契约
2026-07-06 20:09:43 +08:00
| OSI `code` 非成功码非 405（业务/权限拒绝） | 不可重试 | failed，记 message 供排查 |
docs: 初始化 chis_osi 设计文档与协作规范
2026-05-30 00:37:34 +08:00
| HTTP 5xx / 429 | 可重试 | 退避重试 |
---
## 7. 待补字段表
以下接口的完整字段表 docx 未充分给出或存在坑点，建模时以联调样本为准并在此登记：
- [ ] 体检 `jktj/create` 全量字段（hcData/lsData/exaData/aeData，体量最大）
- [ ] 老年人自理评估 `lnrzlpg` 字段
- [ ] 中医体质辨识 `lnrzyygl` 字段
- [ ] 中医健康指导 `zyjkzd` 字段 + serviceId
docs: 依 JKDA00002 联调实测校准接口契约
2026-07-06 20:09:43 +08:00
- [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 报错。
feat(osi): 实现公开字典查询接口（T-101）
2026-07-07 20:58:13 +08:00
---
## 9. 公共字典查询 · 联调实测契约
> 来源：2026-07-07 沙箱验证。使用本地未入库凭据和一条已存在档案反查主数据后验证；下方只记录脱敏事实，不记录真实身份证、机构码、医生姓名或密钥。
### 9.1 请求信封
四个公共查询接口与 JKDA 查询一致，仍走统一信封：
```json
{
"serviceId": "<公共查询serviceId>",
"uploadinfo": {
"baseInfo": { "...": "..." },
"manageInfo": { "DSFMC": "<userName>", "operateUser": "<operateUser>", "operateUnit": "<orgCode-18位>" }
}
}
```
### 9.2 已验证结果
| 接口 | serviceId | 真实验证结论 | 备注 |
| --- | --- | --- | --- |
| 网格地址查询 | `WGDZ00001` | `code="01"` 且返回数组非空 | 用已存在档案的区划/网格码派生 `parentCode` 候选值验证 |
| 责任医生查询 | `ZRYS00001` | `code="01"` 且返回数组非空 | 入参 `manaUnitId` 使用档案返回的 9 位机构码 |
| 机构查询 | `CXJG00002` | `code="01"` 且返回数组非空 | 入参 `organizCode` 使用档案返回的 9 位机构码 |
| 药品目录查询 | `YPML00001` | 未做真实联调 | T-101 已完成客户端封装与单测；后续有药品关键字/拼音码时补样本 |
> T-103 字典缓存可以先依赖网格、责任医生、机构三类真实验证结果。药品目录与健康档案创建闭环无直接依赖，不阻塞 T-103/T-206。
Reference in New Issue Copy Permalink