feat(handler): 暴露公开查询 HTTP API（T-210）

2026-07-09 21:24:09 +08:00
parent 1903fa476b
commit 816a992f00
8 changed files with 662 additions and 158 deletions
@@ -1,210 +1,366 @@
 openapi: 3.0.3
 info:
  title: chis_osi Server API
-  version: "0.1.0"
-  description: |
-    chis_osi server 模式对外提供的本机 HTTP 查询接口。
+  version: 0.1.0
+  description: 'chis_osi server 模式对外提供的本机 HTTP 查询接口。
+

    本文档描述的是本项目自己的 HTTP API，不是上游 CHIS OSI 平台接口。
+
    当前端点会原样透传上游平台返回的完整 JSON，响应中可能包含身份证、档案号、
-    体检记录等个人敏感信息。默认只应监听 127.0.0.1；如需对外暴露，必须先补鉴权、
-    访问日志脱敏与限流。
+
+    体检记录等个人敏感信息。默认只监听 127.0.0.1；内网部署可通过 -addr 监听内网地址，
+
+    但服务本身不内置鉴权。如需给多系统调用，必须先补内网访问控制、
+
+    API 鉴权、访问日志脱敏与限流。
+
+    '
 servers:
-  - url: http://127.0.0.1:8080
-    description: 本地默认 server 模式地址
+- url: http://127.0.0.1:8080
+  description: 本地默认 server 模式地址
 tags:
-  - name: health-record
-    description: 健康档案查询
-  - name: health-check
-    description: 健康体检查询
+- name: health-record
+  description: 健康档案查询
+- name: health-check
+  description: 健康体检查询
+- name: dictionaries
+  description: 公开主数据查询
 paths:
  /api/health-record/find:
    get:
      tags:
-        - health-record
+      - health-record
      summary: 查询个人健康档案
-      description: |
-        查询个人健康档案，原样返回上游 JKDA00002 `/auto/jkda/find` 响应。
+      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"
+      - $ref: '#/components/parameters/idCard'
+      - $ref: '#/components/parameters/phrid'
+      - $ref: '#/components/parameters/personName'
+      - $ref: '#/components/parameters/empiId'
      responses:
-        "200":
+        '200':
          description: 平台完整响应，成功和平台业务错误均原样透传。
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/HealthRecordFindResponse"
+                $ref: '#/components/schemas/HealthRecordFindResponse'
              examples:
                success:
                  value:
-                    code: "01"
+                    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"
+                    - 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
+      - health-record
      summary: 查询人群分类/子档案标记
-      description: |
-        查询居民人群分类与子档案标记，原样返回上游 JKDA00005
+      description: '查询居民人群分类与子档案标记，原样返回上游 JKDA00005
+
        `/auto/jkda/findrqbj` 响应。

+
        `idCard`、`phrid` 两个查询参数必须且只能提供一个。`personSign` 可能为逗号分隔
+
        多值，码表见 docs/04 §3。
+
+        '
      operationId: findHealthRecordCrowd
      parameters:
-        - $ref: "#/components/parameters/idCard"
-        - $ref: "#/components/parameters/phrid"
+      - $ref: '#/components/parameters/idCard'
+      - $ref: '#/components/parameters/phrid'
      responses:
-        "200":
+        '200':
          description: 平台完整响应，成功和平台业务错误均原样透传。
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/CrowdResponse"
+                $ref: '#/components/schemas/CrowdResponse'
              examples:
                success:
                  value:
-                    code: "01"
+                    code: '01'
                    message: 操作成功
                    data:
-                      personSign: "01,04"
-                      idCard: "440000********0000"
+                      personSign: 01,04
+                      idCard: 440000********0000
                      phrId: PHRID_PLACEHOLDER
-        "400":
-          $ref: "#/components/responses/BadRequest"
-        "405":
-          $ref: "#/components/responses/MethodNotAllowed"
-        "502":
-          $ref: "#/components/responses/BadGateway"
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '405':
+          $ref: '#/components/responses/MethodNotAllowed'
+        '502':
+          $ref: '#/components/responses/BadGateway'
  /api/health-check/last:
    get:
      tags:
-        - health-check
+      - health-check
      summary: 查询最近一次体检
-      description: |
-        查询某人最近一次健康体检，原样返回上游 JKTJLSJL00002
+      description: '查询某人最近一次健康体检，原样返回上游 JKTJLSJL00002
+
        `/auto/jktjlscx/query` 响应。

+
        `idCard`、`phrid`、`empiId` 三个查询参数必须且只能提供一个。
+
        `data` 为单个完整体检对象。
+
+        '
      operationId: findLastHealthCheck
      parameters:
-        - $ref: "#/components/parameters/idCard"
-        - $ref: "#/components/parameters/phrid"
-        - $ref: "#/components/parameters/empiId"
+      - $ref: '#/components/parameters/idCard'
+      - $ref: '#/components/parameters/phrid'
+      - $ref: '#/components/parameters/empiId'
      responses:
