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