eafonyang
dd92845bc2
- 增加设备持久化、阻抗数据持久化、分享码持久化定时任务 - 通过环境变量 ENABLE_PERSIST_TASK 和 ENABLE_IMPEDANCE_PERSIST_TASK 控制任务启用 - 分享码配置新增最大数量和TTL时间支持多种时间单位（m/h/d） - 实现任务批量处理、锁机制及失败重试保障数据一致性 - 定时任务启动集成至服务主流程，增强系统可配置性和运维便利性 feat(ota): 新增根据设备型号和版本号查询版本名称接口 - 实现 GET /audio/getVerName 接口返回唯一 OTA 版本名称 verName - 添加请求参数校验及错误处理逻辑 - 在仓库层新增按型号和版本号查询版本名称的方法 - 完善接口文档及Swagger定义，支持前端调用查询版本名称功能
829 lines
29 KiB
JSON
829 lines
29 KiB
JSON
{
|
||
"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
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
} |