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

07 · 本项目 HTTP 接口

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

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

---

启动

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

参数	必填	说明
pageNo	是	页码，整数——药品目录是分页查询，必填
pageSize	否	每页数量，整数
ypmc	否	药品名称关键字
pym	否	拼音码

• 上游：YPML00001 /auto/ypmlcx/query（分页目录查询，非按名单条）
• 返回：data 为数组（一页药品），每条含 ypxh(序号)/ypmc/ypdw/ypgg/ypjl(剂量)/ycjl(一次剂量)/jldw 等
• ⚠ 依 docx 契约，YPML00001 尚未真实联调：pageNo 是否真必填、pageSize 字段名、响应字段均以联调实测为准

9. 查询机构

GET /api/dictionaries/orgs

参数	必填	说明
organizCode	否	机构编码；HTTP 未传时仍会向 OSI 显式上送空字符串
parentId	否	上级机构 ID/编码；HTTP 未传时仍会向 OSI 显式上送空字符串

• 上游：CXJG00002 /auto/cxjg/query
• 返回：data 为数组（机构主数据，含 organizCode、organizName、organizType、parentId、regionCode 等）；regionCode 可能为 null
• OSI 要求 organizCode 和 parentId 两个 baseInfo key 都存在，值可为空；本服务已保证该行为

10. 查询老年人生活自理能力评估

GET /api/elderly/self-care

参数	必填	说明
idCard	是	身份证件号
phrId	否	健康档案编号（注意驼峰 phrId）
checkId	否	第三方检查主键

• 上游：LNRZLPG00002 /auto/lnr/query（厂家文档契约，待真实联调确认）
• 返回：data 为数组，每条含进餐/梳洗/穿衣/如厕/活动及总评的原始值、等级和评分；完整字段原样回写

---

调用示例

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?pageNo=1&pageSize=10&ypmc=<药品名>"   # pageNo 必填
curl "http://127.0.0.1:8080/api/dictionaries/orgs?parentId=<上级机构ID>"
curl "http://127.0.0.1:8080/api/elderly/self-care?idCard=<身份证>"

---

尚未提供（后续）

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