ilaandClaude Opus 4.8
7a079b2b3f
- docs/07 §8 pageNo 必填 + 补 pageSize + 分页说明 + 未联调警示 - openapi drugs 内联 pageNo(required)+pageSize，不动共享 pageNo - tasks T-211 DONE Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
650 lines
20 KiB
YAML
650 lines
20 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；内网部署可通过 -addr 监听内网地址，
|
|
|
|
但服务本身不内置鉴权。如需给多系统调用，必须先补内网访问控制、
|
|
|
|
API 鉴权、访问日志脱敏与限流。
|
|
|
|
'
|
|
servers:
|
|
- url: http://127.0.0.1:8080
|
|
description: 本地默认 server 模式地址
|
|
tags:
|
|
- name: health-record
|
|
description: 健康档案查询
|
|
- name: health-check
|
|
description: 健康体检查询
|
|
- name: dictionaries
|
|
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'
|
|
/api/dictionaries/grid-addresses:
|
|
get:
|
|
tags:
|
|
- dictionaries
|
|
summary: 查询网格地址
|
|
description: 查询网格地址主数据，原样返回上游 WGDZ00001 `/auto/wgdzcx/query` 响应。
|
|
operationId: listGridAddresses
|
|
parameters:
|
|
- $ref: '#/components/parameters/parentCode'
|
|
- $ref: '#/components/parameters/pageNo'
|
|
- $ref: '#/components/parameters/operateUser'
|
|
responses:
|
|
'200':
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DictionaryListResponse'
|
|
examples:
|
|
success:
|
|
value:
|
|
code: '01'
|
|
message: 操作成功
|
|
data:
|
|
- regionCode: '441625000000'
|
|
regionName: 测试网格
|
|
isFamily: '1'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'405':
|
|
$ref: '#/components/responses/MethodNotAllowed'
|
|
'502':
|
|
$ref: '#/components/responses/BadGateway'
|
|
/api/dictionaries/doctors:
|
|
get:
|
|
tags:
|
|
- dictionaries
|
|
summary: 查询责任医生
|
|
description: 查询责任医生主数据，原样返回上游 ZRYS00001 `/auto/zryscx/query` 响应。
|
|
operationId: listDoctors
|
|
parameters:
|
|
- $ref: '#/components/parameters/manaUnitId'
|
|
- $ref: '#/components/parameters/operateUser'
|
|
responses:
|
|
'200':
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DictionaryListResponse'
|
|
examples:
|
|
success:
|
|
value:
|
|
code: '01'
|
|
message: 操作成功
|
|
data:
|
|
- personId: DOC_ID_PLACEHOLDER
|
|
personName: 测试医生
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'405':
|
|
$ref: '#/components/responses/MethodNotAllowed'
|
|
'502':
|
|
$ref: '#/components/responses/BadGateway'
|
|
/api/dictionaries/drugs:
|
|
get:
|
|
tags:
|
|
- dictionaries
|
|
summary: 查询药品目录
|
|
description: 查询药品目录主数据（分页），原样返回上游 YPML00001 `/auto/ypmlcx/query` 响应。pageNo 必填；契约依 docx，尚未真实联调。
|
|
operationId: listDrugs
|
|
parameters:
|
|
- name: pageNo
|
|
in: query
|
|
required: true
|
|
description: 页码（药品目录为分页查询，必填）。
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
- name: pageSize
|
|
in: query
|
|
required: false
|
|
description: 每页数量。
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
- $ref: '#/components/parameters/ypmc'
|
|
- $ref: '#/components/parameters/pym'
|
|
responses:
|
|
'200':
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DictionaryListResponse'
|
|
examples:
|
|
success:
|
|
value:
|
|
code: '01'
|
|
message: 操作成功
|
|
data:
|
|
- ypmc: 测试药品
|
|
ypdw: 盒
|
|
ypgg: 10mg
|
|
jldw: 片
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'405':
|
|
$ref: '#/components/responses/MethodNotAllowed'
|
|
'502':
|
|
$ref: '#/components/responses/BadGateway'
|
|
/api/dictionaries/orgs:
|
|
get:
|
|
tags:
|
|
- dictionaries
|
|
summary: 查询机构
|
|
description: 查询机构主数据，原样返回上游 CXJG00002 `/auto/cxjg/query` 响应。
|
|
operationId: listOrgs
|
|
parameters:
|
|
- $ref: '#/components/parameters/organizCode'
|
|
- $ref: '#/components/parameters/parentId'
|
|
responses:
|
|
'200':
|
|
description: 平台完整响应，成功和平台业务错误均原样透传。
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DictionaryListResponse'
|
|
examples:
|
|
success:
|
|
value:
|
|
code: '01'
|
|
message: 操作成功
|
|
data:
|
|
- organizCode: '441625001'
|
|
organizName: 测试机构
|
|
organizType: '1'
|
|
parentId: '441625'
|
|
'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'
|
|
parentCode:
|
|
name: parentCode
|
|
in: query
|
|
required: false
|
|
description: 上级区划/网格编码。
|
|
schema:
|
|
type: string
|
|
pageNo:
|
|
name: pageNo
|
|
in: query
|
|
required: false
|
|
description: 页码，必须为整数。
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
operateUser:
|
|
name: operateUser
|
|
in: query
|
|
required: false
|
|
description: 平台操作人编码。
|
|
schema:
|
|
type: string
|
|
manaUnitId:
|
|
name: manaUnitId
|
|
in: query
|
|
required: false
|
|
description: 9 位管理机构码。
|
|
schema:
|
|
type: string
|
|
ypmc:
|
|
name: ypmc
|
|
in: query
|
|
required: false
|
|
description: 药品名称关键字。
|
|
schema:
|
|
type: string
|
|
pym:
|
|
name: pym
|
|
in: query
|
|
required: false
|
|
description: 药品拼音码。
|
|
schema:
|
|
type: string
|
|
organizCode:
|
|
name: organizCode
|
|
in: query
|
|
required: false
|
|
description: 机构编码。
|
|
schema:
|
|
type: string
|
|
parentId:
|
|
name: parentId
|
|
in: query
|
|
required: false
|
|
description: 上级机构 ID/编码。
|
|
schema:
|
|
type: string
|
|
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
|
|
DictionaryListResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/OSIBaseResponse'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
description: 平台公开查询主数据数组，字段按上游原始响应透传。
|
|
items:
|
|
type: object
|
|
additionalProperties: true
|