openapi: 3.0.3
info:
  title: 运梦气象 API
  version: 1.0.0
  description: ERA5 历史气象与德国气象局预报数据同步下载接口。字段口径以本 OpenAPI 规范和公开字段表为准。
servers:
  - url: https://console.yun-meng.top
paths:
  /api/energy-weather/search/weather/action/downloadSync:
    post:
      summary: 按经纬度同步下载气象数据
      operationId: downloadWeatherSync
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeatherDownloadRequest'
            example:
              lat: 31.7655
              lon: 105.205
              dataSourceId: era5
              stime: '2026-04-20 00:00'
              etime: '2026-04-21 23:00'
              fields:
                - tas
                - hurs
                - ws
              timezone: '8'
      responses:
        '200':
          description: |
            查询成功。返回 application/json 统一 envelope：
            {code, success, data:{timeList, tas, ...}, msg, errorCode}。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherDownloadEnvelope'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    WeatherDownloadRequest:
      type: object
      required:
        - lat
        - lon
        - dataSourceId
        - stime
        - etime
        - fields
        - timezone
      properties:
        lat:
          type: number
          format: double
          description: 纬度
        lon:
          type: number
          format: double
          description: 经度
        dataSourceId:
          type: string
          description: 数据源 ID。era5=欧洲中期天气中心 / nasa=美国国家航空航天局 / zg1=中国数源V1.0（历史再分析）；ger=德国气象局（预报，未来 ~7 天）
          enum:
            - era5
            - nasa
            - zg1
            - ger
        stime:
          type: string
          description: 开始时间，格式 yyyy-MM-dd HH:mm
        etime:
          type: string
          description: 结束时间，格式 yyyy-MM-dd HH:mm
        fields:
          type: array
          items:
            $ref: '#/components/schemas/WeatherField'
        timezone:
          type: string
          description: 时区偏移，例如 8
    WeatherField:
      type: string
      enum:
        - tas
        - hurs
        - sp
        - pr
        - uas
        - vas
        - ws
        - wd
        - rsds
        - dni
        - dhi
        - u100
        - v100
        - u10n
        - v10n
    WeatherDownloadEnvelope:
      type: object
      description: 统一 JSON 响应包；与控制台 / OpenAPI Gateway 其他接口一致
      required:
        - code
        - success
        - data
        - msg
        - errorCode
      properties:
        code:
          type: integer
          example: 200
        success:
          type: boolean
          example: true
        msg:
          type: string
          example: success
        errorCode:
          type: integer
          example: 0
        data:
          $ref: '#/components/schemas/WeatherDownloadData'
    WeatherDownloadData:
      type: object
      properties:
        timeList:
          type: array
          items:
            type: string
        tas:
          type: array
          items:
            type: number
        hurs:
          type: array
          items:
            type: number
        sp:
          type: array
          items:
            type: number
        pr:
          type: array
          items:
            type: number
        uas:
          type: array
          items:
            type: number
        vas:
          type: array
          items:
            type: number
        ws:
          type: array
          items:
            type: number
        wd:
          type: array
          items:
            type: number
        rsds:
          type: array
          items:
            type: number
        dni:
          type: array
          items:
            type: number
        dhi:
          type: array
          items:
            type: number
        u100:
          type: array
          items:
            type: number
        v100:
          type: array
          items:
            type: number
        u10n:
          type: array
          items:
            type: number
        v10n:
          type: array
          items:
            type: number
