ilaandClaude Opus 4.8
8d54ad38d5
- 整理 server 模式 5 个查询端点（档案 find + 体检 last/all/list） - 参数/上游 serviceId/返回形态/PII 警示/通用约定 - README 导航登记；CLAUDE.md 同步表加端点→docs/07 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
180 lines
10 KiB
Markdown
180 lines
10 KiB
Markdown
# CLAUDE.md
|
||
|
||
适用于 `chis_osi` 仓库的 Claude Code 协作规则。
|
||
|
||
> **当前为 pre-code 阶段**：已 git 管理，仅有设计文档与源材料，代码骨架尚未建立（见路线图阶段 0）。
|
||
|
||
---
|
||
|
||
## 会话启动
|
||
|
||
1. 读 `docs/current-state.md` — 当前快照、已验证事实、blocker
|
||
2. 读 `tasks.md` — 任务看板；一次只领一个 `TODO` 且依赖均 `DONE` 的任务
|
||
3. 执行 `git log --oneline -10` — 了解上次做到哪里
|
||
4. 需要背景再读 `docs/README.md`（文档导航）与 `docs/05-实施路线图.md`（阶段全景）
|
||
|
||
> 需要架构细节读 `docs/03-目标架构设计.md`；需要接口字段/码表读 `docs/01-OSI接口规范分析.md` 与 `docs/04-字段与接口映射.md`（**§8 为联调实测契约，优先级高于 docx 整理**）。
|
||
|
||
> 用户说"继续开发""继续上次的"时，完成以上步骤后直接接续，不重新介绍项目背景。
|
||
|
||
### 三件套职责（完成任务后同步）
|
||
|
||
| 工件 | 性质 | 维护方式 |
|
||
|------|------|---------|
|
||
| `tasks.md` | 任务看板 | 领取改 `DOING`，验收通过改 `DONE`；标 DONE 需有 `progress.md` 里的验证证据 |
|
||
| `progress.md` | 执行流水 | **只追加**：变更/验证命令与结果/阻塞/决策/下一步 |
|
||
| `docs/current-state.md` | 当前快照 | **覆盖更新**：目录现实、可运行命令、blocker、下一步 |
|
||
|
||
统一验证入口：`./init.sh`（阶段 0 骨架未建立前会主动失败并提示 T-001，属预期）。
|
||
|
||
---
|
||
|
||
## 项目定位
|
||
|
||
**chis_osi**——对接「广东省基层医疗机构管理系统（CHIS）」厂家（和宇健康科技）提供的**官方统一对外服务接口（OSI）**，
|
||
把上游 PHIS（公卫系统）数据转换并投递到省基卫平台。
|
||
|
||
- **当前阶段**：设计完成、待编码（脚手架尚未建立，见路线图阶段 0）
|
||
- **语言/运行**：Go 1.24，单二进制 + 子命令（`main.go -mode server|deliver`，沿用 chis_upload 风格）
|
||
- **团队定位**：默认由初级程序员维护，所有改动优先保证可读、可理解、可接手，避免过度抽象
|
||
- **核心链路**：PHIS（拉取）→ 字段映射 → MD5 签名 + 统一信封 → CHIS OSI（POST `/osi/api/...`）→ 状态回写
|
||
|
||
**关键架构判断（务必牢记）：**
|
||
OSI 是**无状态服务端接口**，鉴权 = 请求头 MD5 签名（`password=md5("ts=<ts>&ask=<ask>")` 32 位小写）。
|
||
参考项目 `/mnt/d/GoP/chis_upload`（逆向 Chrome F12 实现）里的 SM2 登录 / Cookie / Redis 会话 / 身份链反查 / 网页报文对齐这部分复杂度**在本项目不存在、不要引入**。
|
||
本项目核心资产是 **PHIS→OSI 表驱动字段映射层** 与 **投递流水线**（重试分类/幂等/熔断/批次报告），幂等键用 OSI 的 `checkId`。
|
||
|
||
源材料：`docs/统一对外服务接口文档-.docx`（OSI 规范 V1.5.7）、`docs/广东省基层...需要的接口.xlsx`（本期 25 个接口）。这两份是厂家标注"内部资料注意保密"的材料，**已在 `.gitignore` 中排除、不入库**，仅本地随项目留存；接口契约的事实来源以 `docs/01`、`docs/04` 的整理结论为准。
|
||
|
||
---
|
||
|
||
## 目录职责
|
||
|
||
> 以下为**目标**结构（见 `docs/03-目标架构设计.md` 第 3 节），多数目录尚未创建，按路线图阶段逐步建立。
|
||
|
||
> 采用**扁平布局**（顶层平铺包，不用 `internal/`/`cmd/`），与 `chis_upload` 同款形状。
|
||
|
||
| 目录 | 说明 |
|
||
|------|------|
|
||
| `main.go` | 单入口：`-mode server\|deliver`（同步投递 API / 定时投递 worker） |
|
||
| `osi/` | ★ 薄客户端：签名、传输、`Call`、各业务域调用方法 |
|
||
| `contract/` | ★ 校验后的接口契约（结构体 + serviceId 常量），docx 坑点的唯一修正点 |
|
||
| `mapping/` | ★ PHIS→OSI 字段/字典映射 + checkId 生成（本项目核心） |
|
||
| `source/` | PHIS 拉取客户端 + 任务模型 + 状态回写 |
|
||
| `pipeline/` | 投递编排：校验→映射→调用→分类重试→幂等→熔断→报告 |
|
||
| `observ/` `store/` | report log（redis 优先、文件降级）/ redis(可选)+文件存储 |
|
||
| `handler/` `router/` | server 模式对外 HTTP 接口与路由 |
|
||
| `config/` | viper 读取配置（osi / phis / redis / proxy） |
|
||
| `docs/` | 所有设计文档，与代码同等重要 |
|
||
|
||
---
|
||
|
||
## 修改原则
|
||
|
||
- 先读现有实现和相关文档，再动手；优先最小化改动范围。
|
||
- 已有实现可复用时，不新增平行实现。
|
||
- 先定位根因，再修复问题，不做只遮盖现象的补丁。
|
||
- 非任务要求，不改对外接口字段、返回结构、配置键名、文件名、编码。
|
||
- 涉及**签名逻辑、serviceId 常量、checkId 生成、码表、幂等存储**时必须保守处理——它们直接影响平台对账与重复建档。
|
||
- **不照搬 docx 字段表**：docx 有复制粘贴错误（serviceId 串台、字段名/类型不一致，见 `docs/01` 第 7 节）。以 `contract/` + 联调真实样本为准。
|
||
- 架构或字段映射发生变化时，同步更新 `docs/` 对应文件（`docs/03` 架构、`docs/04` 字段映射），不让代码改了文档没跟上。
|
||
|
||
---
|
||
|
||
## 技术约定
|
||
|
||
### 通用
|
||
- **语言**：Go 1.24，**优先标准库**，谨慎引入第三方依赖。
|
||
- **注释**：必要的中文注释，只写 WHY 不写 WHAT；重点注释业务规则不直观处（字段映射、码表、分支判定）、外部系统约束（OSI 固定字段/签名规则）、易误改的关键路径（签名、checkId、幂等）。
|
||
- **错误**：显式处理不吞错；**命名**直接表达用途，避免过度抽象。
|
||
|
||
### osi（薄客户端）
|
||
- 签名只在 `osi` 层完成，业务层无感；用 `crypto/md5` 即可，**不引入 SM2/任何加密库**。
|
||
- `ts` 取 13 位毫秒；`password` 取 32 位小写；`ask` **仅参与签名**，不进请求头、不进报文、不进日志。
|
||
- 返回判定集中在 `codes.go`：成功码为**字符串**，联调实测 `"01"`（docx 误写 `"1"`），判定按去前导零 == `"1"`；`405` 超时（可重试）；其它失败。
|
||
- 传输层移植自 `chis_upload`（保留 SOCKS5/超时，**去掉 cookiejar 与网页拟态头**）。
|
||
|
||
### mapping（核心）
|
||
- 码表集中 `dict.go`，双向查表，**未命中显式报 ValidationError，绝不静默置空**。
|
||
- 映射函数为纯函数，返回结构化校验错误，便于用文档样例 + 联调样本单测。
|
||
- `checkId` 必须**确定性生成**：同一源记录重试得同一 checkId，防止平台重复建档。
|
||
- 完整度（completeLevel/perfection）**默认不本地计算**，依赖平台；联调确认需自算后再移植旧逻辑。
|
||
|
||
### pipeline / 可观测
|
||
- 重试分类：网络错误 / HTTP 5xx / 429 / `code==405` 可重试；参数错、权限错、映射校验错不可重试；退避 `2s*attempt`，最多 3 次。
|
||
- 幂等键 = `checkId`；存储 redis 优先、本地 JSON 降级。
|
||
- Redis 完全可选：启动失败不阻断（沿用 `chis_upload` 行为）。
|
||
- 一套 report log，不重建 apitrace/snapshot 多套追踪。
|
||
|
||
---
|
||
|
||
## 安全要求
|
||
|
||
- **严禁**将 `ask` 密钥、`orgCode`/`userName`/`deviceSN`、PHIS token、真实账号、含真实地址的配置提交到 git。
|
||
- `ask` 等敏感项走环境变量或部署密文，不写进仓库配置、不打印到日志。
|
||
- 配置示例用 `config.yaml.example`（占位值，不含真实地址与密钥）。
|
||
- 不提交 `logs/`、快照、抓包样本中含真实身份证/个人信息的文件。
|
||
|
||
---
|
||
|
||
## 验证要求
|
||
|
||
改动完成后做最小必要验证：
|
||
|
||
- **签名改动**：单测校验 `password` 形态（32 位小写）+ 用最简查询接口（机构查询 CXJG00002）打通真实请求。
|
||
- **映射改动**：补/跑 `mapping` 单测，用 docx 样例与联调样本对齐；确认必填/码表/格式校验生效。
|
||
- **投递流水线改动**：跑批确认批次报告字段（total/success/failed/skipped/retry）与幂等跳过、熔断行为正确。
|
||
- 至少执行 `go test ./...` 或与改动最相关的包级测试；无法验证时说明原因和风险。
|
||
|
||
---
|
||
|
||
## 文档同步要求
|
||
|
||
代码和文档同步，不允许代码改了文档没跟上。完成一组相关改动（1~3 个功能/修复/重构）后，自主判断是否同步更新 `docs/`，无需用户提醒。
|
||
|
||
| 发生什么 | 必须更新 |
|
||
|---------|---------|
|
||
| 架构或分层发生变化 | `docs/03-目标架构设计.md` |
|
||
| serviceId / 接口路径 / 字段映射 / 码表校准 | `docs/01-OSI接口规范分析.md`、`docs/04-字段与接口映射.md` |
|
||
| 本项目对外 HTTP 端点增改 | `docs/07-本项目HTTP接口.md` |
|
||
| 联调确认了开放问题（完整度 / checkId 规则 / 缺漏接口等） | `docs/03` 第 8 节、`docs/04` 第 7 节待补清单 |
|
||
| 阶段推进或验收通过 | `docs/05-实施路线图.md` 勾选项与阶段状态 |
|
||
| 任务领取/完成/受阻 | `tasks.md` 状态 + `progress.md` 追加记录（含验证证据）+ `docs/current-state.md` 覆盖快照 |
|
||
| 做了重要技术决策 | `docs/decisions/00N-简短描述.md`（背景 / 决策 / 原因 / 影响） |
|
||
|
||
---
|
||
|
||
## 提交规范
|
||
|
||
> 提交、推送仅在用户要求时进行。代码按每个逻辑改动单独 commit。
|
||
|
||
格式：`<type>(<scope>): <简短描述>`
|
||
|
||
| type | 用途 | | scope | 对应 |
|
||
|------|------|---|------|------|
|
||
| `feat` | 新功能 | | `osi` | 薄客户端 |
|
||
| `fix` | 修复问题 | | `mapping` | 字段/码表映射 |
|
||
| `docs` | 文档变更 | | `pipeline` | 投递流水线 |
|
||
| `refactor` | 重构（不改功能） | | `contract` | 接口契约 |
|
||
| `chore` | 构建/配置/依赖 | | `phis` | 任务源 |
|
||
| `test` | 测试相关 | | `config` `handler` … | 其余包/文档 |
|
||
|
||
```
|
||
feat(osi): 实现 MD5 头签名与统一 Call
|
||
feat(mapping): 落地健康档案字段映射与 checkId 生成
|
||
docs: 校准 jkda serviceId 并更新接口映射文档
|
||
chore: 初始化 go module 与双子命令骨架
|
||
```
|
||
|
||
---
|
||
|
||
## 提交前检查
|
||
|
||
- [ ] 未改动无关文件，未引入不必要重构或第三方依赖
|
||
- [ ] 未硬编码 `ask` 密钥、机构码、账号、PHIS token、服务器地址
|
||
- [ ] 未提交 `config.yaml`、`logs/`、含个人信息的样本
|
||
- [ ] 未留下临时代码、调试输出、未说明的 `TODO`
|
||
- [ ] serviceId / 字段映射 / 架构变更已同步更新 `docs/` 对应文件
|
||
- [ ] 重要技术决策已补 `docs/decisions/` ADR 文件
|
||
- [ ] `go test ./...` 通过（或说明未验证的原因与风险）
|