Files

T

eafonyang 455bea8380 修复了EQ 曲线接口中，+没有转义成空格的 bug

2026-07-02 12:06:10 +08:00

57 KiB

Raw Blame History

数据模型

**本文档引用的文件** - [internal/model/brand.go](file://internal/model/brand.go) - [internal/model/model.go](file://internal/model/model.go) - [internal/model/ota.go](file://internal/model/ota.go) - [internal/model/share_code.go](file://internal/model/share_code.go) - [internal/model/target.go](file://internal/model/target.go) - [internal/model/user_device.go](file://internal/model/user_device.go) - [internal/model/user_active.go](file://internal/model/user_active.go) - [internal/repository/brand.go](file://internal/repository/brand.go) - [internal/repository/model.go](file://internal/repository/model.go) - [internal/repository/ota.go](file://internal/repository/ota.go) - [internal/repository/share_code.go](file://internal/repository/share_code.go) - [internal/repository/curve.go](file://internal/repository/curve.go) - [internal/repository/device.go](file://internal/repository/device.go) - [internal/handler/brand.go](file://internal/handler/brand.go) - [internal/handler/model.go](file://internal/handler/model.go) - [internal/handler/model_list.go](file://internal/handler/model_list.go) - [internal/handler/ota.go](file://internal/handler/ota.go) - [internal/handler/share_code.go](file://internal/handler/share_code.go) - [internal/handler/device.go](file://internal/handler/device.go) - [internal/handler/curve.go](file://internal/handler/curve.go) - [internal/router/router.go](file://internal/router/router.go) - [internal/config/database.go](file://internal/config/database.go) - [internal/config/share_code_ttl.go](file://internal/config/share_code_ttl.go) - [internal/response/response.go](file://internal/response/response.go) - [internal/task/device_persist.go](file://internal/task/device_persist.go) - [internal/task/share_code_persist.go](file://internal/task/share_code_persist.go) - [pkg/encode/base64.go](file://pkg/encode/base64.go) - [sql/model.sql](file://sql/model.sql) - [sql/ota.sql](file://sql/ota.sql) - [sql/ota_target_device.sql](file://sql/ota_target_device.sql) - [sql/black_list.sql](file://sql/black_list.sql) - [sql/share_code_log.sql](file://sql/share_code_log.sql) - [sql/user_device.sql](file://sql/user_device.sql) - [sql/user_active.sql](file://sql/user_active.sql) - [cmd/server/main.go](file://cmd/server/main.go)

更新摘要

变更内容

OTA模型字段简化：移除了pawVerCode、pawVerName、pawUrl、pawMd5四个冗余字段，OTA结构现在更加简洁
OTA灰度升级设备模型重构：从包含Type字段的定向设备改为不包含类型字段的灰度升级设备，简化了设备管理逻辑
数据库表结构同步更新：ota_target_device表移除了type字段，OTATargetDevice结构体不再包含Type字段
业务逻辑调整：OTA升级策略从"定向设备"概念转变为"灰度升级设备"概念，简化了升级控制逻辑

简介

本文件面向 Luxsin 应用 API 的数据模型，系统性梳理 Brand、Model、OTA、ShareCode、Target、UserDevice 和 UserActive 七类数据模型的设计理念、字段定义、约束条件、业务含义以及与数据库表结构的映射关系。文档还覆盖 ORM 映射配置（基于原生 sql.DB 的扫描映射）、模型验证与序列化机制、模型在各层之间的传递方式与性能考量，并给出扩展、版本管理与向后兼容的最佳实践建议。内容兼顾初学者与高级开发者，既提供高层概览，也包含代码级的可视化图示与来源标注。

项目结构

该项目采用分层架构：路由层负责请求入口与中间件；处理器层处理业务逻辑与参数解析；仓库层封装数据库访问；模型层承载数据结构；响应层统一返回格式；编码层提供可选的响应体压缩编码；配置层加载数据库、Redis等外部服务配置。新增的分享码功能、目标曲线模型和增强的OTA模型进一步完善了系统的数据模型体系。

graph TB
subgraph "应用入口"
MAIN["cmd/server/main.go"]
end
subgraph "路由层"
ROUTER["internal/router/router.go"]
end
subgraph "处理器层"
BRAND_H["internal/handler/brand.go"]
MODEL_H["internal/handler/model.go"]
MODEL_LIST_H["internal/handler/model_list.go"]
OTA_H["internal/handler/ota.go"]
DEVICE_H["internal/handler/device.go"]
SHARE_CODE_H["internal/handler/share_code.go"]
CURVE_H["internal/handler/curve.go"]
end
subgraph "仓库层"
BRAND_R["internal/repository/brand.go"]
MODEL_R["internal/repository/model.go"]
OTA_R["internal/repository/ota.go"]
DEVICE_R["internal/repository/device.go"]
SHARE_CODE_R["internal/repository/share_code.go"]
CURVE_R["internal/repository/curve.go"]
end
subgraph "模型层"
MODEL_M["internal/model/brand.go"]
MODEL_M2["internal/model/model.go"]
MODEL_M3["internal/model/ota.go"]
MODEL_M4["internal/model/user_device.go"]
MODEL_M5["internal/model/user_active.go"]
MODEL_M6["internal/model/share_code.go"]
MODEL_M7["internal/model/target.go"]
end
subgraph "缓存层"
CACHE["internal/cache/*"]
end
subgraph "响应与编码"
RESP["internal/response/response.go"]
ENCODE["pkg/encode/base64.go"]
end
subgraph "配置与数据库"
DB_CFG["internal/config/database.go"]
SHARE_TTL["internal/config/share_code_ttl.go"]
DB_SQL["sql/*.sql"]
end
subgraph "任务处理"
DEVICE_TASK["internal/task/device_persist.go"]
SHARE_TASK["internal/task/share_code_persist.go"]
end
MAIN --> ROUTER
ROUTER --> BRAND_H
ROUTER --> MODEL_H
ROUTER --> MODEL_LIST_H
ROUTER --> OTA_H
ROUTER --> DEVICE_H
ROUTER --> SHARE_CODE_H
ROUTER --> CURVE_H
BRAND_H --> BRAND_R
MODEL_H --> MODEL_R
MODEL_LIST_H --> MODEL_R
OTA_H --> OTA_R
DEVICE_H --> DEVICE_R
SHARE_CODE_H --> CACHE
SHARE_CODE_H --> SHARE_CODE_R
CURVE_H --> CURVE_R
BRAND_R --> MODEL_M
MODEL_R --> MODEL_M2
OTA_R --> MODEL_M3
DEVICE_R --> MODEL_M4
DEVICE_R --> MODEL_M5
SHARE_CODE_R --> MODEL_M6
CURVE_R --> MODEL_M7
BRAND_H --> RESP
MODEL_H --> RESP
MODEL_LIST_H --> RESP
OTA_H --> RESP
DEVICE_H --> RESP
SHARE_CODE_H --> RESP
CURVE_H --> RESP
DEVICE_H --> ENCODE
SHARE_CODE_H --> ENCODE
SHARE_TASK --> SHARE_CODE_R
DEVICE_TASK --> DEVICE_R
DB_CFG --> DB_SQL
CACHE --> SHARE_TTL

图表来源

章节来源

核心组件

传统模型层（Model）
- Brand：承载品牌标识与名称，用于品牌列表查询。
- Model：承载型号信息，包含品牌名、型号名、形态、设备类型、来源、等价键、创建时间等。
OTA固件升级模型层
- OTA：固件升级记录，包含版本信息、下载地址、MD5校验、强制升级标志、灰度发布状态、定向升级配置等。
- BlackList：OTA黑名单，记录被禁止升级的设备MAC地址。
- OTATargetDevice：OTA灰度升级设备，记录允许参与灰度升级的设备列表。
分享码模型层
- ShareCodeLog：分享码操作日志，记录导出/导入操作及EQ数据快照。
- ShareCodeData：分享码缓存数据，包含分享码、MAC地址、设备型号、EQ数据、过期时间等。
目标曲线模型层
- Target：目标曲线配置，包含标签、CSV读取标志、文件路径、贝斯增强配置等。
用户设备跟踪模型层
- UserDevice：用户设备信息，包含设备MAC地址、型号、添加时间、当前版本等。
- UserActive：用户活动记录，包含设备活跃信息、IP地址、活跃日期等。
仓库层（Repository）
- BrandRepository：提供按品牌名模糊查询的品牌列表。
- ModelRepository：提供按品牌名或型号名模糊查询的型号列表，并处理可空字段的扫描。
- OTARepository：提供OTA升级信息查询、黑名单检查、灰度升级设备查询等功能。
- DeviceRepository：提供设备信息查询、插入、更新以及活动记录管理。
- ShareCodeRepository：提供分享码日志插入、导出记录检查等功能。
- CurveRepository：提供型号和目标曲线查询功能。
处理器层（Handler）
- BrandHandler：接收查询参数，调用仓库层，支持可选的响应体 Base64 编码。
- ModelHandler：接收品牌与型号查询参数，调用仓库层，支持可选的响应体 Base64 编码。
- ModelListHandler：通过搜索客户端返回模型列表，支持可选的响应体 Base64 编码。
- OTAHandler：获取OTA升级信息，支持黑名单检查、灰度升级设备检查等功能。
- DeviceHandler：处理设备信息上报，将设备活动信息写入Redis缓存。
- ShareCodeHandler：处理分享码创建、查询、导入、删除等操作，支持Redis缓存和数据库持久化。
- CurveHandler：处理曲线数据获取，支持目标曲线配置和EQ参数化。
任务处理层
- DevicePersistTask：定时从Redis缓存批量持久化设备信息到数据库。
- ShareCodePersistTask：定时从Redis缓存批量持久化分享码日志到数据库。

章节来源

架构总览

下图展示了从请求到响应的关键路径，包括处理器、仓库、数据库与可选编码流程，以及新增的分享码功能、目标曲线配置和增强的OTA固件升级功能。

sequenceDiagram
participant C as "客户端"
participant R as "路由层"
participant H as "处理器层"
participant Repo as "仓库层"
participant Cache as "缓存层"
participant DB as "数据库"
participant Enc as "编码层"
C->>R : "POST /audio/shareCreate"
R->>H : "ShareCodeHandler.ExportShareCode"
H->>Cache : "Create(分享码, EQ数据)"
Cache-->>H : "ShareCodeData"
H->>Repo : "InsertLog(分享码日志)"
Repo->>DB : "插入分享码日志"
DB-->>Repo : "确认插入"
Repo-->>H : "确认"
H-->>C : "200 OK + 分享码信息"
C->>R : "GET /audio/shareQuery?shareCode=ABCDE"
R->>H : "ShareCodeHandler.QueryShareCode"
H->>Cache : "Get(分享码)"
Cache-->>H : "ShareCodeData"
H-->>C : "200 OK + EQ数据"
C->>R : "GET /audio/shareAccept?mac=xx&model=Luxsin-X9&shareCode=ABCDE"
R->>H : "ShareCodeHandler.ImportShareCode"
H->>Cache : "EnqueueImportLog(导入日志)"
Cache-->>H : "排队成功"
H-->>C : "200 OK + EQ数据"
C->>R : "GET /audio/getCurve?brand=xxx&name=xxx&target=xxx"
R->>H : "CurveHandler.GetCurve"
H->>Repo : "GetTargetByLabel(目标曲线)"
Repo->>DB : "查询目标曲线"
DB-->>Repo : "Target配置"
Repo-->>H : "Target配置"
H->>Cache : "GetWithFR(缓存)"
Cache-->>H : "曲线数据"
H-->>C : "200 OK + parametric_eq"

图表来源

详细组件分析

Brand 数据模型

设计理念
- 轻量级品牌实体，仅包含标识与名称，用于品牌筛选与列表展示。
字段定义与约束
- id：整数，主键，自增。
- name：字符串，非空，用于品牌名匹配与排序。
业务含义
- 作为 Model 的上游维度，配合 Model 的 brandName 字段形成关联。
数据库映射
- 表名：brand（未在本文直接列出，但与 Model 的 brand_name 关联一致）。
- 字段：id、name。
ORM 映射配置
- 使用原生 sql.DB 扫描，通过结构体标签与 Scan 对齐。
验证与序列化
- 无显式校验逻辑，依赖数据库约束与上层参数清洗。
- JSON 标签用于序列化输出。
查询流程
- 支持按品牌名模糊查询，使用 LIKE 匹配并按名称升序排列。
- 返回 []Brand 列表。

classDiagram
class Brand {
+int id
+string name
}
class BrandRepository {
-db *sql.DB
+List(ctx, brandName) []Brand
}
BrandRepository --> Brand : "返回"

图表来源

章节来源

Model 数据模型

设计理念
- 型号实体承载品牌名、型号名及可选属性（形态、设备类型、来源、等价键），并记录创建时间。
字段定义与约束
- id：整数，主键，自增。
- brandName：字符串，非空，与品牌维度关联。
- name：字符串，非空，型号名。
- form、rig、source、eqKey：字符串（指针），可空，表示形态、设备类型、来源、等价键。
- createAt：时间戳，非空，记录创建时间。
业务含义
- 作为核心产品维度，支持按品牌或型号名检索，可为空的扩展属性满足多样化设备描述。
数据库映射
- 表名：model。
- 字段：id、brand_name、name、form、rig、source、eq_key、create_at。
- 约束：唯一索引 (brand_name, name)，保证同品牌下型号名唯一。
ORM 映射配置
- 使用 sql.NullString 扫描可空列，再转换为指针字符串，避免零值歧义。
- JSON 标签用于序列化输出，可空字段支持 omitempty。
验证与序列化
- 无显式校验逻辑，依赖数据库约束与上层参数清洗。
- JSON 标签用于序列化输出。
查询流程
- ostartTime 支持按品牌名精确匹配或按型号名模糊匹配，返回 []Model 列表。
- 默认返回空切片而非 nil，便于前端处理。

classDiagram
class Model {
+int id
+string brandName
+string name
+*string form
+*string rig
+*string source
+*string eqKey
+time createAt
}
class ModelRepository {
-db *sql.DB
+List(ctx, brandName, modelName) []Model
}
ModelRepository --> Model : "返回"

图表来源

章节来源

OTA 固件升级模型

设计理念
- OTA模型用于管理固件升级信息，支持强制升级、灰度发布、灰度升级设备等功能。
- 更新：OTA模型已简化，移除了pawVerCode、pawVerName、pawUrl、pawMd5四个冗余字段，现在只包含核心升级信息字段。
- 更新：OTATargetDevice模型已重构，移除了Type字段，从"定向设备"概念转变为"灰度升级设备"概念。
字段定义与约束
- OTA模型：
  - id：整数，主键，自增。
  - VerCode：整数，版本号，用于排序。
  - VerName：字符串，版本名称。
  - URL：字符串，固件下载地址。
  - MD5：字符串，固件MD5校验值。
  - Force：BoolInt，是否强制升级（true/false）。
  - Desc：字符串指针，升级描述。
  - Model：字符串指针，对应设备型号。
  - HW：整数，硬件版本号。
  - Target：BoolInt，是否定向升级（true/false）。
  - Beta：BoolInt，是否灰度发布（true/false）。
  - StartTime：时间戳指针，升级开始时间。
  - EndTime：时间戳指针，升级结束时间。
  - Status：整数，状态（1-可用，0-不可用）。
- BlackList模型：
  - id：整数，主键，自增。
  - OTAID：整数，关联OTA记录ID。
  - Mac：字符串，设备MAC地址。
  - CreateAt：时间戳，创建时间。
- OTATargetDevice模型：
  - id：整数，主键，自增。
  - OTAID：整数，关联OTA记录ID。
  - MacAddr：字符串，设备MAC地址。
  - CreateAt：时间戳，创建时间。
业务含义
- 支持复杂的固件升级策略，包括强制升级、灰度发布、灰度升级设备管理等功能。
- 简化的字段结构提高了数据模型的清晰度和维护性。
- 灰度升级设备概念简化了设备管理逻辑，不再区分白名单和黑名单类型。
数据库映射
- 表名：ota、black_list、ota_target_device。
- 字段：完整映射关系详见数据库表结构。
- 更新：OTA表不再包含pawVerCode、pawVerName、pawUrl、pawMd5字段。
- 更新：ota_target_device表不再包含type字段。
ORM 映射配置
- 使用 sql.NullString 和 sql.NullTime 扫描可空列。
- BoolInt类型支持数据库整型与JSON布尔值的双向转换。
- JSON 标签用于序列化输出，可空字段支持 omitempty。
查询流程
- 支持多种查询策略：最新OTA记录、非黑名单OTA记录、非定向OTA记录等。
- 支持黑名单检查和灰度升级设备检查。

classDiagram
class OTA {
+int ID
+int VerCode
+string VerName
+string URL
+string MD5
+BoolInt Force
+*string Desc
+*string Model
+int HW
+BoolInt Target
+BoolInt Beta
+*time StartTime
+*time EndTime
+int Status
}
class BlackList {
+int ID
+int OTAID
+string Mac
+time CreateAt
}
class OTATargetDevice {
+int ID
+int OTAID
+string MacAddr
+time CreateAt
}
class OTARepository {
-db *sql.DB
+GetLatestOTA(ctx, model, hw, beta) *OTA
+GetLatestOTANotInBlackList(ctx, model, hw, beta, mac) *OTA
+GetLatestOTANotTarget(ctx, model, hw, beta) *OTA
+IsInBlackList(ctx, otaID, mac) bool
+FindTargetDevice(ctx, otaID, mac) *OTATargetDevice
}
OTARepository --> OTA : "返回"
OTARepository --> BlackList : "返回"
OTARepository --> OTATargetDevice : "返回"

图表来源

章节来源

分享码数据模型

设计理念
- ShareCodeLog用于记录分享码的操作日志，支持导出和导入两种操作类型。
- ShareCodeData用于Redis缓存中的分享码数据，包含完整的分享码信息和缓存状态。
字段定义与约束
- ShareCodeLog模型：
  - ID：整数，主键，自增。
  - MacAddr：字符串，设备MAC地址。
  - ShareCode：字符串，5位分享码。
  - Action：枚举，操作类型（export/import）。
  - Model：枚举，设备型号（Luxsin-X9/Luxsin-X8）。
  - IpAddr：字符串，用户IP地址。
  - EqData：JSON，EQ数据快照。
  - ExpireAt：时间戳指针，分享码到期时间。
  - CreateAt：时间戳，创建时间。
- ShareCodeData结构：
  - ShareCode：字符串，5位分享码。
  - MacAddr：字符串，创建者MAC地址。
  - IpAddr：字符串，创建者IP地址。
  - Model：字符串，设备型号。
  - EqData：字符串，EQ参数JSON。
  - ExpireAt：时间戳，过期时间。
  - Persisted：布尔值，是否已刷入数据库。
业务含义
- 支持EQ数据的分享与导入功能，提供完整的操作审计和数据快照。
数据库映射
- 表名：share_code_log。
- 字段：完整映射关系详见数据库表结构。
- 索引：对mac_addr、share_code、create_at建立索引。
ORM 映射配置
- 使用 sql.NullString 和 sql.NullTime 扫描可空列。
- JSON 标签用于序列化输出，支持复杂JSON数据存储。
查询流程
- 支持按分享码查询导出记录存在性检查。
- 支持分享码日志的插入和查询。

classDiagram
class ShareCodeLog {
+int ID
+string MacAddr
+string ShareCode
+string Action
+string Model
+string IpAddr
+[]byte EqData
+*time ExpireAt
+time CreateAt
}
class ShareCodeData {
+string ShareCode
+string MacAddr
+string IpAddr
+string Model
+string EqData
+time ExpireAt
+bool Persisted
}
class ShareCodeRepository {
-db *sql.DB
+InsertLog(ctx, log) error
+HasExportLog(ctx, shareCode) bool
}
ShareCodeRepository --> ShareCodeLog : "返回"

图表来源

章节来源

目标曲线数据模型

设计理念
- Target模型用于定义目标曲线配置，支持从CSV文件读取目标数据和贝斯增强配置。
字段定义与约束
- ID：整数，主键，自增。
- Label：字符串，目标曲线标签。
- ReadCSV：BoolInt，是否从CSV文件读取目标数据。
- File：字符串指针，CSV文件路径。
- BassBoost：字符串指针，贝斯增强配置JSON。
- AddTime：时间戳，添加时间。
业务含义
- 支持灵活的目标曲线配置，可以使用预定义的曲线名称或从CSV文件读取自定义曲线。
数据库映射
- 表名：target。
- 字段：完整映射关系详见数据库表结构。
ORM 映射配置
- 使用 BoolInt 类型支持布尔值序列化。
- JSON 标签用于序列化输出，可空字段支持 omitempty。
查询流程
- 支持按标签查询目标曲线配置。
- 支持CSV文件路径和贝斯增强配置的动态加载。

classDiagram
class Target {
+int ID
+string Label
+BoolInt ReadCSV
+*string File
+*string BassBoost
+time AddTime
}
class CurveRepository {
-db *sql.DB
+GetTargetByLabel(ctx, label) *Target
}
CurveRepository --> Target : "返回"

图表来源

章节来源

用户设备跟踪模型

设计理念
- UserDevice模型用于跟踪用户设备信息，支持设备注册、版本更新等功能。
- UserActive模型用于记录用户设备的活跃信息，支持按日期分区存储。
字段定义与约束
- UserDevice模型：
  - id：整数，主键，自增。
  - mac_addr：字符串，设备MAC地址，唯一索引。
  - model：字符串，设备型号。
  - add_time：时间戳，默认当前时间。
  - ver：字符串指针，设备当前版本。
- UserActive模型：
  - id：整数，主键。
  - mac_addr：字符串，设备MAC地址。
  - model：字符串，设备型号。
  - active_date：日期，活跃日期，联合主键。
  - ip_addr：字符串，设备IP地址。
  - create_at：时间戳，默认当前时间。
业务含义
- 支持设备信息的实时上报和历史活动记录追踪。
数据库映射
- 表名：user_device、user_active。
- 字段：完整映射关系详见数据库表结构。
- 索引：user_device的mac_addr唯一索引，user_active的(mac_addr, active_date)联合索引。
ORM 映射配置
- 使用 sql.NullString 扫描可空列。
- JSON 标签用于序列化输出。
查询流程
- 支持按MAC地址查询设备信息。
- 支持按MAC地址和日期查询活跃记录。
- 支持设备信息的插入、更新和活跃记录的插入、更新。

classDiagram
class UserDevice {
+int id
+string mac_addr
+string model
+time add_time
+*string ver
}
class UserActive {
+int id
+string mac_addr
+string model
+date active_date
+string ip_addr
+time create_at
}
class DeviceRepository {
-db *sql.DB
+FindDeviceByMac(ctx, macAddr) *UserDevice
+InsertDevice(ctx, device) error
+UpdateDeviceVer(ctx, id, ver) error
+FindActiveByMacAndDate(ctx, macAddr, activeDate) *UserActive
+InsertActive(ctx, active) error
+UpdateActiveIp(ctx, id, ipAddr) error
}
DeviceRepository --> UserDevice : "返回"
DeviceRepository --> UserActive : "返回"

图表来源

章节来源

处理器与序列化机制

统一响应体
- 统一响应体包含 code、message、data 字段，便于前端统一处理。
可选 Base64 编码
- 支持通过 base64Resp 参数控制是否对 JSON 响应进行自定义 Base64 编码。
- 自定义映射表将标准 Base64 字符集映射为更紧凑的字符集，减少体积。
OTA处理器特殊逻辑
- 支持参数校验、黑名单检查、灰度升级设备检查等复杂业务逻辑。
- 根据不同情况返回不同的OTA升级信息。
- 更新：OTA处理器现在处理简化的字段结构，移除了对paw*字段的处理。
- 更新：OTA处理器现在使用灰度升级设备概念，不再区分白名单和黑名单类型。
设备处理器特殊逻辑
- 将设备信息写入Redis缓存，支持异步持久化。
- 提供设备信息上报接口。
分享码处理器特殊逻辑
- 支持分享码创建、查询、导入、删除等完整生命周期管理。
- 使用Redis缓存提高性能，支持分布式锁保证数据一致性。
- 提供分享码数量限制和过期时间控制。
曲线处理器特殊逻辑
- 支持目标曲线配置查询和EQ参数化计算。
- 使用Redis缓存优化曲线数据访问性能。
错误处理
- 处理器捕获仓库层错误，记录日志并通过统一响应体返回内部错误。

sequenceDiagram
participant C as "客户端"
participant H as "ShareCodeHandler"
participant Cache as "ShareCodeCache"
participant Repo as "ShareCodeRepository"
participant DB as "数据库"
participant Enc as "编码层"
C->>H : "POST /audio/shareCreate"
H->>Cache : "Create(mac, model, eqData)"
Cache-->>H : "ShareCodeData"
H->>Repo : "InsertLog(export)"
Repo->>DB : "插入日志"
DB-->>Repo : "确认"
Repo-->>H : "确认"
H-->>C : "200 OK + 分享码信息"
C->>H : "GET /audio/shareAccept?shareCode=ABCDE"
H->>Cache : "EnqueueImportLog(mac, model, eqData)"
Cache-->>H : "排队成功"
H-->>C : "200 OK + EQ数据"

图表来源

章节来源

查询与过滤逻辑

Brand 查询
- 支持按品牌名模糊匹配，使用 LIKE 并按名称升序排列。
Model 查询
- 优先按品牌名精确匹配；若为空则按型号名模糊匹配；否则返回空切片。
- 扫描时将 sql.NullString 转换为指针字符串，避免零值歧义。
OTA 查询
- 支持按model+hw+beta+status=1查询最新OTA记录。
- 支持黑名单检查和灰度升级设备检查。
- 提供多种查询策略以适应不同的升级场景。
- 更新：OTA查询现在使用简化的字段列表，移除了对paw*字段的查询。
- 更新：OTA查询现在使用灰度升级设备概念，简化了设备匹配逻辑。
设备查询
- 支持按MAC地址查询设备信息。
- 支持按MAC地址和日期查询活跃记录。
- 扫描时将 sql.NullString 转换为指针字符串，避免零值歧义。
分享码查询
- 支持按MAC地址查询未过期的分享码列表。
- 支持按分享码查询单个分享码详情。
- 支持分享码导入操作的日志排队和持久化。
目标曲线查询
- 支持按标签查询目标曲线配置。
- 支持CSV文件路径和贝斯增强配置的动态加载。

flowchart TD
Start(["进入分享码查询"]) --> Params["参数校验"]
Params --> CheckMac{"mac参数是否非空?"}
CheckMac --> |是| ListByMac["ListByMac 查询"]
CheckMac --> |否| CheckCode{"shareCode参数是否5位?"}
CheckCode --> |是| GetByCode["Get 查询"]
CheckCode --> |否| Error["返回错误"]
ListByMac --> CleanExpired["清理过期条目"]
CleanExpired --> GetDetails["逐个获取详情"]
GetDetails --> ReturnList["返回分享码列表"]
GetByCode --> ReturnDetail["返回分享码详情"]
ReturnList --> End(["返回结果"])
ReturnDetail --> End
Error --> End

图表来源

章节来源

依赖分析

层间耦合
- Handler 依赖 Repository；Repository 依赖 sql.DB；Model 为纯数据结构。
- 统一响应体与编码层被 Handler 调用，降低重复逻辑。
- 新增的Redis依赖用于分享码缓存和设备信息缓存。
- 分享码功能依赖Redis缓存和数据库的双重存储。
- 目标曲线功能依赖CurveRepository和CurveCache。
外部依赖
- 数据库：MySQL，通过 sql.DB 访问。
- 日志：zap。
- Web 框架：Gin。
- 搜索：Meilisearch（ModelListHandler）。
- 缓存：Redis（Device、ShareCode、Curve相关处理器）。
- 对象存储：S3（曲线数据CSV文件）。
- 任务调度：定时任务用于设备信息和分享码持久化。
潜在循环依赖
- 当前结构清晰，无循环导入迹象。
新增依赖关系
- 分享码功能依赖Redis缓存和数据库的双重存储。
- 目标曲线功能依赖CurveRepository和CurveCache。
- OTA功能依赖多个表的关联查询。

graph LR
H_Brand["BrandHandler"] --> Repo_Brand["BrandRepository"]
H_Model["ModelHandler"] --> Repo_Model["ModelRepository"]
H_ModelList["ModelListHandler"] --> Search["Meilisearch 客户端"]
H_OTA["OTAHandler"] --> Repo_OTA["OTARepository"]
H_Device["DeviceHandler"] --> Repo_Device["DeviceRepository"]
H_ShareCode["ShareCodeHandler"] --> Cache_Share["ShareCodeCache"]
H_ShareCode --> Repo_Share["ShareCodeRepository"]
H_Curve["CurveHandler"] --> Repo_Curve["CurveRepository"]
Repo_Brand --> DB["sql.DB"]
Repo_Model --> DB
Repo_OTA --> DB
Repo_Device --> DB
Repo_Share --> DB
Repo_Curve --> DB
H_Device --> Redis["Redis Client"]
H_ShareCode --> Redis
H_Curve --> Redis
H_Curve --> S3["S3 Storage"]
H_Brand --> Resp["统一响应体"]
H_Model --> Resp
H_ModelList --> Resp
H_OTA --> Resp
H_Device --> Resp
H_ShareCode --> Resp
H_Curve --> Resp
H_Brand --> Encode["Base64 编码"]
H_Model --> Encode
H_ModelList --> Encode
Task_Device["DevicePersistTask"] --> Repo_Device
Task_Device --> Redis
Task_Share["ShareCodePersistTask"] --> Repo_Share
Task_Share --> Redis

图表来源

章节来源

性能考虑

查询优化
- Model 表对 (brand_name, name) 建有唯一索引，有利于去重与快速定位。
- OTA表对(model, hw, beta, status)建立索引，支持快速查询最新OTA记录。
- UserDevice表对(mac_addr)建立唯一索引，支持快速设备查询。
- UserActive表对(mac_addr, active_date)建立联合索引，支持按日期分区查询。
- share_code_log表对(mac_addr, share_code, create_at)建立索引，支持分享码查询。
- 查询时优先按品牌名匹配，减少 LIKE 的范围。
- 更新：OTA查询现在使用简化的字段列表，减少了不必要的字段扫描。
- 更新：OTA查询现在使用灰度升级设备概念，简化了设备匹配逻辑，提高了查询性能。
扫描与内存
- 使用 sql.NullString 扫描可空列，避免零值歧义；转换为指针字符串减少冗余存储。
- OTA模型使用BoolInt类型处理布尔值，支持数据库整型与JSON布尔值的双向转换。
- ShareCodeLog模型使用[]byte存储JSON数据，减少字符串处理开销。
缓存策略
- 设备信息先写入Redis缓存，通过定时任务批量持久化到数据库，减少数据库压力。
- 品牌和型号信息使用Redis缓存提升查询性能。
- 分享码数据使用Redis缓存，支持TTL自动过期和分布式锁保证一致性。
- 目标曲线数据使用Redis缓存，支持fr数据独立存储优化缓存空间。
编码策略
- 可选的自定义 Base64 编码可降低响应体积，适合大列表传输场景。
并发与超时
- 服务器设置读写超时与优雅关闭，保障稳定性。
- 设备持久化任务和分享码持久化任务使用定时器定期执行，避免阻塞主线程。
- 分布式锁机制保证Redis操作的原子性和数据一致性。

章节来源

故障排查指南

常见问题
- 数据库连接失败：检查环境变量与配置加载逻辑。
- 查询无结果：确认查询参数是否为空或大小写敏感；Model 查询默认返回空切片而非 nil。
- 编码异常：确认 base64Resp 参数与 JSON 序列化是否成功。
- OTA查询失败：检查model、hw参数是否正确，确认OTA记录状态是否为1。
- 设备信息未持久化：检查Redis连接和数据库连接，确认定时任务是否正常运行。
- 分享码创建失败：检查Redis连接、分享码生成算法、TTL配置。
- 分享码导入失败：检查导入日志队列、数据库连接、分布式锁状态。
- 目标曲线查询失败：检查目标曲线配置、CSV文件路径、S3访问权限。
- 更新：OTA灰度升级设备查询失败：检查ota_target_device表结构，确认type字段已被移除。
排查步骤
- 查看日志：处理器记录错误日志，统一响应体返回错误码。
- 核对数据库：确认表结构与索引是否存在。
- 验证参数：确认查询参数是否符合预期。
- 检查Redis：确认设备信息、分享码数据是否正确写入Redis缓存。
- 监控任务：确认设备持久化任务和分享码持久化任务是否按预期执行。
- 检查分布式锁：确认分享码操作的分布式锁状态和超时处理。
- 更新：检查OTA表结构，确认paw*字段不存在，验证简化的字段结构。
- 更新：检查ota_target_device表结构，确认type字段已被移除，验证灰度升级设备查询逻辑。

章节来源

结论

本项目的数据模型设计简洁明确：Brand 与 Model 分别承担品牌与型号的维度，通过仓库层的原生 SQL 访问实现高效查询；处理器层统一响应与可选编码，提升传输效率与前端体验。新增的分享码功能、目标曲线模型和增强的OTA模型进一步完善了系统的数据模型体系，支持复杂的固件升级策略、设备信息跟踪、用户行为分析和EQ数据分享功能。数据库层面通过唯一索引与合理字段设计保障一致性与性能。Redis缓存层提供了高性能的临时数据存储和分布式锁机制。

更新：OTA模型经过简化重构，移除了pawVerCode、pawVerName、pawUrl、pawMd5四个冗余字段，现在只包含核心升级信息，提高了数据模型的清晰度和维护性。同时，OTATargetDevice模型从"定向设备"概念重构为"灰度升级设备"概念，移除了Type字段，简化了设备管理逻辑，提高了系统的易用性和维护性。新的字段结构更加简洁，减少了不必要的数据冗余，同时保持了完整的升级策略支持能力。

建议在后续迭代中引入显式的校验与转换层，增强健壮性与可维护性，同时考虑添加更多的监控指标和告警机制。

附录

数据库表结构与模型映射对照

表：model
- 字段：id（主键）、brand_name、name、form、rig、source、eq_key、create_at。
- 约束：唯一索引 (brand_name, name)。
表：ota
- 字段：id（主键）、verCode、verName、url、md5、force、desc、model、hw、target、beta、startTime、endTime、status。
- 约束：无显式约束。
- 更新：移除了pawVerCode、pawVerName、pawUrl、pawMd5字段。
表：black_list
- 字段：id（主键）、ota_id、mac、create_at。
- 约束：无显式约束。
表：ota_target_device
- 字段：id（主键）、ota_id、mac_addr、create_at。
- 约束：无显式约束。
- 更新：移除了type字段，简化了灰度升级设备管理。
表：user_device
- 字段：id（主键）、mac_addr、model、add_time、ver。
- 约束：唯一索引 (mac_addr)。
表：user_active
- 字段：id、mac_addr、model、active_date、ip_addr、create_at。
- 约束：联合主键 (id, active_date)，联合索引 (mac_addr, active_date)。
表：share_code_log
- 字段：id（主键）、mac_addr、share_code、action、model、ip_addr、eq_data、expire_at、create_at。
- 约束：索引 idx_mac_addr、idx_share_code、idx_create_at。
表：target
- 字段：id（主键）、label、read_csv、file、bassBoost、addtime。
- 约束：无显式约束。
映射关系
- Model.id ↔ model.id
- Model.brandName ↔ model.brand_name
- Model.name ↔ model.name
- OTA.ID ↔ ota.id
- OTA.VerCode ↔ ota.verCode
- OTA.VerName ↔ ota.verName
- OTA.URL ↔ ota.url
- OTA.MD5 ↔ ota.md5
- OTA.Force ↔ ota.force
- OTA.Desc ↔ ota.desc
- OTA.Model ↔ ota.model
- OTA.HW ↔ ota.hw
- OTA.Target ↔ ota.target
- OTA.Beta ↔ ota.beta
- OTA.StartTime ↔ ota.startTime
- OTA.EndTime ↔ ota.endTime
- OTA.Status ↔ ota.status
- BlackList.ID ↔ black_list.id
- BlackList.OTAID ↔ black_list.ota_id
- BlackList.Mac ↔ black_list.mac
- BlackList.CreateAt ↔ black_list.create_at
- OTATargetDevice.ID ↔ ota_target_device.id
- OTATargetDevice.OTAID ↔ ota_target_device.ota_id
- OTATargetDevice.MacAddr ↔ ota_target_device.mac_addr
- OTATargetDevice.CreateAt ↔ ota_target_device.create_at
- UserDevice.id ↔ user_device.id
- UserDevice.mac_addr ↔ user_device.mac_addr
- UserDevice.model ↔ user_device.model
- UserDevice.add_time ↔ user_device.add_time
- UserDevice.ver ↔ user_device.ver
- UserActive.id ↔ user_active.id
- UserActive.mac_addr ↔ user_active.mac_addr
- UserActive.model ↔ user_active.model
- UserActive.active_date ↔ user_active.active_date
- UserActive.ip_addr ↔ user_active.ip_addr
- UserActive.create_at ↔ user_active.create_at
- ShareCodeLog.ID ↔ share_code_log.id
- ShareCodeLog.MacAddr ↔ share_code_log.mac_addr
- ShareCodeLog.ShareCode ↔ share_code_log.share_code
- ShareCodeLog.Action ↔ share_code_log.action
- ShareCodeLog.Model ↔ share_code_log.model
- ShareCodeLog.IpAddr ↔ share_code_log.ip_addr
- ShareCodeLog.EqData ↔ share_code_log.eq_data
- ShareCodeLog.ExpireAt ↔ share_code_log.expire_at
- ShareCodeLog.CreateAt ↔ share_code_log.create_at
- Target.ID ↔ target.id
- Target.Label ↔ target.label
- Target.ReadCSV ↔ target.read_csv
- Target.File ↔ target.file
- Target.BassBoost ↔ target.bassBoost
- Target.AddTime ↔ target.addtime

章节来源

请求与响应示例（路径参考）

获取品牌列表
- 路由：/audio/getBrand
- 方法：GET
- 参数：brandName（可选），base64Resp（可选）
- 返回：[]Brand 或 Base64 编码后的 JSON
- 参考路径：internal/handler/brand.go:26-50
获取型号列表
- 路由：/audio/getModel
- 方法：GET
- 参数：brandName（可选)、modelName（可选)、base64Resp（可选）
- 返回：[]Model 或 Base64 编码后的 JSON
- 参考路径：internal/handler/model.go:26-51
搜索模型列表
- 路由：/audio/modelList
- 方法：GET
- 参数：key（必需）、count（可选）、base64Resp（可选)
- 返回：[]Model 或 Base64 编码后的 JSON
- 参考路径：internal/handler/model_list.go:26-57
获取OTA升级信息
- 路由：/audio/ota
- 方法：GET
- 参数：model（必需）、hw（必需）、mac（可选）、beta（可选）、base64Resp（可选)
- 返回：OTA对象或 Base64 编码后的 JSON
- 更新：返回的OTA对象现在包含简化的字段结构
- 更新：OTA查询现在使用灰度升级设备概念，简化了设备匹配逻辑
- 参考路径：internal/handler/ota.go:23-145
设备信息上报
- 路由：/audio/reportDevInfo
- 方法：GET
- 参数：mac（必需）、model（必需）、ver（可选)
- 返回：操作结果
- 参考路径：internal/handler/device.go:27-83
创建分享码
- 路由：/audio/shareCreate
- 方法：POST
- 参数：mac（必需）、model（必需，Luxsin-X9或Luxsin-X8）、eq_data（必需，JSON）
- 返回：分享码信息和过期时间
- 参考路径：internal/handler/share_code.go:40-125
查询分享码
- 路由：/audio/shareQuery
- 方法：GET
- 参数：shareCode（必需，5位）
- 返回：EQ数据和设备型号
- 参考路径：internal/handler/share_code.go:192-211
导入分享码
- 路由：/audio/shareAccept
- 方法：GET
- 参数：mac（必需）、model（必需，Luxsin-X9或Luxsin-X8）、shareCode（必需，5位）
- 返回：EQ数据和设备型号
- 参考路径：internal/handler/share_code.go:228-279
获取目标曲线
- 路由：/audio/getCurve
- 方法：GET
- 参数：brand（必需）、name（必需）、target（必需）、base64Resp（可选)
- 返回：parametric_eq数据
- 参考路径：internal/handler/curve.go:145-198

