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: 公开主数据查询
- name: elderly
  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/elderly/self-care:
    get:
      tags:
      - elderly
      summary: 查询老年人生活自理能力评估
      description: 厂家文档给出的 LNRZLPG00002 查询契约，待真实联调确认。原样返回上游 `/auto/lnr/query` 响应。
      operationId: queryElderlySelfCare
      parameters:
      - name: idCard
        in: query
        required: true
        description: 身份证件号。
        schema:
          type: string
      - name: phrId
        in: query
        required: false
        description: 健康档案编号。注意参数名为驼峰 phrId。
        schema:
          type: string
      - name: checkId
        in: query
        required: false
        description: 第三方检查主键。
        schema:
          type: string
      responses:
        '200':
          description: 平台完整响应，成功和平台业务错误均原样透传。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElderlySelfCareResponse'
              examples:
                success:
                  value:
                    code: '01'
                    message: 操作成功
                    data:
                    - phrId: PHRID_PLACEHOLDER
                      checkId: LNR_CHECK_ID_PLACEHOLDER
                      jc: '1'
                      jcdj: '1'
                      jcpf: '10'
                      zp: '1'
                      zpdj: '1'
                      zpfs: '100'
        '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
    ElderlySelfCareResponse:
      allOf:
      - $ref: '#/components/schemas/OSIBaseResponse'
      - type: object
        properties:
          data:
            type: array
            description: 老年人生活自理能力评估记录数组。
            items:
              $ref: '#/components/schemas/ElderlySelfCareAssessment'
    ElderlySelfCareAssessment:
      type: object
      description: 厂家查询文档列出的评估字段；完整原始字段由服务透传。
      properties:
        phrId:
          type: string
        checkId:
          type: string
        jc:
          type: string
          description: 进餐原始值。
        jcdj:
          type: string
          description: 进餐等级。
        jcpf:
          type: string
          description: 进餐评分。
        sx:
          type: string
          description: 梳洗原始值。
        cy:
          type: string
          description: 穿衣原始值。
        rc:
          type: string
          description: 如厕原始值。
        hd:
          type: string
          description: 活动原始值。
        zp:
          type: string
          description: 总评。
        zpdj:
          type: string
          description: 总评等级。
        zpfs:
          type: string
          description: 总评分数。
      additionalProperties: true