chis_osi/docs/README.md

chis_osi 对接设计文档

本目录是「广东省基层医疗机构管理系统（CHIS）统一对外服务接口（OSI）」对接项目 chis_osi 的设计文档集。

背景

省基卫厂家（和宇健康科技）已提供官方服务端对接接口《统一对外服务接口 API 规范文档 V1.5.7》。 本项目基于该官方接口重新对接，并参考既有项目 chis_upload（通过逆向 Chrome F12 网页接口实现）的工程经验， 设计一套更简洁、更稳定、更易维护的整体架构。

关键判断：官方 OSI 接口是无状态的服务端到服务端 JSON 接口，鉴权方式为请求头 MD5 签名。 这意味着 chis_upload 中为对付网页逆向而引入的大量复杂度（SM2 登录加密、Cookie/Redis 会话、 身份链路反查、Chrome 报文对齐补齐）在新项目中可以整体删除。新项目的核心复杂度从「如何骗过网页」 转移到「如何把上游 PHIS 数据正确映射成 OSI 文档约定的字段」。

文档索引

文档	内容
01-OSI接口规范分析.md	官方 OSI 接口的鉴权、报文约定、全量接口清单与 serviceId 映射、文档坑点
02-旧项目架构评估.md	chis_upload 的分层与组件、哪些复杂度由逆向驱动、哪些经验值得保留
03-目标架构设计.md	chis_osi 的整体架构、分层、目录结构、数据流与时序、关键设计决策
04-字段与接口映射.md	OSI 接口↔内部能力映射、PHIS→OSI 字段/字典映射策略、checkId 幂等键
05-实施路线图.md	分阶段落地计划、配置项、可观测性、测试与联调清单
06-厂家联调清单.md	向厂家索要的凭据/环境/契约/样本清单，带回填状态，可直接发对接人
07-本项目HTTP接口.md	本项目 server 模式对外提供的 HTTP 查询端点（我方接口的事实来源）
openapi.yaml	本项目 server 模式 HTTP 查询端点的 OpenAPI 3.0 机器可读接口文档
current-state.md	当前实现状态快照（可覆盖）：仓库现实、已验证事实、可运行命令、blocker

执行工件（根目录）

文件	作用
../CLAUDE.md	仓库级硬规则（Claude Code 入口，唯一权威规则源）
../AGENTS.md	通用 agent 薄入口，导航到 CLAUDE.md 与三件套
../tasks.md	任务看板：小步任务 + 依赖 + 验收 + 状态，一次只领一个
../progress.md	执行流水（只追加）：每轮变更/验证/阻塞/决策
../init.sh	统一启动与验证入口（Go 骨架建立后：download → test → run）

维护原则：需求/契约变化先改文档再改代码；任务状态变化同步 tasks.md + progress.md + current-state.md；接口契约以 01/04（含 §8 实测）为准，代码不得另起一套。

一句话结论

用一个无状态 OSI 客户端（MD5 签名 + 统一信封） + 一个表驱动的 PHIS→OSI 映射层 + 一个复用旧项目经验的投递流水线（校验/映射/签名/调用/分类重试/幂等/批次报告）， 替代旧项目里因网页逆向而堆积的会话与补齐逻辑。