docs: 新增 docs/07 本项目 HTTP 接口文档

- 整理 server 模式 5 个查询端点（档案 find + 体检 last/all/list）
- 参数/上游 serviceId/返回形态/PII 警示/通用约定
- README 导航登记；CLAUDE.md 同步表加端点→docs/07

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -136,6 +136,7 @@ OSI 是**无状态服务端接口**，鉴权 = 请求头 MD5 签名（`password=
 |---------|---------|
 | 架构或分层发生变化 | `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/07-本项目HTTP接口.md

@@ -0,0 +1,113 @@
+# 07 · 本项目 HTTP 接口
+
+`chis_osi` **server 模式**对外提供的 HTTP 查询接口——供前端/运维/PHIS 侧调用。
+
+> 这是本项目**自己**对外的接口的单一事实来源；调用**上游厂家 OSI** 的接口契约看 `docs/01`、`docs/04`。
+> 新增/修改端点后同步本文（与 `handler/`、`server.go` 保持一致）。
+
+---
+
+## 启动
+
+```bash
+go run . -mode server              # 默认监听 127.0.0.1:8080
+go run . -mode server -addr 127.0.0.1:9000   # 指定地址
+```
+
+凭据从 `config.yaml`（嵌套 `osi:` 段）读取；服务经 SOCKS5 代理访问内网 OSI 主机。
+
+⚠ **默认仅绑 `127.0.0.1`**：所有端点回写真实居民档案/体检（含身份证等 PII）。**切勿绑 `0.0.0.0` 或反代到公网**；确需对外必须自行加鉴权。
+
+---
+
+## 通用约定
+
+| 项 | 说明 |
+| --- | --- |
+| 方法 | 一律 `GET`，查询条件走 query string |
+| 成功响应 | **直接回写平台完整 JSON**（`{code,message,data}`，不裁字段），`Content-Type: application/json` |
+| 平台成功码 | `code="01"`（字符串，见 docs/01 §1）——本服务不改写，原样透传 |
+| 参数错误 | `400`，体为 `{"error":"..."}`（如缺必填标识符） |
+| 上游失败/网络错误 | `502`，体为 `{"error":"..."}` |
+| 方法不对 | `405` |
+
+> 设计取舍：端点**原样回写平台响应**（同 `Result.Raw`），不做字段裁剪/转换——保证平台未建模字段也能拿到，便于查看完整档案/体检。
+
+---
+
+## 端点清单
+
+### 1. 查询个人健康档案
+
+```
+GET /api/health-record/find
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `idCard` / `phrid` / `personName` / `empiId` | **四选一** | 查询标识符，只能给一个 |
+
+- 上游：`JKDA00002` `/auto/jkda/find`
+- 返回：`data` 为**数组**（档案聚合，含 healthRecord/pastHistory/既往史等，见 docs/04 §8）
+
+### 2. 最近一次体检
+
+```
+GET /api/health-check/last
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `idCard` / `phrid` / `empiId` | **三选一** | |
+
+- 上游：`JKTJLSJL00002` `/auto/jktjlscx/query`
+- 返回：`data` 为**单个对象**（最近一次完整体检，约 260 字段，见 docs/04 §11.3）
+
+### 3. 某人全部体检
+
+```
+GET /api/health-check/all
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `idCard` / `phrid` / `empiId` | **三选一** | |
+
+- 上游：`JKTJ00002` `/auto/jktj/query`
+- 返回：`data` 为**数组**（该人全部体检历史，每条完整）
+- 注意：历史记录 `checkId` 可能为 `null`（仅近年有），历史体检按 `checkDate` 区分（docs/04 §11.1）
+
+### 4. 年度已检/未检人员名单
+
+```
+GET /api/health-check/list
+```
+
+| 参数 | 必填 | 说明 |
+| --- | --- | --- |
+| `checkYear` | **是** | 检查年度，如 `2025` |
+| `idCard` | 否 | 过滤到某人 |
+| `checkType` | 否 | `0`已检 / `1`未检 / `2`全部 |
+| `page` `rows` | 否 | 分页，默认 `1` / `10` |
+
+- 上游：`JKTJLIST00002` `/auto/jktjlist/query`
+- 返回：`data` 为**数组**（人员名单 + `checkType` 状态，**非体检明细**，见 docs/04 §11.4）
+
+---
+
+## 调用示例
+
+```bash
+curl "http://127.0.0.1:8080/api/health-record/find?idCard=<身份证>"
+curl "http://127.0.0.1:8080/api/health-check/last?idCard=<身份证>"
+curl "http://127.0.0.1:8080/api/health-check/all?idCard=<身份证>"
+curl "http://127.0.0.1:8080/api/health-check/list?checkYear=2025&idCard=<身份证>"
+```
+
+---
+
+## 尚未提供（后续）
+
+- 写入类端点（档案/体检 create/update）：`handler` 侧 `/api/health-record/save` 等待 T-204/T-206 及厂家写入授权。
+- 老年人自理/体质、中医指导查询端点：待对应 OSI serviceId 联调（docs/06 B4）。
+- 鉴权、访问日志、限流：当前是本机联调工具形态，对外前必须补齐。

docs/README.md

@@ -23,6 +23,7 @@
 | [04-字段与接口映射.md](04-字段与接口映射.md) | OSI 接口↔内部能力映射、PHIS→OSI 字段/字典映射策略、checkId 幂等键 |
 | [05-实施路线图.md](05-实施路线图.md) | 分阶段落地计划、配置项、可观测性、测试与联调清单 |
 | [06-厂家联调清单.md](06-厂家联调清单.md) | 向厂家索要的凭据/环境/契约/样本清单，带回填状态，可直接发对接人 |
+| [07-本项目HTTP接口.md](07-本项目HTTP接口.md) | 本项目 server 模式对外提供的 HTTP 查询端点（我方接口的事实来源）|
 | [current-state.md](current-state.md) | **当前实现状态快照**（可覆盖）：仓库现实、已验证事实、可运行命令、blocker |
 
 ## 执行工件（根目录）

progress.md

@@ -242,3 +242,10 @@
 - 发现（实测校准）：① JKTJ00002 身份证字段是**驼峰 `idCard`**（≠ 最近一次小写 `idcard`；体检三接口 last 独用小写）；② **`checkId` 仅近年记录有值，历史记录为 `null`**（本样本仅最近 2 条有编号）——历史体检只能按 `checkDate` 定位；③ 数组元素结构同 §11.3。
 - 决策：数组查询只强类型化定位字段（checkId/checkDate/idCard/personName），完整体检走 Result.Raw；单独建 `HealthCheckRecordSummary`（驼峰 idCard）不复用最近一次的 `HealthCheckSummary`（小写 idcard），因平台字段大小写不一致。
 - 下一步：go test 复验后提交；体检查询三接口（最近一次/全部/名单）osi+HTTP 全齐。
+
+## 2026-07-08 新增 docs/07 本项目 HTTP 接口文档
+
+- 状态：DONE
+- 变更：新建 `docs/07-本项目HTTP接口.md`，整理 server 模式 5 个查询端点（档案 find + 体检 last/all/list）的参数/上游 serviceId/返回形态/PII 警示/通用约定；`docs/README.md` 导航登记；`CLAUDE.md` 文档同步表加"HTTP 端点增改 → docs/07"。
+- 决策：区分两层接口文档——上游 OSI 契约以 docs/01+04（实测）为准，本项目对外接口以 docs/07 为单一事实来源；docx 反复被证明不可靠，只作参考。
+- 下一步：新增端点时同步 docs/07；对外前补鉴权/日志/限流。