chis_osi/docs/04-字段与接口映射.md

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 映射函数约定

// 返回结构化校验错误，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/01 §1 为准：实测为字符串 "01"（非 "1"），判定按去前导零后 == "1"。

错误来源	分类	处理
映射缺必填/码表未命中/格式非法	不可重试（数据错）	直接 failed，回写 PHIS，附 ValidationError 明细
网络错误 / SOCKS / EOF / 超时	可重试	退避重试，计熔断
OSI code == "405"（服务超时）	可重试	退避重试
OSI code 非成功码非 405（业务/权限拒绝）	不可重试	failed，记 message 供排查
HTTP 5xx / 429	可重试	退避重试

---

7. 待补字段表

以下接口的完整字段表 docx 未充分给出或存在坑点，建模时以联调样本为准并在此登记：

• 体检 jktj/create 全量字段（hcData/lsData/exaData/aeData，体量最大）
• 老年人自理评估 lnrzlpg 字段
• 中医体质辨识 lnrzyygl 字段
• 中医健康指导 zyjkzd 字段 + serviceId
• 个人档案查询 JKDA00002 的请求信封与返回结构 —— 已联调实测，见 §8
• 其余列表/查询接口的分页与返回数组结构（体检/老年人/中医指导）

---

8. JKDA00002 个人档案查询 · 联调实测契约

来源：2026-07 沙箱一次成功查询（code="01" 操作成功）。下方均为脱敏结构，真实身份证/姓名/联系方式等 PII 只在本地样本，不入库。 这是 contract/ 里 FindHealthRecord 请求/响应结构体与 osi.FindHealthRecord 的事实基线。

8.1 请求（POST /osi/api/auto/jkda/find）

{
  "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 报错。