chis_osi/docs/07-本项目HTTP接口.md

# 07 · 本项目 HTTP 接口

`chis_osi` **server 模式**对外提供的 HTTP 查询接口——供前端/运维/PHIS 侧调用。

> 这是本项目**自己**对外的接口的单一事实来源；调用**上游厂家 OSI** 的接口契约看 `docs/01`、`docs/04`。
> 新增/修改端点后同步本文（与 `handler/`、`server.go` 保持一致）。
> 机器可读 OpenAPI 文档见 [`openapi.yaml`](openapi.yaml)。

---

## 启动

```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`**：所有端点回写真实居民档案/体检或平台主数据。后续内网部署可用 `-addr <内网IP>:<端口>` 监听内网地址，但本服务当前不内置鉴权；上线前必须通过内网访问控制/API 网关补鉴权、日志脱敏和限流。

---

## 通用约定

| 项 | 说明 |
| --- | --- |
| 方法 | 一律 `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-record/crowd
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `idCard` / `phrid` | **二选一** | 查询标识符，只能给一个 |

- 上游：`JKDA00005` `/auto/jkda/findrqbj`
- 返回：`data` 为对象，含 `personSign`、`idCard`、`phrId`（见 docs/04 §12）
- `personSign` 是人群分类码，可能为逗号分隔多值；码表见 docs/04 §3

### 3. 最近一次体检

```
GET /api/health-check/last
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `idCard` / `phrid` / `empiId` | **三选一** | |

- 上游：`JKTJLSJL00002` `/auto/jktjlscx/query`
- 返回：`data` 为**单个对象**（最近一次完整体检，约 260 字段，见 docs/04 §11.3）

### 4. 某人全部体检

```
GET /api/health-check/all
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `idCard` / `phrid` / `empiId` | **三选一** | |

- 上游：`JKTJ00002` `/auto/jktj/query`
- 返回：`data` 为**数组**（该人全部体检历史，每条完整）
- 注意：历史记录 `checkId` 可能为 `null`（仅近年有），历史体检按 `checkDate` 区分（docs/04 §11.1）

### 5. 年度已检/未检人员名单

```
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）

### 6. 查询网格地址

```
GET /api/dictionaries/grid-addresses
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `parentCode` | 否 | 上级区划/网格编码 |
| `pageNo` | 否 | 页码，整数 |
| `operateUser` | 否 | 平台操作人编码 |

- 上游：`WGDZ00001` `/auto/wgdzcx/query`
- 返回：`data` 为**数组**（网格地址主数据，含 `regionCode`、`regionName`、`isFamily` 等）

### 7. 查询责任医生

```
GET /api/dictionaries/doctors
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `manaUnitId` | 否 | 9 位管理机构码 |
| `operateUser` | 否 | 平台操作人编码 |

- 上游：`ZRYS00001` `/auto/zryscx/query`
- 返回：`data` 为**数组**（责任医生主数据，含 `personId`、`personName` 等）

### 8. 查询药品目录

```
GET /api/dictionaries/drugs
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `ypmc` | 否 | 药品名称关键字 |
| `pym` | 否 | 拼音码 |
| `pageNo` | 否 | 页码，整数 |

- 上游：`YPML00001` `/auto/ypmlcx/query`
- 返回：`data` 为**数组**（药品目录主数据，含 `ypmc`、`ypdw`、`ypgg`、`jldw` 等）

### 9. 查询机构

```
GET /api/dictionaries/orgs
```

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `organizCode` | 否 | 机构编码 |
| `parentId` | 否 | 上级机构 ID/编码 |

- 上游：`CXJG00002` `/auto/cxjg/query`
- 返回：`data` 为**数组**（机构主数据，含 `organizCode`、`organizName`、`organizType`、`parentId` 等）
---

## 调用示例

```bash
curl "http://127.0.0.1:8080/api/health-record/find?idCard=<身份证>"
curl "http://127.0.0.1:8080/api/health-record/crowd?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=<身份证>"
curl "http://127.0.0.1:8080/api/dictionaries/grid-addresses?parentCode=<区划码>"
curl "http://127.0.0.1:8080/api/dictionaries/doctors?manaUnitId=<机构码>"
curl "http://127.0.0.1:8080/api/dictionaries/drugs?ypmc=<药品名>"
curl "http://127.0.0.1:8080/api/dictionaries/orgs?parentId=<上级机构ID>"
```

---

## 尚未提供（后续）

- 写入类端点（档案/体检 create/update）：`handler` 侧 `/api/health-record/save` 等待 T-204/T-206 及厂家写入授权。
- 老年人自理/体质、中医指导查询端点：待对应 OSI serviceId 联调（docs/06 B4）。
- 鉴权、访问日志、限流：当前是本机联调工具形态，对外前必须补齐。