-        "200":
+        '200':
          description: 平台完整响应，成功和平台业务错误均原样透传。
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/HealthCheckLastResponse"
+                $ref: '#/components/schemas/HealthCheckLastResponse'
              examples:
                success:
                  value:
-                    code: "01"
+                    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"
+                      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
+      - health-check
      summary: 查询某人全部体检
-      description: |
-        查询某人的全部健康体检历史，原样返回上游 JKTJ00002 `/auto/jktj/query` 响应。
+      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"
+      - $ref: '#/components/parameters/idCard'
+      - $ref: '#/components/parameters/phrid'
+      - $ref: '#/components/parameters/empiId'
      responses:
-        "200":
+        '200':
          description: 平台完整响应，成功和平台业务错误均原样透传。
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/HealthCheckAllResponse"
+                $ref: '#/components/schemas/HealthCheckAllResponse'
              examples:
                success:
                  value:
-                    code: "01"
+                    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"
+                    - 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
+      - health-check
      summary: 查询年度已检/未检人员名单
-      description: |
-        查询年度体检人员名单，原样返回上游 JKTJLIST00002 `/auto/jktjlist/query` 响应。
+      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"
+      - $ref: '#/components/parameters/checkYear'
+      - $ref: '#/components/parameters/idCard'
+      - $ref: '#/components/parameters/checkType'
+      - $ref: '#/components/parameters/page'
+      - $ref: '#/components/parameters/rows'
      responses:
-        "200":
+        '200':
          description: 平台完整响应，成功和平台业务错误均原样透传。
          content:
            application/json:
              schema:
-                $ref: "#/components/schemas/HealthCheckListResponse"
+                $ref: '#/components/schemas/HealthCheckListResponse'
              examples:
                success:
                  value:
-                    code: "01"
+                    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"
+                    - 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` 响应。
+      operationId: listDrugs
+      parameters:
+      - $ref: '#/components/parameters/ypmc'
+      - $ref: '#/components/parameters/pym'
+      - $ref: '#/components/parameters/pageNo'
+      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:
@@ -242,8 +398,8 @@ components:
      description: 体检年度，如 2025。
      schema:
        type: string
-        pattern: "^[0-9]{4}$"
-        example: "2025"
+        pattern: ^[0-9]{4}$
+        example: '2025'
    checkType:
      name: checkType
      in: query
@@ -252,9 +408,9 @@ components:
      schema:
        type: string
        enum:
-          - "0"
-          - "1"
-          - "2"
+        - '0'
+        - '1'
+        - '2'
    page:
      name: page
      in: query
@@ -262,7 +418,7 @@ components:
      description: 页码；未传时后端默认 1。
      schema:
        type: string
-        default: "1"
+        default: '1'
    rows:
      name: rows
      in: query
@@ -270,24 +426,81 @@ components:
      description: 每页条数；未传时后端默认 10。
      schema:
        type: string
-        default: "10"
+        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"
+            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingQueryKey:
              value:
-                error: "provide one of: idCard, phrid, empiId"
+                error: 'provide one of: idCard, phrid, empiId'
    MethodNotAllowed:
      description: HTTP 方法不支持。
      content:
        application/json:
          schema:
-            $ref: "#/components/schemas/ErrorResponse"
+            $ref: '#/components/schemas/ErrorResponse'
          examples:
            methodNotAllowed:
              value:
@@ -297,7 +510,7 @@ components:
      content:
        application/json:
          schema:
-            $ref: "#/components/schemas/ErrorResponse"
+            $ref: '#/components/schemas/ErrorResponse'
          examples:
            upstreamError:
              value:
@@ -306,49 +519,49 @@ components:
    ErrorResponse:
      type: object
      required:
-        - error
+      - error
      properties:
        error:
          type: string
    OSIBaseResponse:
      type: object
      required:
-        - code
-        - message
+      - code
+      - message
      properties:
        code:
          type: string
          description: 平台业务码。成功实测为字符串 "01"；平台业务错误也会原样透传。
-          example: "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
+      - $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"
+      - $ref: '#/components/schemas/OSIBaseResponse'
+      - type: object
+        properties:
+          data:
+            $ref: '#/components/schemas/CrowdData'
    CrowdData:
      type: object
      properties:
        personSign:
          type: string
          description: 人群分类码，可能为逗号分隔多值。
-          example: "01,04"
+          example: 01,04
        idCard:
          type: string
          description: 身份证号。
@@ -358,29 +571,29 @@ components:
      additionalProperties: true
    HealthCheckLastResponse:
      allOf:
-        - $ref: "#/components/schemas/OSIBaseResponse"
-        - type: object
-          properties:
-            data:
-              $ref: "#/components/schemas/HealthCheckRecord"
+      - $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"
+      - $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"
+      - $ref: '#/components/schemas/OSIBaseResponse'
+      - type: object
+        properties:
+          data:
+            type: array
+            items:
+              $ref: '#/components/schemas/HealthCheckPerson'
    HealthCheckRecord:
      type: object
      description: 平台完整体检对象；字段很多，未在本项目裁剪。
@@ -410,3 +623,14 @@ components:
          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