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>
114 lines
3.7 KiB
Markdown
114 lines
3.7 KiB
Markdown
# 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）。
|
||
- 鉴权、访问日志、限流：当前是本机联调工具形态，对外前必须补齐。
|