chis_osi/docs/current-state.md

# 当前实现状态

> 可覆盖的当前快照：记录仓库现实、可运行命令、blocker 和下一步，防止只看计划而忽略现状。
> 历史流水追加到 [`../progress.md`](../progress.md)；任务状态以 [`../tasks.md`](../tasks.md) 为准。

## 当前快照

- 日期：2026-07-16
- 阶段：**T-212 转换器、T-213 upsert 编排和 T-204 HTTP 适配已完成；健康档案本地写入链路就绪，真实写入验收由 T-215 单独受阻**；T-303 老年人生活自理能力评估查询代码完成、真实联调受阻
- 技术栈：Go 1.24 单二进制；`main.go -mode server|deliver`；配置读取使用 viper，支持环境变量覆盖；OSI 客户端已具备签名、信封、传输、基础判码、JKDA00002 Find、JKDA00005 FindRqbj（人群分类，已按实测 auto 路径校准）、JKDA00001 Create、JKDA00003 Update、LNRZLPG00002 老年人生活自理能力查询（待真实联调），以及 WGDZ/ZRYS/YPML/CXJG 四个公开查询薄封装
- 生产代码：`source/health_record.go` 承接 PHIS 档案 DTO 并剥离医生凭据；`mapping/health_record.go` 转换 JKDA 写入请求；`pipeline/health_record_upsert.go` 实现 query-first upsert；`POST /api/health-record/upsert` 接收 PHIS 信封，运行时加载医生/机构主数据并复用同一服务，返回脱敏结构化 outcome
- 联调现实：**JKDA00002 个人档案查询已用 Go 侧真实请求打通**，返回 `code="01" message="操作成功" data_count=1`；**公开查询 WGDZ00001/ZRYS00001/CXJG00002 已用真实档案主数据验证通过**，均返回 `code="01"` 且数组非空；药品目录 YPML00001 已完成客户端封装和单测，尚未做真实药品关键字样本验证；**JKDA00001 create 未跑真实请求**，避免在没有安全测试居民/写入授权时污染平台档案
- 测试：`go test ./...` 通过；除既有查询、契约、映射与 OSI 客户端测试外，已覆盖 upsert create/update/manual_review/retry/failed/error HTTP 映射、成功后收尾错误的 `retrySafe=false`、路由注册、运行时主数据加载，以及进程内租约 acquire/release/complete/stale token
- 标准启动路径：`./init.sh` 已配置三步：依赖下载、`go test ./...`、`go run . -mode server -config config.yaml.example`
- 标准验证路径：`go test ./...`、`go build ./...`
- 当前 blocker：T-215 真实 create/update 验收缺少可写入沙箱的安全测试居民资料或明确写入授权；PHIS 源键已在 T-212 固化为 `archId`，`addressNumber`、`createDate` 和逐档案 `operateUser` 仍需 T-215 写入后回查确认。软限制：当前机器从 Git Bash 启动 Go 会出现标准库路径/构建缓存权限异常，`init.sh` 无法完整跑完；PowerShell 下等价 Go 命令和真实查询通过。厂家侧 B1/B2/B4/B5 契约缺口只影响阶段 4

## 当前目录要点

