diff --git a/docs/05-实施路线图.md b/docs/05-实施路线图.md index 56a8117..68707a2 100644 --- a/docs/05-实施路线图.md +++ b/docs/05-实施路线图.md @@ -21,7 +21,7 @@ ## 阶段 1 · 字典服务打通 - [ ] 实现 `public.go` 四个查询：网格/责任医生/药品/机构。 -- [ ] `mapping/dict.go` 落地全部码表（含 56 项民族）。 +- [x] `mapping/dict.go` 落地全部码表（含 56 项民族）。 - [ ] 字典缓存（内存 + redis 可选），供映射层反查 `regionCode/manaDoctorId/manaUnitId`。 - **验收**：能用真实机构码查到下级网格、责任医生、机构树。 diff --git a/docs/current-state.md b/docs/current-state.md index 88bf1e1..6c8a53a 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -6,11 +6,11 @@ ## 当前快照 - 日期：2026-07-07 -- 阶段：**Phase Q 查询档案已打通**；T-001~T-006、T-201、T-203 已验收，下一步进入 Phase M 的 T-102 +- 阶段：**Phase M 映射基线已起步**；T-001~T-006、T-201、T-203、T-102 已验收，下一步进入 T-202 - 技术栈：Go 1.24 单二进制；`main.go -mode server|deliver`；配置读取使用 viper，支持环境变量覆盖；OSI 客户端已具备签名、信封、传输、基础判码、JKDA00002 Find 与 JKDA00005 FindRqbj -- 生产代码：已有 `main.go`、`config/`、`contract/envelope.go`、`osi/sign.go`、`osi/transport.go`、`osi/codes.go`、`osi/client.go`、`verify_jkda.go`、`go.mod`/`go.sum`；`contract/jkda.go` 已建立 JKDA00002 查询响应契约；`osi/jkda.go` 已实现 Find/FindRqbj；`mapping/`、`pipeline/` 等业务模块仍待后续任务建立 +- 生产代码：已有 `main.go`、`config/`、`contract/envelope.go`、`osi/sign.go`、`osi/transport.go`、`osi/codes.go`、`osi/client.go`、`verify_jkda.go`、`go.mod`/`go.sum`；`contract/jkda.go` 已建立 JKDA00002 查询响应契约；`osi/jkda.go` 已实现 Find/FindRqbj；`mapping/dict.go` 已建立码表基线；`pipeline/` 等业务模块仍待后续任务建立 - 联调现实：**JKDA00002 个人档案查询已用 Go 侧真实请求打通**，返回 `code="01" message="操作成功" data_count=1`；Python 联调样本和实测契约沉淀在 `docs/04 §8` -- 测试：`go test ./...` 通过；当前测试覆盖 mode 解析、配置加载与环境变量覆盖、MD5 签名、请求头组装、JSON POST 传输、头名大小写保留、identity 响应编码声明、超时配置、SOCKS5 代理地址校验、信封结构、serviceId 路由、成功/重试判码、Client.Call 请求与响应解析、JKDA00002 查询响应契约、JKDA00002 Find、JKDA00005 FindRqbj、JKDA00002 验证入口 +- 测试：`go test ./...` 通过；当前测试覆盖 mode 解析、配置加载与环境变量覆盖、MD5 签名、请求头组装、JSON POST 传输、头名大小写保留、identity 响应编码声明、超时配置、SOCKS5 代理地址校验、信封结构、serviceId 路由、成功/重试判码、Client.Call 请求与响应解析、JKDA00002 查询响应契约、JKDA00002 Find、JKDA00005 FindRqbj、映射码表双向查找、民族 01~56 完整性、JKDA00002 验证入口 - 标准启动路径：`./init.sh` 已配置三步：依赖下载、`go test ./...`、`go run . -mode server -config config.yaml.example` - 标准验证路径：`go test ./...`、`go build ./...` - 当前 blocker：无硬 blocker。软限制：当前机器从 Git Bash 启动 Go 会出现标准库路径/构建缓存权限异常，`init.sh` 无法完整跑完；PowerShell 下等价 Go 命令和真实请求通过。厂家侧 B1/B2/B4/B5 契约缺口只影响阶段 4，不阻塞 Phase Q/M/D 的当前路径 @@ -35,7 +35,8 @@ | `tasks.md` `progress.md` | 已有 | 任务看板 / 执行流水（根目录） | | `scripts/` | 已有·不入库 | Python 联调脚本（硬编码真实凭据与身份证，勿提交） | | `config.yaml` | 已有·不入库 | 真实凭据；不要提交 | -| `mapping/` `pipeline/` 等 | 待建 | 后续任务 | +| `mapping/dict.go` | 已有 | 性别/民族/血型/RH/文化程度/职业/婚姻/医保/personSign 双向码表；未命中返回 `ValidationError` | +| `pipeline/` 等 | 待建 | 后续任务 | ## 已验证事实（写代码时直接依赖） @@ -70,8 +71,8 @@ python3 scripts/query_health_record.py ## 下一步 -1. T-102：`mapping/dict.go` 全量码表（含 56 项民族）。 -2. T-202：码表完成后进入健康档案映射与 checkId。 +1. T-202：`mapping/health_record.go` + `mapping/checkid.go`，基于码表和 JKDA 查询契约建立映射纯函数。 +2. T-205：映射单测基线。 ## 维护规则 diff --git a/mapping/dict.go b/mapping/dict.go new file mode 100644 index 0000000..259ee73 --- /dev/null +++ b/mapping/dict.go @@ -0,0 +1,244 @@ +package mapping + +import "fmt" + +type Direction string + +const ( + DirectionPHISToOSI Direction = "phis_to_osi" + DirectionOSIToPHIS Direction = "osi_to_phis" +) + +type ValidationError struct { + Field string + DictName string + Direction Direction + Code string +} + +func (e ValidationError) Error() string { + return fmt.Sprintf("mapping %s %s unknown code %q for %s", e.DictName, e.Direction, e.Code, e.Field) +} + +type Entry struct { + PHIS string + OSI string + Name string +} + +type Dict struct { + Name string + Field string + Entries []Entry +} + +func (d Dict) PHISToOSI(code string) (string, error) { + for _, entry := range d.Entries { + if entry.PHIS == code { + return entry.OSI, nil + } + } + return "", ValidationError{Field: d.Field, DictName: d.Name, Direction: DirectionPHISToOSI, Code: code} +} + +func (d Dict) OSIToPHIS(code string) (string, error) { + for _, entry := range d.Entries { + if entry.OSI == code { + return entry.PHIS, nil + } + } + return "", ValidationError{Field: d.Field, DictName: d.Name, Direction: DirectionOSIToPHIS, Code: code} +} + +func (d Dict) EntryByOSI(code string) (Entry, bool) { + for _, entry := range d.Entries { + if entry.OSI == code { + return entry, true + } + } + return Entry{}, false +} + +func (d Dict) Len() int { + return len(d.Entries) +} + +func (d Dict) Validate() error { + phisSeen := make(map[string]bool, len(d.Entries)) + osiSeen := make(map[string]bool, len(d.Entries)) + for _, entry := range d.Entries { + if entry.PHIS == "" || entry.OSI == "" { + return fmt.Errorf("%s contains empty code: %#v", d.Name, entry) + } + if phisSeen[entry.PHIS] { + return fmt.Errorf("%s duplicate PHIS code %q", d.Name, entry.PHIS) + } + if osiSeen[entry.OSI] { + return fmt.Errorf("%s duplicate OSI code %q", d.Name, entry.OSI) + } + phisSeen[entry.PHIS] = true + osiSeen[entry.OSI] = true + } + return nil +} + +func sameCodeDict(name, field string, entries ...Entry) Dict { + for i := range entries { + if entries[i].PHIS == "" { + entries[i].PHIS = entries[i].OSI + } + } + return Dict{Name: name, Field: field, Entries: entries} +} + +var SexDict = sameCodeDict("sex", "sexCode", + Entry{OSI: "0", Name: "未知"}, + Entry{OSI: "1", Name: "男"}, + Entry{OSI: "2", Name: "女"}, + Entry{OSI: "9", Name: "未说明"}, +) + +var BloodTypeDict = sameCodeDict("bloodType", "bloodTypeCode", + Entry{OSI: "1", Name: "A"}, + Entry{OSI: "2", Name: "B"}, + Entry{OSI: "3", Name: "O"}, + Entry{OSI: "4", Name: "AB"}, + Entry{OSI: "5", Name: "不详"}, +) + +var RhBloodDict = sameCodeDict("rhBlood", "rhBloodCode", + Entry{OSI: "1", Name: "阳性"}, + Entry{OSI: "2", Name: "阴性"}, + Entry{OSI: "3", Name: "不详"}, +) + +var EducationDict = sameCodeDict("education", "educationCode", + Entry{OSI: "10", Name: "研究生"}, + Entry{OSI: "20", Name: "本科"}, + Entry{OSI: "31", Name: "大专"}, + Entry{OSI: "41", Name: "中专"}, + Entry{OSI: "47", Name: "技校"}, + Entry{OSI: "60", Name: "高中"}, + Entry{OSI: "70", Name: "初中"}, + Entry{OSI: "80", Name: "小学"}, + Entry{OSI: "90", Name: "文盲"}, + Entry{OSI: "91", Name: "不详"}, +) + +var WorkDict = sameCodeDict("work", "workCode", + Entry{OSI: "0", Name: "负责人"}, + Entry{OSI: "1", Name: "专业技术人员"}, + Entry{OSI: "2", Name: "专业技术人员"}, + Entry{OSI: "3", Name: "办事人员"}, + Entry{OSI: "4", Name: "商业服务业人员"}, + Entry{OSI: "5", Name: "农林牧渔人员"}, + Entry{OSI: "9", Name: "生产运输人员"}, + Entry{OSI: "X", Name: "军人"}, + Entry{OSI: "Y", Name: "其他"}, + Entry{OSI: "8", Name: "无职业"}, +) + +var MaritalStatusDict = sameCodeDict("maritalStatus", "maritalStatusCode", + Entry{OSI: "10", Name: "未婚"}, + Entry{OSI: "20", Name: "已婚"}, + Entry{OSI: "30", Name: "丧偶"}, + Entry{OSI: "40", Name: "离婚"}, + Entry{OSI: "90", Name: "未说明"}, +) + +var InsuranceDict = sameCodeDict("insurance", "insuranceCode", + Entry{OSI: "01", Name: "城镇职工"}, + Entry{OSI: "02", Name: "城乡居民"}, + Entry{OSI: "04", Name: "贫困救助"}, + Entry{OSI: "05", Name: "商业"}, + Entry{OSI: "06", Name: "全公费"}, + Entry{OSI: "07", Name: "全自费"}, + Entry{OSI: "99", Name: "其他"}, +) + +var PersonSignDict = sameCodeDict("personSign", "personSign", + Entry{OSI: "PU", Name: "普通"}, + Entry{OSI: "GRQY", Name: "已签约"}, + Entry{OSI: "LAO", Name: "老年"}, + Entry{OSI: "GAO", Name: "高血压"}, + Entry{OSI: "TANG", Name: "糖尿病"}, + Entry{OSI: "FU", Name: "孕产妇"}, + Entry{OSI: "ER", Name: "儿童"}, + Entry{OSI: "FEI", Name: "肺结核"}, + Entry{OSI: "JING", Name: "精神障碍"}, + Entry{OSI: "CAN", Name: "残疾"}, +) + +var NationDict = sameCodeDict("nation", "nationCode", + Entry{OSI: "01", Name: "汉族"}, + Entry{OSI: "02", Name: "蒙古族"}, + Entry{OSI: "03", Name: "回族"}, + Entry{OSI: "04", Name: "藏族"}, + Entry{OSI: "05", Name: "维吾尔族"}, + Entry{OSI: "06", Name: "苗族"}, + Entry{OSI: "07", Name: "彝族"}, + Entry{OSI: "08", Name: "壮族"}, + Entry{OSI: "09", Name: "布依族"}, + Entry{OSI: "10", Name: "朝鲜族"}, + Entry{OSI: "11", Name: "满族"}, + Entry{OSI: "12", Name: "侗族"}, + Entry{OSI: "13", Name: "瑶族"}, + Entry{OSI: "14", Name: "白族"}, + Entry{OSI: "15", Name: "土家族"}, + Entry{OSI: "16", Name: "哈尼族"}, + Entry{OSI: "17", Name: "哈萨克族"}, + Entry{OSI: "18", Name: "傣族"}, + Entry{OSI: "19", Name: "黎族"}, + Entry{OSI: "20", Name: "傈僳族"}, + Entry{OSI: "21", Name: "佤族"}, + Entry{OSI: "22", Name: "畲族"}, + Entry{OSI: "23", Name: "高山族"}, + Entry{OSI: "24", Name: "拉祜族"}, + Entry{OSI: "25", Name: "水族"}, + Entry{OSI: "26", Name: "东乡族"}, + Entry{OSI: "27", Name: "纳西族"}, + Entry{OSI: "28", Name: "景颇族"}, + Entry{OSI: "29", Name: "柯尔克孜族"}, + Entry{OSI: "30", Name: "土族"}, + Entry{OSI: "31", Name: "达斡尔族"}, + Entry{OSI: "32", Name: "仫佬族"}, + Entry{OSI: "33", Name: "羌族"}, + Entry{OSI: "34", Name: "布朗族"}, + Entry{OSI: "35", Name: "撒拉族"}, + Entry{OSI: "36", Name: "毛南族"}, + Entry{OSI: "37", Name: "仡佬族"}, + Entry{OSI: "38", Name: "锡伯族"}, + Entry{OSI: "39", Name: "阿昌族"}, + Entry{OSI: "40", Name: "普米族"}, + Entry{OSI: "41", Name: "塔吉克族"}, + Entry{OSI: "42", Name: "怒族"}, + Entry{OSI: "43", Name: "乌孜别克族"}, + Entry{OSI: "44", Name: "俄罗斯族"}, + Entry{OSI: "45", Name: "鄂温克族"}, + Entry{OSI: "46", Name: "德昂族"}, + Entry{OSI: "47", Name: "保安族"}, + Entry{OSI: "48", Name: "裕固族"}, + Entry{OSI: "49", Name: "京族"}, + Entry{OSI: "50", Name: "塔塔尔族"}, + Entry{OSI: "51", Name: "独龙族"}, + Entry{OSI: "52", Name: "鄂伦春族"}, + Entry{OSI: "53", Name: "赫哲族"}, + Entry{OSI: "54", Name: "门巴族"}, + Entry{OSI: "55", Name: "珞巴族"}, + Entry{OSI: "56", Name: "基诺族"}, + Entry{OSI: "99", Name: "其他"}, +) + +func AllDicts() []Dict { + return []Dict{ + SexDict, + BloodTypeDict, + RhBloodDict, + EducationDict, + WorkDict, + MaritalStatusDict, + InsuranceDict, + NationDict, + PersonSignDict, + } +} diff --git a/mapping/dict_test.go b/mapping/dict_test.go new file mode 100644 index 0000000..a4ad9b3 --- /dev/null +++ b/mapping/dict_test.go @@ -0,0 +1,112 @@ +package mapping + +import ( + "errors" + "fmt" + "testing" +) + +func TestDictTranslatesPHISToOSIAndOSIToPHIS(t *testing.T) { + got, err := SexDict.PHISToOSI("1") + if err != nil { + t.Fatalf("PHISToOSI: %v", err) + } + if got != "1" { + t.Fatalf("PHISToOSI = %q, want 1", got) + } + + got, err = SexDict.OSIToPHIS("2") + if err != nil { + t.Fatalf("OSIToPHIS: %v", err) + } + if got != "2" { + t.Fatalf("OSIToPHIS = %q, want 2", got) + } +} + +func TestDictReturnsValidationErrorForUnknownCode(t *testing.T) { + _, err := SexDict.PHISToOSI("bad") + if err == nil { + t.Fatal("PHISToOSI accepted unknown code") + } + var validationErr ValidationError + if !errors.As(err, &validationErr) { + t.Fatalf("error type = %T, want ValidationError", err) + } + if validationErr.Field != "sexCode" || validationErr.Code != "bad" || validationErr.Direction != DirectionPHISToOSI { + t.Fatalf("validation error = %#v", validationErr) + } +} + +func TestNationDictContains56EthnicGroupsAndOther(t *testing.T) { + if got := NationDict.Len(); got != 57 { + t.Fatalf("NationDict.Len = %d, want 57 including 99 other", got) + } + checks := map[string]string{ + "01": "汉族", + "02": "蒙古族", + "10": "朝鲜族", + "56": "基诺族", + "99": "其他", + } + for code, wantName := range checks { + entry, ok := NationDict.EntryByOSI(code) + if !ok { + t.Fatalf("NationDict missing code %s", code) + } + if entry.Name != wantName { + t.Fatalf("NationDict[%s].Name = %q, want %q", code, entry.Name, wantName) + } + got, err := NationDict.PHISToOSI(code) + if err != nil { + t.Fatalf("Nation PHISToOSI(%s): %v", code, err) + } + if got != code { + t.Fatalf("Nation PHISToOSI(%s) = %q", code, got) + } + } +} + +func TestNationDictContainsAllCodesFrom01To56(t *testing.T) { + for i := 1; i <= 56; i++ { + code := fmt.Sprintf("%02d", i) + if _, ok := NationDict.EntryByOSI(code); !ok { + t.Fatalf("NationDict missing code %s", code) + } + } +} +func TestCoreDictsContainDocumentedValues(t *testing.T) { + tests := []struct { + name string + dict Dict + code string + want string + }{ + {name: "blood", dict: BloodTypeDict, code: "4", want: "AB"}, + {name: "rh", dict: RhBloodDict, code: "2", want: "阴性"}, + {name: "education", dict: EducationDict, code: "31", want: "大专"}, + {name: "work", dict: WorkDict, code: "Y", want: "其他"}, + {name: "marital", dict: MaritalStatusDict, code: "40", want: "离婚"}, + {name: "insurance", dict: InsuranceDict, code: "99", want: "其他"}, + {name: "personSign", dict: PersonSignDict, code: "GRQY", want: "已签约"}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + entry, ok := tt.dict.EntryByOSI(tt.code) + if !ok { + t.Fatalf("missing code %s", tt.code) + } + if entry.Name != tt.want { + t.Fatalf("name = %q, want %q", entry.Name, tt.want) + } + }) + } +} + +func TestAllDictsRejectDuplicateCodes(t *testing.T) { + for _, dict := range AllDicts() { + if err := dict.Validate(); err != nil { + t.Fatalf("%s Validate: %v", dict.Name, err) + } + } +} diff --git a/progress.md b/progress.md index ca055a1..be010cb 100644 --- a/progress.md +++ b/progress.md @@ -126,3 +126,10 @@ - 验证：按 TDD 先运行 `go test ./osi -run "TestFind(HealthRecord|Rqbj)" -count=1`，因 `FindHealthRecord`/`FindRqbj` 与查询类型未定义失败；实现后目标测试通过。随后 `go test . -run TestRunJKDAFindCheckUsesConfiguredOSIClient -count=1` 通过，`go test ./...` 通过；使用本地环境变量发起正式 Go Find 真实请求，返回 `JKDA00002 code=01 message=操作成功 data_count=1`。 - 决策：FindRqbj 已有 serviceId/path 与 `personSign` 契约，先以单测覆盖；当前只对 JKDA00002 Find 做真实请求验收，因为本地已有可查档案样本。 - 下一步：T-102（`mapping/dict.go` 全量码表）。 +## 2026-07-07 T-102 映射码表基线 + +- 状态：DONE +- 变更：新增 `mapping/dict.go` 与 `mapping/dict_test.go`；建立通用 `Dict`/`Entry` 双向查表结构和 `ValidationError`；落地性别、民族（01~56 + 99 其他）、血型、RH、文化程度、职业、婚姻、医保、人群标记 `personSign` 初始码表。 +- 验证：按 TDD 先运行 `go test ./mapping -count=1`，因 `SexDict`/`Dict`/`ValidationError` 等未定义失败；实现后 `go test ./mapping -count=1` 通过；补充民族 `01~56` 连续码检查后再次通过。最终 `go test ./...` 通过，`go build ./...` 通过。 +- 决策：当前文档未给 PHIS 侧差异码值，T-102 先以 PHIS 与 OSI 同码作为静态基线；保留 `Entry{PHIS, OSI}` 结构，后续 T-202 若发现 PHIS 码值差异可局部覆盖，不改调用方。 +- 下一步：T-202（`mapping/health_record.go` + `mapping/checkid.go`）。 diff --git a/tasks.md b/tasks.md index 976a73b..8b09d36 100644 --- a/tasks.md +++ b/tasks.md @@ -49,7 +49,7 @@ | ID | 任务 | 依赖 | 验收要点 | 状态 | | --- | --- | --- | --- | --- | -| T-102 | `mapping/dict.go` 全量码表（含 56 项民族） | T-001 | 双向查表；未命中显式 ValidationError；单测覆盖（静态枚举，不走网络） | TODO | +| T-102 | `mapping/dict.go` 全量码表（含 56 项民族） | T-001 | 双向查表；未命中显式 ValidationError；单测覆盖（静态枚举，不走网络） | DONE | | T-202 | `mapping/health_record.go` + `mapping/checkid.go` | T-102, T-201 | 映射纯函数 + 结构化校验错误；主数据经 `MapContext` 字典快照注入（单测塞假快照）；checkId 确定性生成单测 | TODO | | T-205 | 映射单测基线：docx 样例 + 联调样本 | T-202 | `go test ./mapping/...` 全绿；必填/码表/格式校验生效 | TODO |