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