| 路径 | 状态 | 说明 |
| --- | --- | --- |
| `main.go` | 已有 | 单入口，解析 `-mode server|deliver`、`-config`，并提供 `-verify-jkda` 联调验证入口（身份证从 `OSI_VERIFY_ID_CARD` 读取） |
| `config/` | 已有 | viper 配置加载，支持 `OSI_*` 等环境变量覆盖 |
| `contract/envelope.go` | 已有 | OSI 通用信封与 `manageInfo` 结构 |
| `contract/jkda.go` | 已有 | JKDA00002 查询响应结构体；JKDA00001/00003 创建更新请求结构体与保存结果结构体 |
| `osi/sign.go` | 已有 | OSI 请求头 MD5 签名与 headers 组装 |
| `osi/transport.go` | 已有 | OSI JSON POST 传输层；原始 HTTP/1.1 写请求以保留头名大小写；支持超时与可选 SOCKS5 |
| `osi/codes.go` | 已有 | serviceId 路由与成功/可重试判码；已包含 JKDA 查询/创建/更新与四个公开查询 serviceId |
| `osi/client.go` | 已有 | 通用 `Call`：签名头 + 查询信封 + 传输 + 响应解析；内部 `callUploadInfo` 支持创建/更新完整 uploadinfo |
| `osi/jkda.go` | 已有 | JKDA00001 Create、JKDA00003 Update、JKDA00002 Find、JKDA00005 FindRqbj（`/auto/jkda/findrqbj`） |
| `osi/public.go` | 已有 | WGDZ00001 网格、ZRYS00001 责任医生、YPML00001 药品、CXJG00002 机构查询 |
| `cache/dictionary.go` | 已有 | 公开字典内存快照；按名称反查 `regionCode`/`manaDoctorId`/`manaUnitId`；可选持久化失败不阻断 |
| `verify_jkda.go` | 已有 | JKDA00002 真实请求验证辅助入口 |
| `config.yaml.example` | 已有 | 占位配置，不含真实凭据 |
| `go.mod` `go.sum` | 已有 | module `chis_osi`，依赖 viper 与 `golang.org/x/net/proxy` |
| `docs/` | 已有 | 设计文档集 01~06 + 本快照；`docs/04 §9` 记录公开查询脱敏实测契约，`docs/04 §10` 记录创建/更新本地契约；`账号.txt` 本地留存不入库 |
| `tasks.md` `progress.md` | 已有 | 任务看板 / 执行流水（根目录） |
| `scripts/` | 已有·不入库 | Python 联调脚本（硬编码真实凭据与身份证，勿提交） |
| `config.yaml` | 已有·不入库 | 真实/本地配置；不要提交 |
| `mapping/dict.go` | 已有 | 性别/民族/血型/RH/文化程度/职业/婚姻/医保/personSign 双向码表；未命中返回 `ValidationError` |
| `mapping/health_record.go` `mapping/checkid.go` | 已有 | 健康档案映射草稿、字典快照注入、主数据反查、创建请求组装（含 createUser/createUnit 派生）、必填/码表校验、确定性 checkId |
| `mapping/health_record_baseline_test.go` | 已有 | docx 风格、联调风格、脏数据映射回归样本 |
| `handler/health_record.go` | 已有 | `GET /api/health-record/find` 档案查询、`GET /api/health-record/crowd` 人群分类查询，均回写平台完整响应 |
| `handler/health_check.go` | 已有 | 体检端点 `GET /api/health-check/last`（最近一次）+ `/all`（全部体检）+ `/list`（年度名单）|
| `handler/elderly.go` | 已有 | `GET /api/elderly/self-care` 老年人生活自理能力评估查询（待真实联调） |
| `handler/public.go` | 已有 | 公开查询端点 `GET /api/dictionaries/grid-addresses`、`/doctors`、`/drugs`、`/orgs` |
| `server.go` `osi_client.go` | 已有 | server 模式起 HTTP 服务、注册路由；`buildOSIClient` 共用构造（verify 与 server 复用） |
| `pipeline/health_record_upsert.go` | 已有 | T-213 query-first upsert 应用服务；外部客户端、原子幂等、报告与 PHIS 状态均接口注入，持久化待阶段 3 |
| `handler/health_record_upsert.go` | 已有 | `POST /api/health-record/upsert` 薄适配；1 MiB 限制、PHIS 信封解码、状态码映射、内部错误脱敏 |
| `health_record_upsert_runtime.go` | 已有 | server 模式加载责任医生/机构字典并组装 T-213 服务；HTTP 模式不执行 PHIS 回调 |
| `pipeline/memory_idempotency.go` | 已有 | T-204 同步 HTTP 的进程内 owner-token 并发租约；成功即释放，不缓存 completed，非阶段 3 持久化实现 |

## 已验证事实（写代码时直接依赖）

