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