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

# 05 · 实施路线图

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

---

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

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

> **执行顺序注记**：`tasks.md` 已按"查询先行"重排为 Q（查询）→ M（映射）→ D（字典+创建）。
> 原因：查询档案(Find)不依赖字典、映射单测只需码表+假字典快照，只有真实创建闭环才需字典反查主数据。
> 下面阶段 1/2 是能力全景，实际领取顺序以 `tasks.md` 为准。

## 阶段 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 → 平台返回成功码（实测 `"01"`）与 `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 会话/身份链）。
- 映射层：**与旧项目相当或略增**（但从"逆向猜"变为"照文档写"，更确定、更可测）。
- 投递流水线：**基本复用**旧项目经验，少量适配。
- 净效果：总复杂度显著下降，且代码意图清晰可交接。