章节来源

最佳实践建议

模型扩展
- 引入显式的校验与转换层，如参数清洗、长度限制、正则校验等。
- 对可空字段提供默认值策略，避免前端空值判断复杂化。
- OTA模型支持复杂的升级策略，建议在业务层添加更多的参数验证。
- 分享码模型支持多种设备型号，建议添加设备型号验证和限制。
- 更新：OTA模型简化后，减少了字段验证的复杂度，但仍需确保核心字段的完整性。
- 更新：OTATargetDevice模型简化后，灰度升级设备管理更加直观，减少了类型判断的复杂性。
版本管理与向后兼容
- 通过 API 版本号（如 /api/v1）隔离变更；新增字段采用可选策略，保持旧字段必填。
- 对于破坏性变更，提供迁移脚本与双写策略。
- OTA升级策略的变更需要谨慎处理，确保向后兼容性。
- 分享码功能的新增不影响现有API，保持向前兼容。
- 更新：OTA模型的简化属于向后兼容的重构，不会影响现有API调用。
- 更新：OTATargetDevice模型的重构属于概念性重构，从"定向设备"到"灰度升级设备"，保持了API的向后兼容性。
性能优化
- 为高频查询字段建立索引；避免 SELECT *，仅选择必要字段。
- 对大列表启用可选 Base64 编码；结合分页与缓存策略。
- 设备信息使用Redis缓存，定期批量持久化到数据库。
- OTA查询使用复合索引，支持快速定位最新OTA记录。
- 分享码使用Redis缓存，支持TTL自动过期和分布式锁。
- 目标曲线使用Redis缓存，优化fr数据的独立存储。
- 更新：OTA查询现在使用简化的字段列表，减少了查询开销。
- 更新：OTA查询现在使用灰度升级设备概念，简化了设备匹配逻辑，提高了查询性能。
错误处理与可观测性
- 统一错误码与消息格式；记录关键链路日志；对数据库与外部服务增加超时与重试。
- OTA查询失败需要详细的日志记录，包括参数、查询结果等。
- 设备持久化任务需要监控执行状态和错误日志。
- 分享码持久化任务需要监控Redis队列状态和数据库插入结果。
- 目标曲线查询需要监控S3访问权限和CSV文件读取。
- 更新：OTA灰度升级设备查询失败需要详细的日志记录，包括设备MAC地址和OTA ID。
安全考虑
- OTA下载链接需要安全性验证，防止恶意下载。
- 设备信息上报需要参数验证，防止注入攻击。
- 黑名单和灰度升级设备管理需要权限控制和审计日志。
- 分享码功能需要防止暴力破解，建议添加频率限制。
- 分享码删除操作需要MAC地址验证，防止越权操作。
- EQ数据存储需要JSON格式验证，防止恶意数据注入。
- 更新：灰度升级设备管理需要MAC地址验证，防止越权访问。
监控与运维
- 添加Redis连接池监控，确保缓存层稳定运行。
- 添加数据库连接池监控，避免连接泄漏。
- 添加任务调度监控，确保持久化任务正常执行。
- 添加分布式锁监控，防止死锁和资源竞争。
- 添加S3访问监控，确保CSV文件读取正常。
- 更新：监控OTA表结构变化，确保简化的字段结构得到正确应用。
- 更新：监控ota_target_device表结构变化，确保type字段已被移除，验证灰度升级设备查询逻辑。

57 KiB Raw Blame History Unescape Escape

数据模型

更新摘要

目录

简介

项目结构

核心组件

架构总览

详细组件分析

Brand 数据模型

Model 数据模型

OTA 固件升级模型

分享码数据模型

目标曲线数据模型

用户设备跟踪模型

处理器与序列化机制

查询与过滤逻辑

依赖分析

性能考虑

故障排查指南

结论

附录

数据库表结构与模型映射对照

请求与响应示例（路径参考）

最佳实践建议

57 KiB

Raw Blame History