413 lines
13 KiB
YAML
413 lines
13 KiB
YAML
|
openapi: 3.0.3
|
||
|
|
info:
|
||
|
|
title: chis_osi Server API
|
||
|
|
version: "0.1.0"
|
||
|
|
description: |
|
||
|
|
chis_osi server 模式对外提供的本机 HTTP 查询接口。
|
||
|
|
|
||
|
|
本文档描述的是本项目自己的 HTTP API，不是上游 CHIS OSI 平台接口。
|
||
|
|
当前端点会原样透传上游平台返回的完整 JSON，响应中可能包含身份证、档案号、
|
||
|
|
体检记录等个人敏感信息。默认只应监听 127.0.0.1；如需对外暴露，必须先补鉴权、
|
||
|
|
访问日志脱敏与限流。
|
||
|
|
servers:
|
||
|
|
- url: http://127.0.0.1:8080
|
||
|
|
description: 本地默认 server 模式地址
|
||
|
|
tags:
|
||
|
|
- name: health-record
|
||
|
|
description: 健康档案查询
|
||
|
|
- name: health-check
|
||
|
|
description: 健康体检查询
|
||
|
|
paths:
|
||
|
|
/api/health-record/find:
|
||
|
|
get:
|
||
|
|
tags:
|
||
|
|
- health-record
|
||
|
|
summary: 查询个人健康档案
|
||
|
|
description: |
|
||
|
|
查询个人健康档案，原样返回上游 JKDA00002 `/auto/jkda/find` 响应。
|
||
|
|
|
||
|
|
`idCard`、`phrid`、`personName`、`empiId` 四个查询参数必须且只能提供一个。
|
||
|
|
`data` 为数组，内容为平台返回的完整档案聚合对象。
|
||
|
|
operationId: findHealthRecord
|
||
|
|
parameters:
|
||
|
|
- $ref: "#/components/parameters/idCard"
|
||
|
|
- $ref: "#/components/parameters/phrid"
|
||
|
|
- $ref: "#/components/parameters/personName"
|
||
|
|
- $ref: "#/components/parameters/empiId"
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/HealthRecordFindResponse"
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
value:
|
||
|
|
code: "01"
|
||
|
|
message: 操作成功
|
||
|
|
data:
|
||
|
|
- phrId: PHRID_PLACEHOLDER
|
||
|
|
idCard: "440000********0000"
|
||
|
|
"400":
|
||
|
|
$ref: "#/components/responses/BadRequest"
|
||
|
|
"405":
|
||
|
|
$ref: "#/components/responses/MethodNotAllowed"
|
||
|
|
"502":
|
||
|
|
$ref: "#/components/responses/BadGateway"
|
||
|
|
/api/health-record/crowd:
|
||
|
|
get:
|
||
|
|
tags:
|
||
|
|
- health-record
|
||
|
|
summary: 查询人群分类/子档案标记
|
||
|
|
description: |
|
||
|
|
查询居民人群分类与子档案标记，原样返回上游 JKDA00005
|
||
|
|
`/auto/jkda/findrqbj` 响应。
|
||
|
|
|
||
|
|
`idCard`、`phrid` 两个查询参数必须且只能提供一个。`personSign` 可能为逗号分隔
|
||
|
|
多值，码表见 docs/04 §3。
|
||
|
|
operationId: findHealthRecordCrowd
|
||
|
|
parameters:
|
||
|
|
- $ref: "#/components/parameters/idCard"
|
||
|
|
- $ref: "#/components/parameters/phrid"
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/CrowdResponse"
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
value:
|
||
|
|
code: "01"
|
||
|
|
message: 操作成功
|
||
|
|
data:
|
||
|
|
personSign: "01,04"
|
||
|
|
idCard: "440000********0000"
|
||
|
|
phrId: PHRID_PLACEHOLDER
|
||
|
|
"400":
|
||
|
|
$ref: "#/components/responses/BadRequest"
|
||
|
|
"405":
|
||
|
|
$ref: "#/components/responses/MethodNotAllowed"
|
||
|
|
"502":
|
||
|
|
$ref: "#/components/responses/BadGateway"
|
||
|
|
/api/health-check/last:
|
||
|
|
get:
|
||
|
|
tags:
|
||
|
|
- health-check
|
||
|
|
summary: 查询最近一次体检
|
||
|
|
description: |
|
||
|
|
查询某人最近一次健康体检，原样返回上游 JKTJLSJL00002
|
||
|
|
`/auto/jktjlscx/query` 响应。
|
||
|
|
|
||
|
|
`idCard`、`phrid`、`empiId` 三个查询参数必须且只能提供一个。
|
||
|
|
`data` 为单个完整体检对象。
|
||
|
|
operationId: findLastHealthCheck
|
||
|
|
parameters:
|
||
|
|
- $ref: "#/components/parameters/idCard"
|
||
|
|
- $ref: "#/components/parameters/phrid"
|
||
|
|
- $ref: "#/components/parameters/empiId"
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/HealthCheckLastResponse"
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
value:
|
||
|
|
code: "01"
|
||
|
|
message: 操作成功
|
||
|
|
data:
|
||
|
|
checkId: CHECK_ID_PLACEHOLDER
|
||
|
|
checkDate: "2025-01-01"
|
||
|
|
idCard: "440000********0000"
|
||
|
|
"400":
|
||
|
|
$ref: "#/components/responses/BadRequest"
|
||
|
|
"405":
|
||
|
|
$ref: "#/components/responses/MethodNotAllowed"
|
||
|
|
"502":
|
||
|
|
$ref: "#/components/responses/BadGateway"
|
||
|
|
/api/health-check/all:
|
||
|
|
get:
|
||
|
|
tags:
|
||
|
|
- health-check
|
||
|
|
summary: 查询某人全部体检
|
||
|
|
description: |
|
||
|
|
查询某人的全部健康体检历史，原样返回上游 JKTJ00002 `/auto/jktj/query` 响应。
|
||
|
|
|
||
|
|
`idCard`、`phrid`、`empiId` 三个查询参数必须且只能提供一个。
|
||
|
|
`data` 为数组；历史记录的 `checkId` 可能为空，调用方应按 `checkDate` 等字段辅助区分。
|
||
|
|
operationId: findAllHealthChecks
|
||
|
|
parameters:
|
||
|
|
- $ref: "#/components/parameters/idCard"
|
||
|
|
- $ref: "#/components/parameters/phrid"
|
||
|
|
- $ref: "#/components/parameters/empiId"
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/HealthCheckAllResponse"
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
value:
|
||
|
|
code: "01"
|
||
|
|
message: 操作成功
|
||
|
|
data:
|
||
|
|
- checkId: CHECK_ID_PLACEHOLDER
|
||
|
|
checkDate: "2025-01-01"
|
||
|
|
idCard: "440000********0000"
|
||
|
|
"400":
|
||
|
|
$ref: "#/components/responses/BadRequest"
|
||
|
|
"405":
|
||
|
|
$ref: "#/components/responses/MethodNotAllowed"
|
||
|
|
"502":
|
||
|
|
$ref: "#/components/responses/BadGateway"
|
||
|
|
/api/health-check/list:
|
||
|
|
get:
|
||
|
|
tags:
|
||
|
|
- health-check
|
||
|
|
summary: 查询年度已检/未检人员名单
|
||
|
|
description: |
|
||
|
|
查询年度体检人员名单，原样返回上游 JKTJLIST00002 `/auto/jktjlist/query` 响应。
|
||
|
|
|
||
|
|
`data` 为人员名单和 `checkType` 状态，不是体检明细。
|
||
|
|
operationId: listHealthCheckPeople
|
||
|
|
parameters:
|
||
|
|
- $ref: "#/components/parameters/checkYear"
|
||
|
|
- $ref: "#/components/parameters/idCard"
|
||
|
|
- $ref: "#/components/parameters/checkType"
|
||
|
|
- $ref: "#/components/parameters/page"
|
||
|
|
- $ref: "#/components/parameters/rows"
|
||
|
|
responses:
|
||
|
|
"200":
|
||
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/HealthCheckListResponse"
|
||
|
|
examples:
|
||
|
|
success:
|
||
|
|
value:
|
||
|
|
code: "01"
|
||
|
|
message: 操作成功
|
||
|
|
data:
|
||
|
|
- idCard: "440000********0000"
|
||
|
|
checkYear: "2025"
|
||
|
|
checkType: "0"
|
||
|
|
"400":
|
||
|
|
$ref: "#/components/responses/BadRequest"
|
||
|
|
"405":
|
||
|
|
$ref: "#/components/responses/MethodNotAllowed"
|
||
|
|
"502":
|
||
|
|
$ref: "#/components/responses/BadGateway"
|
||
|
|
components:
|
||
|
|
parameters:
|
||
|
|
idCard:
|
||
|
|
name: idCard
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: 身份证号。该字段属于个人敏感信息，日志和截图中应脱敏。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
phrid:
|
||
|
|
name: phrid
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: 健康档案编号。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
personName:
|
||
|
|
name: personName
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: 居民姓名，仅健康档案查询支持。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
empiId:
|
||
|
|
name: empiId
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: EMPI 主索引 ID。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
checkYear:
|
||
|
|
name: checkYear
|
||
|
|
in: query
|
||
|
|
required: true
|
||
|
|
description: 体检年度，如 2025。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
pattern: "^[0-9]{4}$"
|
||
|
|
example: "2025"
|
||
|
|
checkType:
|
||
|
|
name: checkType
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: 年度名单过滤条件：0 已检，1 未检，2 全部。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
enum:
|
||
|
|
- "0"
|
||
|
|
- "1"
|
||
|
|
- "2"
|
||
|
|
page:
|
||
|
|
name: page
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: 页码；未传时后端默认 1。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
default: "1"
|
||
|
|
rows:
|
||
|
|
name: rows
|
||
|
|
in: query
|
||
|
|
required: false
|
||
|
|
description: 每页条数；未传时后端默认 10。
|
||
|
|
schema:
|
||
|
|
type: string
|
||
|
|
default: "10"
|
||
|
|
responses:
|
||
|
|
BadRequest:
|
||
|
|
description: 请求参数错误。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/ErrorResponse"
|
||
|
|
examples:
|
||
|
|
missingQueryKey:
|
||
|
|
value:
|
||
|
|
error: "provide one of: idCard, phrid, empiId"
|
||
|
|
MethodNotAllowed:
|
||
|
|
description: HTTP 方法不支持。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/ErrorResponse"
|
||
|
|
examples:
|
||
|
|
methodNotAllowed:
|
||
|
|
value:
|
||
|
|
error: only GET is supported
|
||
|
|
BadGateway:
|
||
|
|
description: 未拿到上游平台响应，通常为网络、代理、签名或平台不可用错误。
|
||
|
|
content:
|
||
|
|
application/json:
|
||
|
|
schema:
|
||
|
|
$ref: "#/components/schemas/ErrorResponse"
|
||
|
|
examples:
|
||
|
|
upstreamError:
|
||
|
|
value:
|
||
|
|
error: empty response from OSI
|
||
|
|
schemas:
|
||
|
|
ErrorResponse:
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- error
|
||
|
|
properties:
|
||
|
|
error:
|
||
|
|
type: string
|
||
|
|
OSIBaseResponse:
|
||
|
|
type: object
|
||
|
|
required:
|
||
|
|
- code
|
||
|
|
- message
|
||
|
|
properties:
|
||
|
|
code:
|
||
|
|
type: string
|
||
|
|
description: 平台业务码。成功实测为字符串 "01"；平台业务错误也会原样透传。
|
||
|
|
example: "01"
|
||
|
|
message:
|
||
|
|
type: string
|
||
|
|
example: 操作成功
|
||
|
|
additionalProperties: true
|
||
|
|
HealthRecordFindResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: "#/components/schemas/OSIBaseResponse"
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
type: array
|
||
|
|
description: 平台完整健康档案聚合对象数组。
|
||
|
|
items:
|
||
|
|
type: object
|
||
|
|
additionalProperties: true
|
||
|
|
CrowdResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: "#/components/schemas/OSIBaseResponse"
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
$ref: "#/components/schemas/CrowdData"
|
||
|
|
CrowdData:
|
||
|
|
type: object
|
||
|
|
properties:
|
||
|
|
personSign:
|
||
|
|
type: string
|
||
|
|
description: 人群分类码，可能为逗号分隔多值。
|
||
|
|
example: "01,04"
|
||
|
|
idCard:
|
||
|
|
type: string
|
||
|
|
description: 身份证号。
|
||
|
|
phrId:
|
||
|
|
type: string
|
||
|
|
description: 健康档案编号。
|
||
|
|
additionalProperties: true
|
||
|
|
HealthCheckLastResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: "#/components/schemas/OSIBaseResponse"
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
$ref: "#/components/schemas/HealthCheckRecord"
|
||
|
|
HealthCheckAllResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: "#/components/schemas/OSIBaseResponse"
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
type: array
|
||
|
|
items:
|
||
|
|
$ref: "#/components/schemas/HealthCheckRecord"
|
||
|
|
HealthCheckListResponse:
|
||
|
|
allOf:
|
||
|
|
- $ref: "#/components/schemas/OSIBaseResponse"
|
||
|
|
- type: object
|
||
|
|
properties:
|
||
|
|
data:
|
||
|
|
type: array
|
||
|
|
items:
|
||
|
|
$ref: "#/components/schemas/HealthCheckPerson"
|
||
|
|
HealthCheckRecord:
|
||
|
|
type: object
|
||
|
|
description: 平台完整体检对象；字段很多，未在本项目裁剪。
|
||
|
|
properties:
|
||
|
|
checkId:
|
||
|
|
type: string
|
||
|
|
nullable: true
|
||
|
|
description: 体检幂等/定位 ID，历史记录可能为空。
|
||
|
|
checkDate:
|
||
|
|
type: string
|
||
|
|
description: 体检日期，平台返回格式以原始响应为准。
|
||
|
|
idCard:
|
||
|
|
type: string
|
||
|
|
description: 身份证号。
|
||
|
|
additionalProperties: true
|
||
|
|
HealthCheckPerson:
|
||
|
|
type: object
|
||
|
|
description: 年度已检/未检人员名单项，非体检明细。
|
||
|
|
properties:
|
||
|
|
idCard:
|
||
|
|
type: string
|
||
|
|
description: 身份证号。
|
||
|
|
checkYear:
|
||
|
|
type: string
|
||
|
|
description: 体检年度。
|
||
|
|
checkType:
|
||
|
|
type: string
|
||
|
|
description: 0 已检，1 未检，2 全部或平台返回状态。
|
||
|
|
additionalProperties: true
|