app-api/docs/swagger.yaml

basePath: /
info:
  contact:
    name: Luxsin
  description: 耳机音频参数 EQ 后端服务
  title: App Audio API
  version: "1.0"
paths:
  /api/v1/health:
    get:
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            type: object
      summary: 健康检查
      tags:
      - System
  /audio/getBrand:
    get:
      parameters:
      - description: 品牌名称（模糊匹配）
        in: query
        name: brandName
        type: string
      - description: 是否返回 base64 编码响应
        in: query
        name: base64Resp
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: object
            type: array
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 获取品牌列表
      tags:
      - Brand
  /audio/getCurve:
    get:
      description: 根据机型和目标曲线名称，计算并返回 parametric_eq 数据
      parameters:
      - description: 品牌名称
        in: query
        name: brand
        required: true
        type: string
      - description: 型号名称
        in: query
        name: name
        required: true
        type: string
      - description: 目标曲线名称
        in: query
        name: target
        required: true
        type: string
      - description: 是否返回 base64 编码响应
        in: query
        name: base64Resp
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 parametric_eq 数据
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 获取目标曲线参数化 EQ
      tags:
      - Curve
  /audio/getModel:
    get:
      parameters:
      - description: 品牌名称
        in: query
        name: brandName
        type: string
      - description: 型号名称
        in: query
        name: modelName
        type: string
      - description: 是否返回 base64 编码响应
        in: query
        name: base64Resp
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: object
            type: array
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 获取型号列表
      tags:
      - Model
  /audio/getModelCSV:
    get:
      description: 从 S3 读取指定机型的测量 CSV 数据，返回 frequency 和 raw 数组
      parameters:
      - description: 品牌名称
        in: query
        name: brand
        required: true
        type: string
      - description: 型号名称
        in: query
        name: model
        required: true
        type: string
      - description: 耳机类型 (in-ear/over-ear)
        in: query
        name: form
        required: true
        type: string
      - description: 是否返回 base64 编码响应
        in: query
        name: base64Resp
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 frequency 和 raw 数组
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 获取耳机原始频响 CSV 数据
      tags:
      - Curve
  /audio/modelCurve:
    get:
      description: 返回指定机型的频响曲线数据（fr），固定使用 Harman over-ear 2018 target
      parameters:
      - description: 品牌名称
        in: query
        name: brand
        required: true
        type: string
      - description: 型号名称
        in: query
        name: name
        required: true
        type: string
      - description: 是否返回 base64 编码响应
        in: query
        name: base64Resp
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 fr 数据
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 获取机型默认频响曲线
      tags:
      - Curve
  /audio/modelList:
    get:
      parameters:
      - description: 搜索关键词
        in: query
        name: key
        type: string
      - description: 返回数量上限
        in: query
        name: count
        type: integer
      - description: 是否返回 base64 编码响应
        in: query
        name: base64Resp
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            items:
              type: string
            type: array
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 搜索型号列表（基于 Meilisearch）
      tags:
      - Model
  /audio/ota:
    get:
      description: 根据设备型号和硬件版本查询最新 OTA 记录，支持黑名单过滤和定向升级逻辑
      parameters:
      - description: 设备型号
        in: query
        name: model
        required: true
        type: string
      - description: 硬件版本
        in: query
        name: hw
        required: true
        type: integer
      - description: 设备 MAC 地址
        in: query
        name: mac
        type: string
      - description: 是否 beta 通道 (0=否,1=是)
        in: query
        name: beta
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 OTA 信息
          schema:
            type: object
        "400":
          description: Bad Request
          schema:
            type: object
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 获取 OTA 升级信息
      tags:
      - OTA
  /audio/reportDevInfo:
    get:
      parameters:
      - description: 设备 MAC 地址
        in: query
        name: mac
        required: true
        type: string
      - description: 设备型号
        in: query
        name: model
        required: true
        type: string
      - description: 固件版本号
        in: query
        name: ver
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 操作成功
          schema:
            additionalProperties: true
            type: object
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 上报设备信息
      tags:
      - Device
  /audio/reportImpedance:
    get:
      parameters:
      - description: 设备 MAC 地址
        in: query
        name: mac
        required: true
        type: string
      - description: 设备型号
        in: query
        name: name
        required: true
        type: string
      - description: 耳机品牌
        in: query
        name: brand
        required: true
        type: string
      - description: 耳机型号
        in: query
        name: model
        required: true
        type: string
      - description: 阻抗值（整数）
        in: query
        name: value
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: 操作成功
          schema:
            additionalProperties: true
            type: object
        "500":
          description: Internal Server Error
          schema:
            type: object
      summary: 上报耳机阻抗
      tags:
      - Device
  /audio/shareAccept:
    get:
      description: 根据分享码获取他人分享的 EQ 数据
      parameters:
      - description: 设备 MAC 地址
        in: query
        name: mac
        required: true
        type: string
      - description: 操作设备型号，取值 Luxsin-X9 或 Luxsin-X8
        in: query
        name: model
        required: true
        type: string
      - description: 5 位分享码
        in: query
        name: shareCode
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 eq_data、model
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: 系统错误
          schema:
            additionalProperties: true
            type: object
      summary: 导入 EQ 分享码
      tags:
      - ShareCode
  /audio/shareCreate:
    post:
      consumes:
      - application/json
      description: 将用户的 EQ 数据生成一个 5 位分享码，有效期由 SHARE_CODE_TTL_MIN 配置决定（支持 30、30m、24h、30d
        等格式）
      parameters:
      - description: 分享请求，model 取值 Luxsin-X9 或 Luxsin-X8
        in: body
        name: body
        required: true
        schema:
          properties:
            eq_data:
              type: object
            mac:
              type: string
            model:
              type: string
          type: object
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 share_code、expire_at、eq_data
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: 系统错误
          schema:
            additionalProperties: true
            type: object
      summary: 创建 EQ 分享码
      tags:
      - ShareCode
  /audio/shareDelete:
    get:
      description: 根据 MAC 与分享码删除 Redis 中的分享码数据（仅创建者可删除）
      parameters:
      - description: 设备 MAC 地址
        in: query
        name: mac
        required: true
        type: string
      - description: 5 位分享码
        in: query
        name: shareCode
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 删除成功
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: 系统错误
          schema:
            additionalProperties: true
            type: object
      summary: 删除 EQ 分享码
      tags:
      - ShareCode
  /audio/shareList:
    get:
      description: 根据设备 MAC 地址查询该设备尚未过期的所有分享码（仅查询 Redis，依赖 TTL 自动过期）
      parameters:
      - description: 设备 MAC 地址
        in: query
        name: mac
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 share_codes 列表
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: 系统错误
          schema:
            additionalProperties: true
            type: object
      summary: 查询未过期分享码
      tags:
      - ShareCode
  /audio/shareQuery:
    get:
      description: 根据分享码预览 EQ 数据，不写入导入流水
      parameters:
      - description: 5 位分享码
        in: query
        name: shareCode
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: 成功返回 eq_data、expire_at、model
          schema:
            additionalProperties: true
            type: object
        "400":
          description: 参数校验失败
          schema:
            additionalProperties: true
            type: object
        "500":
          description: 系统错误
          schema:
            additionalProperties: true
            type: object
      summary: 查询 EQ 分享码
      tags:
      - ShareCode
swagger: "2.0"