chis_osi/docs/05-实施路线图.md

05 · 实施路线图

分阶段落地 chis_osi，每阶段都「可运行、可回归、可联调」，沿用旧项目"小步、可测、可交接"的节奏。

---

阶段 0 · 脚手架与契约骨架

• 初始化 Go module、单 main.go（-mode server|deliver）、config/（viper）。
• 落地 osi/sign.go（MD5 签名）+ 单测：用文档约定的 ts/ask 校验 password 形态（32 位小写）。
• 移植旧项目 transport.go/http_client.go → osi/transport.go（保留 SOCKS5/超时，去 cookiejar 与拟态头）。
• osi/client.go 的 Call(serviceId, body, out)：注入头+信封+发送+判码（code=="1"/405）。
• contract/envelope.go + osi/codes.go（serviceId 常量 + pathOf 路由）。
• 验收：对任一最简查询接口（如机构查询 CXJG00002）发真实请求，拿到 code/message。

阶段 1 · 字典服务打通

• 实现 public.go 四个查询：网格/责任医生/药品/机构。
• mapping/dict.go 落地全部码表（含 56 项民族）。
• 字典缓存（内存 + redis 可选），供映射层反查 regionCode/manaDoctorId/manaUnitId。
• 验收：能用真实机构码查到下级网格、责任医生、机构树。

阶段 2 · 健康档案闭环（第一条业务线）

• contract/jkda.go + mapping/health_record.go + mapping/checkid.go。
• osi/jkda.go：Create/Update/Find/FindRqbj。
• handler + router：暴露 /api/health-record/save（server 模式联调用）。
• 用 01 文档样例 + 联调样本写映射单测。
• 验收：一条 PHIS 档案 → 映射 → create → 平台返回 code:"1" 与 phrId；重复投递被幂等跳过。

阶段 3 · 投递流水线

• pipeline：deliver.go/retry.go/idempotency.go(checkId)/circuit.go/report.go。
• observ：一套 report log（redis 优先、文件降级）+ 快照 + trace。
• main.go -mode deliver：定时驱动（先用本地任务文件 mock，对齐旧项目可跑形态）。
• 验收：批量任务跑完出批次报告（total/success/failed/skipped/retry + 失败 Top）；网络不可达触发熔断且行为符合预期。

阶段 4 · 其余业务线

• 体检（JKTJ，字段最多，重点）、老年人自理评估、中医体质辨识、中医健康指导。
• 各自的 contract/mapping/osi 方法 + 单测。
• 验收：四类 dataType 均能走通 create/update/query。

阶段 5 · PHIS 真实接入与状态回写

• source：真实拉取接口替换 mock；任务模型对齐。
• 投递结果回写 PHIS（done/retry/failed），trace_id 用 PHIS 任务号贯穿。
• 验收：PHIS→chis_osi→CHIS 全链路自动跑通，状态可回查。

阶段 6 · 加固与交接

• 完整度问题定论（见开放问题 1）：若平台要求接入方算，移植旧项目 complete_level/perfection 到 mapping/。
• 配置/密钥走环境变量，osi_ask 不入库。
• docs/ 补 运维与排障.md、联调清单.md。
• go test ./... 全绿。

---

联调前置清单（向厂家索要）

1. 沙箱环境 hostname 与一组可用 orgCode/userName/ask/deviceSN/operateUser。
2. docx 缺漏的列表/查询接口路径与 serviceId（档案列表、自理/体质/中医指导列表与查询）。
3. 中医健康指导 zyjkzd 的字段表与 serviceId。
4. checkId 唯一性与去重规则；create/update 的幂等语义。
5. 完整度是否由平台计算。
6. 错误码字典（除 405 外）。
7. 每个创建接口的一组真实成功请求/响应样本（做映射回归基线）。

---

风险与对策

风险	对策
docx 字段表有错（serviceId 串台、字段名/类型不一致）	以 contract/ 为唯一修正点 + 联调样本回归（01 文档第 7 节）
列表/查询接口文档缺漏	阶段性向厂家索要，不阻塞创建类主线
码表庞大易错（民族 56 项等）	集中 dict.go + 单测覆盖 + 未命中显式报错
完整度算法不明	默认不算、依赖平台；联调定论后再决定是否移植旧逻辑
平台限流/超时	复用熔断 + 405 重试；投递并发可配
密钥泄露	ask 仅参与签名、走环境变量、不入库不入日志

---

工作量直觉（相对旧项目）

• 鉴权/会话/传输：大幅减少（无 SM2/登录/Cookie/Redis 会话/身份链）。
• 映射层：与旧项目相当或略增（但从"逆向猜"变为"照文档写"，更确定、更可测）。
• 投递流水线：基本复用旧项目经验，少量适配。
• 净效果：总复杂度显著下降，且代码意图清晰可交接。