From 6204da871e0785868f006299984fa327811c3f9a Mon Sep 17 00:00:00 2001 From: ila Date: Sat, 30 May 2026 12:17:41 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E7=9B=AE=E5=BD=95=E5=B8=83=E5=B1=80?= =?UTF-8?q?=E6=94=B9=E4=B8=BA=E6=89=81=E5=B9=B3=E7=BB=93=E6=9E=84=EF=BC=8C?= =?UTF-8?q?=E4=B8=8E=20chis=5Fupload=20=E5=AF=B9=E9=BD=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按团队 AGENTS.md 的扁平偏好，弃用 internal/+cmd/，改为顶层平铺包 + 单 main.go(-mode server|deliver)。同步更新 docs/03 目录结构图与 §4.4、 docs/05 路线图措辞、CLAUDE.md 目录职责表。 Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 18 +++++----- docs/03-目标架构设计.md | 74 ++++++++++++++++++++--------------------- docs/05-实施路线图.md | 6 ++-- 3 files changed, 50 insertions(+), 48 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index aedd152..82b8bc7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,7 +24,7 @@ 把上游 PHIS（公卫系统）数据转换并投递到省基卫平台。 - **当前阶段**：设计完成、待编码（脚手架尚未建立，见路线图阶段 0） -- **语言/运行**：Go 1.24，单二进制双子命令（`cmd/server` 同步 API、`cmd/deliver` 投递 worker） +- **语言/运行**：Go 1.24，单二进制 + 子命令（`main.go -mode server|deliver`，沿用 chis_upload 风格） - **团队定位**：默认由初级程序员维护，所有改动优先保证可读、可理解、可接手，避免过度抽象 - **核心链路**：PHIS（拉取）→ 字段映射 → MD5 签名 + 统一信封 → CHIS OSI（POST `/osi/api/...`）→ 状态回写 @@ -41,15 +41,17 @@ OSI 是**无状态服务端接口**，鉴权 = 请求头 MD5 签名（`password= > 以下为**目标**结构（见 `docs/03-目标架构设计.md` 第 3 节），多数目录尚未创建，按路线图阶段逐步建立。 +> 采用**扁平布局**（顶层平铺包，不用 `internal/`/`cmd/`），与 `chis_upload` 同款形状。 + | 目录 | 说明 | |------|------| -| `cmd/server/` `cmd/deliver/` | 双入口：同步投递 API / 定时投递 worker | -| `internal/osi/` | ★ 薄客户端：签名、传输、`Call`、各业务域调用方法 | -| `internal/contract/` | ★ 校验后的接口契约（结构体 + serviceId 常量），docx 坑点的唯一修正点 | -| `internal/mapping/` | ★ PHIS→OSI 字段/字典映射 + checkId 生成（本项目核心） | -| `internal/source/phis/` | PHIS 拉取客户端 + 任务模型 + 状态回写 | -| `internal/pipeline/` | 投递编排：校验→映射→调用→分类重试→幂等→熔断→报告 | -| `internal/observ/` `internal/store/` | report log（redis 优先、文件降级）/ redis(可选)+文件存储 | +| `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/` | 所有设计文档，与代码同等重要 | diff --git a/docs/03-目标架构设计.md b/docs/03-目标架构设计.md index 3730e8d..5d1860a 100644 --- a/docs/03-目标架构设计.md +++ b/docs/03-目标架构设计.md @@ -39,48 +39,48 @@ ## 3. 目录结构 +采用**扁平布局**（顶层平铺包、单 `main.go` + `-mode` 子命令），与参考项目 `chis_upload` 保持同款形状，降低团队接手成本。 +与 `chis_upload` 的差别只在"内容"——无 `chis/`(逆向)、无 `middleware/`(cookie)、无 SM2，新增 `osi/`/`mapping/`/`pipeline/`。 + ``` chis_osi/ -├── cmd/ -│ ├── server/ main：HTTP 服务入口 -│ └── deliver/ main：投递 worker 入口 -├── config/ viper 配置（osi/phis/redis/log/proxy） -├── internal/ -│ ├── osi/ ★ 薄客户端：与平台的全部交互 -│ │ ├── sign.go MD5 签名（ts + password） -│ │ ├── transport.go HTTP 发送、超时、SOCKS5 -│ │ ├── client.go Call(ctx, serviceId, body, &out)：注入头+信封+发送+判码 -│ │ ├── codes.go 返回码常量与成功/可重试判定 -│ │ ├── jkda.go 档案：Create/Update/Find/FindRqbj -│ │ ├── jktj.go 体检：Create/Update/Query/List/Last -│ │ ├── lnr.go 老年人：自理评估、中医体质辨识 -│ │ ├── zyjkzd.go 中医健康指导 -│ │ └── public.go 网格/责任医生/药品/机构 字典查询 -│ ├── contract/ ★ 校验后的接口契约（请求/响应结构体 + serviceId 常量） -│ │ ├── envelope.go 通用信封：{serviceId, uploadinfo|baseInfo, manageInfo} -│ │ ├── jkda.go / jktj.go / lnr.go / ... -│ ├── mapping/ ★ PHIS→OSI 映射（本项目核心） -│ │ ├── dict.go 码表：性别/民族/血型/职业/文化程度/婚姻/医保...（双向） -│ │ ├── health_record.go 档案字段映射 + 校验 -│ │ ├── health_check.go 体检字段映射 -│ │ ├── elderly.go 老年人映射 -│ │ └── checkid.go checkId 生成（确定性，幂等键来源） -│ ├── source/phis/ PHIS 拉取客户端 + 任务模型 + 状态回写 -│ ├── pipeline/ 投递编排：校验→映射→调用→分类→重试→幂等→报告 -│ │ ├── deliver.go 单条投递 -│ │ ├── retry.go 重试与错误分类 -│ │ ├── idempotency.go 基于 checkId 的去重存储（redis|file） -│ │ ├── circuit.go 熔断 -│ │ └── report.go 批次报告 -│ ├── observ/ report log（redis 优先，文件降级）+ 快照 + trace -│ └── store/ redis 客户端封装（可选）+ 文件存储 +├── main.go 入口：-mode server|deliver（沿用 chis_upload 的单入口 + flag 风格） +├── config/ viper 配置（osi/phis/redis/proxy） +├── osi/ ★ 薄客户端：与平台的全部交互 +│ ├── sign.go MD5 签名（ts + password） +│ ├── transport.go HTTP 发送、超时、SOCKS5 +│ ├── client.go Call(ctx, serviceId, body, &out)：注入头+信封+发送+判码 +│ ├── codes.go 返回码常量与成功/可重试判定 +│ ├── jkda.go 档案：Create/Update/Find/FindRqbj +│ ├── jktj.go 体检：Create/Update/Query/List/Last +│ ├── lnr.go 老年人：自理评估、中医体质辨识 +│ ├── zyjkzd.go 中医健康指导 +│ └── public.go 网格/责任医生/药品/机构 字典查询 +├── contract/ ★ 校验后的接口契约（请求/响应结构体 + serviceId 常量） +│ ├── envelope.go 通用信封：{serviceId, uploadinfo|baseInfo, manageInfo} +│ └── jkda.go / jktj.go / lnr.go / ... +├── mapping/ ★ PHIS→OSI 映射（本项目核心） +│ ├── dict.go 码表：性别/民族/血型/职业/文化程度/婚姻/医保...（双向） +│ ├── health_record.go 档案字段映射 + 校验 +│ ├── health_check.go 体检字段映射 +│ ├── elderly.go 老年人映射 +│ └── checkid.go checkId 生成（确定性，幂等键来源） +├── source/ PHIS 拉取客户端 + 任务模型 + 状态回写 +├── pipeline/ 投递编排：校验→映射→调用→分类→重试→幂等→报告 +│ ├── deliver.go 单条投递 +│ ├── retry.go 重试与错误分类 +│ ├── idempotency.go 基于 checkId 的去重存储（redis|file） +│ ├── circuit.go 熔断 +│ └── report.go 批次报告 +├── observ/ report log（redis 优先，文件降级）+ 快照 + trace +├── store/ redis 客户端封装（可选）+ 文件存储 ├── handler/ HTTP handlers（server 模式对外接口） ├── router/ 路由 ├── docs/ -└── AGENTS.md 沿用旧项目协作规范 +└── AGENTS.md / CLAUDE.md 协作规范 ``` -> `internal/` 用于约束包边界，避免被外部误用；若团队更习惯扁平结构，可去掉 `internal/` 层级，保持包名不变。 +> 不使用 `internal/` 与 `cmd/`：团队 `AGENTS.md` 偏好扁平、避免过度抽象，且 `chis_upload` 已是单 `main.go`+`-mode` 形态，保持一致优先于"标准 Go 布局"。 --- @@ -142,7 +142,7 @@ type ManageInfo struct { DSFMC, OperateUnit, OperateUser string } > 完整度（completeLevel/perfection）：默认**不本地计算**，按文档字段如实上送，依赖平台计算。 > 若联调发现平台要求接入方计算，再把旧项目 `health_record_complete_level.go`/`health_check_perfection.go` 移植进 `mapping/`（开放问题，见第 8 节）。 -### 4.4 `source/phis` —— 任务源 +### 4.4 `source` —— 任务源 - 拉取待上送明细（替代旧项目的本地 mock 文件）。 - 任务模型：`{taskId, dataType, payload(PHIS原始), ...}`。 @@ -177,7 +177,7 @@ type ManageInfo struct { DSFMC, OperateUnit, OperateUser string } ## 5. 关键时序：一条体检记录的投递 ``` -deliver-worker source/phis mapping osi.Client CHIS OSI +deliver-worker source mapping osi.Client CHIS OSI │ 拉取任务 │ │ │ │ │ ───────────────────▶│ │ │ │ │ ◀─ task(原始体检) │ │ │ │ diff --git a/docs/05-实施路线图.md b/docs/05-实施路线图.md index 27db42b..86ef3ec 100644 --- a/docs/05-实施路线图.md +++ b/docs/05-实施路线图.md @@ -6,7 +6,7 @@ ## 阶段 0 · 脚手架与契约骨架 -- [ ] 初始化 Go module、`cmd/server`、`cmd/deliver` 双入口、`config/`（viper）。 +- [ ] 初始化 Go module、单 `main.go`（`-mode server|deliver`）、`config/`（viper）。 - [ ] 落地 `osi/sign.go`（MD5 签名）+ 单测：用文档约定的 `ts/ask` 校验 `password` 形态（32 位小写）。 - [ ] 移植旧项目 `transport.go`/`http_client.go` → `osi/transport.go`（保留 SOCKS5/超时，去 cookiejar 与拟态头）。 - [ ] `osi/client.go` 的 `Call(serviceId, body, out)`：注入头+信封+发送+判码（`code=="1"`/`405`）。 @@ -32,7 +32,7 @@ - [ ] `pipeline`：`deliver.go`/`retry.go`/`idempotency.go`(checkId)/`circuit.go`/`report.go`。 - [ ] `observ`：一套 report log（redis 优先、文件降级）+ 快照 + trace。 -- [ ] `cmd/deliver`：定时驱动（先用本地任务文件 mock，对齐旧项目可跑形态）。 +- [ ] `main.go -mode deliver`：定时驱动（先用本地任务文件 mock，对齐旧项目可跑形态）。 - **验收**：批量任务跑完出批次报告（total/success/failed/skipped/retry + 失败 Top）；网络不可达触发熔断且行为符合预期。 ## 阶段 4 · 其余业务线 @@ -43,7 +43,7 @@ ## 阶段 5 · PHIS 真实接入与状态回写 -- [ ] `source/phis`：真实拉取接口替换 mock；任务模型对齐。 +- [ ] `source`：真实拉取接口替换 mock；任务模型对齐。 - [ ] 投递结果回写 PHIS（done/retry/failed），trace_id 用 PHIS 任务号贯穿。 - **验收**：PHIS→chis_osi→CHIS 全链路自动跑通，状态可回查。