- 签名：`password = md5("ts=<13位毫秒ts>&ask=<ask>")` 32 位小写，与 Python `hashlib` 向量一致。
- 信封：查询也走 `{"serviceId", "uploadinfo": {"baseInfo", "manageInfo"}}`，见 `docs/04 §8` 与 `docs/04 §9`。
- 创建/更新信封：`baseInfo`、`manageInfo`、`healthRecord` 等节点在 `uploadinfo` 下同级；本地契约见 `docs/04 §10`，真实 create 样本待补。
- 成功码：字符串 `"01"`（判定按去前导零 == `"1"`），见 `docs/01 §1`。
- `405` 为平台服务调用超时，可重试。
- 机构码分层：请求头 `orgCode`=18 位统信码 ≠ `manaUnitId`=9 位机构码 ≠ 12 位区划码，见 `docs/01 §3`。
- `deviceSN` 查询可空。
- OSI 代理语义：`socks5_proxy` 非空即只对 OSI 客户端走 SOCKS5，不做直连回退。
- 真实平台/代理对请求头名大小写敏感；Go `net/http` 会规范化头名，OSI 传输层需保留 `orgCode/deviceSN/userName` 的原始大小写。裸写传输层默认请求 `Accept-Encoding: identity`，避免收到未解压压缩响应。
- 公开字典查询返回 `data` 数组；网格、责任医生、机构三类已真实验证可作为 T-103 字典缓存来源。
- `cache.DictionarySnapshot` 可作为 `mapping.MapContext.MasterData` 注入；PHIS 只有名称、缺平台码时，映射层可反查补齐主数据，未命中仍按必填错误处理。
- 创建请求侧门牌号字段为 `addressNumber`；查询响应侧实测字段为错拼 `adressNumber`，两者分开建模。

## 当前可运行内容

```bash
# Go 骨架验证
go test ./...
go build ./...
go test ./contract ./osi
go test ./cache ./mapping
go run . -mode deliver -config config.yaml.example

# 统一入口（当前 Git Bash 环境存在 Go 标准库/缓存权限限制）
./init.sh

# Go 侧 JKDA00002 联调验证（已实测查通，返回 code=01 data_count=1）
# config.yaml 已迁为 Go 嵌套 osi: 结构并从中读凭据；仅身份证走环境变量，不落文件/命令行历史
OSI_VERIFY_ID_CARD=<idCard> go run . -verify-jkda -config config.yaml

# server 模式 HTTP 查询端点（用真实 config.yaml，默认仅绑 127.0.0.1:8080）
go run . -mode server                 # 起服务（阻塞）
curl "http://127.0.0.1:8080/api/health-record/find?idCard=<idCard>"          # 档案（完整 JSON）
curl "http://127.0.0.1:8080/api/health-record/crowd?idCard=<idCard>"         # 人群分类/子档案标记
curl "http://127.0.0.1:8080/api/health-check/last?idCard=<idCard>"           # 最近一次体检
curl "http://127.0.0.1:8080/api/health-check/all?idCard=<idCard>"            # 某人全部体检（数组）
curl "http://127.0.0.1:8080/api/health-check/list?checkYear=2025&idCard=<idCard>"  # 年度已检/未检名单
curl "http://127.0.0.1:8080/api/elderly/self-care?idCard=<idCard>"                 # 老年人生活自理能力评估（待真实联调）
curl "http://127.0.0.1:8080/api/dictionaries/grid-addresses?parentCode=<区划码>"       # 网格地址
curl "http://127.0.0.1:8080/api/dictionaries/doctors?manaUnitId=<机构码>"          # 责任医生
curl "http://127.0.0.1:8080/api/dictionaries/drugs?pageNo=1&ypmc=<药品名>"          # 药品目录（pageNo 必填）
curl "http://127.0.0.1:8080/api/dictionaries/orgs?parentId=<上级机构ID>"          # 机构查询
curl -X POST "http://127.0.0.1:8080/api/health-record/upsert" -H "Content-Type: application/json" --data-binary "@<phis-health-record.json>"  # 未获写入授权时禁止用真实居民

# 本地 Python 联调查询（脚本硬编码凭据，勿提交）
python3 scripts/query_health_record.py
```

## 下一步

> 2026-07-15 已把本地能力与真实验收拆开：T-206 标记本地 DONE，T-215 承接授权后的真实写入验收。

1. 并行催厂家：写入授权与可写测试档案、更新目标标识、逐档案 `operateUser` 最终规则。
2. 授权到位后执行 T-215 真实 create→query→update→query 验收。
3. 若授权继续等待，则把路线图阶段 3 的持久化幂等、报告和补偿调度拆成独立任务后实施。

## 维护规则

发生以下变化时覆盖更新本文：入口/目录变动、任务状态变化、新增可运行命令、发现文档与代码现实不一致。本文只留当前快照，不留历史。