07 · 本项目 HTTP 接口

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

这是本项目自己对外的接口的单一事实来源；调用上游厂家 OSI 的接口契约看 docs/01、docs/04。新增/修改端点后同步本文（与 handler/、server.go 保持一致）。

启动

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-record/crowd

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

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

2. 最近一次体检

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）

调用示例

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=<身份证>"

尚未提供（后续）

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

4.2 KiB Raw Blame History Unescape Escape