98 lines
5.6 KiB
Markdown
98 lines
5.6 KiB
Markdown
# 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` 路由）。
|
||
- [x] Phase 0 review hardening：传输层默认 Accept-Encoding: identity、移除未使用 http.Client 残留、联调身份证改走 OSI_VERIFY_ID_CARD、删除 Envelope 顶层冗余 BaseInfo。
|
||
- **验收**：Go 侧用 JKDA00002 发真实请求，拿到 `code="01" message="操作成功"`；`init.sh` 已配置为依次执行依赖下载、测试、启动命令；review hardening 后 `go test ./...`、`go build ./...` 通过。
|
||
|
||
> **执行顺序注记**：`tasks.md` 已按"查询先行"重排为 Q（查询）→ M（映射）→ D（字典+创建）。
|
||
> 原因：查询档案(Find)不依赖字典、映射单测只需码表+假字典快照，只有真实创建闭环才需字典反查主数据。
|
||
> 下面阶段 1/2 是能力全景，实际领取顺序以 `tasks.md` 为准。
|
||
|
||
## 阶段 1 · 字典服务打通
|
||
|
||
- [ ] 实现 `public.go` 四个查询：网格/责任医生/药品/机构。
|
||
- [x] `mapping/dict.go` 落地全部码表（含 56 项民族）。
|
||
- [ ] 字典缓存（内存 + redis 可选），供映射层反查 `regionCode/manaDoctorId/manaUnitId`。
|
||
- **验收**：能用真实机构码查到下级网格、责任医生、机构树。
|
||
|
||
## 阶段 2 · 健康档案闭环（第一条业务线）
|
||
|
||
- [x] `contract/jkda.go` 查询响应结构体（T-201；创建/更新请求结构体留到 T-206）。
|
||
- [x] `mapping/health_record.go` + `mapping/checkid.go`。
|
||
- [x] `osi/jkda.go`：Find/FindRqbj（T-203；Find 已真实请求验收，FindRqbj 已按文档契约单测覆盖）。
|
||
- [ ] `osi/jkda.go`：Create/Update（T-206，依赖映射与字典缓存）。
|
||
- [ ] `handler` + `router`：暴露 `/api/health-record/save`（server 模式联调用）。
|
||
- [x] 用 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 会话/身份链）。
|
||
- 映射层：**与旧项目相当或略增**（但从"逆向猜"变为"照文档写"，更确定、更可测）。
|
||
- 投递流水线：**基本复用**旧项目经验，少量适配。
|
||
- 净效果：总复杂度显著下降，且代码意图清晰可交接。
|
||
|