docs: 登记 T-210 公开查询 HTTP API

2026-07-09 21:17:16 +08:00
parent 561cd839e7
commit 1903fa476b
6 changed files with 430 additions and 6 deletions
@@ -0,0 +1,412 @@
+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