docs: 初始化 chis_osi 设计文档与协作规范

- docs/: OSI 接口规范分析、旧项目架构评估、目标架构设计、字段与接口映射、实施路线图 - CLAUDE.md: 协作规则（项目认知、osi/mapping/pipeline 三层技术约束、安全/验证、提交规范） - .gitignore: 补充项目特定忽略（config.yaml/logs/样本等） - 随项目留存厂家 OSI 规范源材料（docx/xlsx，内部保密，仅限本私有仓库） Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-05-30 13:10:17 +08:00
parent 18bf9a82af
commit 3498542b07
11 changed files with 1014 additions and 28 deletions
@@ -0,0 +1,147 @@
+# 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 配合）
+
+| 错误来源 | 分类 | 处理 |
+| --- | --- | --- |
+| 映射缺必填/码表未命中/格式非法 | 不可重试（数据错） | 直接 failed，回写 PHIS，附 ValidationError 明细 |
+| 网络错误 / SOCKS / EOF / 超时 | 可重试 | 退避重试，计熔断 |
+| OSI `code == "405"`（服务超时） | 可重试 | 退避重试 |
+| OSI `code` 非 1 非 405（业务/权限拒绝） | 不可重试 | failed，记 message 供排查 |
+| HTTP 5xx / 429 | 可重试 | 退避重试 |
+
+---
+
+## 7. 待补字段表
+
+以下接口的完整字段表 docx 未充分给出或存在坑点，建模时以联调样本为准并在此登记：
+
+- [ ] 体检 `jktj/create` 全量字段（hcData/lsData/exaData/aeData，体量最大）
+- [ ] 老年人自理评估 `lnrzlpg` 字段
+- [ ] 中医体质辨识 `lnrzyygl` 字段
+- [ ] 中医健康指导 `zyjkzd` 字段 + serviceId
+- [ ] 各列表/查询接口的分页与返回数组结构