新增功能

2026-05-27 18:07:55 +08:00
parent fe7b61d8d1
commit 36c6ca2766
37 changed files with 11023 additions and 39 deletions
@@ -0,0 +1,466 @@
+# API 接口文档
+
+<cite>
+**本文引用的文件**
+- [cmd/server/main.go](file://cmd/server/main.go)
+- [internal/router/router.go](file://internal/router/router.go)
+- [internal/handler/health.go](file://internal/handler/health.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/device.go](file://internal/handler/device.go)
+- [internal/response/response.go](file://internal/response/response.go)
+- [internal/middleware/cors.go](file://internal/middleware/cors.go)
+- [internal/middleware/logger.go](file://internal/middleware/logger.go)
+- [internal/middleware/request_id.go](file://internal/middleware/request_id.go)
+- [internal/search/meilisearch.go](file://internal/search/meilisearch.go)
+- [internal/repository/brand.go](file://internal/repository/brand.go)
+- [internal/repository/model.go](file://internal/repository/model.go)
+- [pkg/encode/base64.go](file://pkg/encode/base64.go)
+- [internal/config/config.go](file://internal/config/config.go)
+- [README.md](file://README.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细接口说明](#详细接口说明)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与可用性](#性能与可用性)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件为 Luxsin 应用 API 的完整接口文档，覆盖品牌管理、型号管理、设备上报与系统健康检查等接口。文档提供各接口的 HTTP 方法、URL 模式、请求参数、响应格式、错误处理、使用示例与最佳实践，并说明认证方式、速率限制策略、版本信息、客户端实现建议、调试与监控方法，以及向后兼容性与迁移注意事项。
+
+## 项目结构
+- 入口程序负责初始化配置、数据库、搜索引擎与缓存，构建路由并启动 HTTP 服务。
+- 路由层按版本与业务域分组，注册各处理器。
+- 处理器负责参数解析、调用仓储或搜索客户端、返回统一响应格式。
+- 统一响应体封装了状态码、消息与数据字段，便于前端一致化处理。
+- 中间件提供 CORS、日志与请求 ID 注入，便于跨域、可观测与追踪。
+- 搜索与缓存分别对接 Meilisearch 与 Redis，支撑型号检索与设备上报数据存储。
+
+```mermaid
+graph TB
+subgraph "服务进程"
+MAIN["cmd/server/main.go<br/>启动与生命周期"]
+ROUTER["internal/router/router.go<br/>路由注册"]
+end
+subgraph "HTTP 层"
+CORS["internal/middleware/cors.go<br/>CORS"]
+LOGMW["internal/middleware/logger.go<br/>访问日志"]
+RID["internal/middleware/request_id.go<br/>请求ID注入"]
+end
+subgraph "业务层"
+HEALTH["internal/handler/health.go<br/>健康检查"]
+BRAND["internal/handler/brand.go<br/>品牌列表"]
+MODEL["internal/handler/model.go<br/>型号详情"]
+MODELLIST["internal/handler/model_list.go<br/>型号检索"]
+DEVICE["internal/handler/device.go<br/>设备上报"]
+end
+subgraph "数据与外部服务"
+RESP["internal/response/response.go<br/>统一响应"]
+DB["MySQL(由配置驱动)"]
+MS["Meilisearch(由配置驱动)"]
+REDIS["Redis(由配置驱动)"]
+end
+MAIN --> ROUTER
+ROUTER --> CORS --> LOGMW --> RID
+ROUTER --> HEALTH
+ROUTER --> BRAND
+ROUTER --> MODEL
+ROUTER --> MODELLIST
+ROUTER --> DEVICE
+BRAND --> DB
+MODEL --> DB
+MODELLIST --> MS
+DEVICE --> REDIS
+HEALTH --> RESP
+BRAND --> RESP
+MODEL --> RESP
+MODELLIST --> RESP
+DEVICE --> RESP
+```
+
+图表来源
+- [cmd/server/main.go:22-96](file://cmd/server/main.go#L22-L96)
+- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
+- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
+- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
+- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
+- [internal/handler/health.go:14-19](file://internal/handler/health.go#L14-L19)
+- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
+- [internal/handler/model.go:26-51](file://internal/handler/model.go#L26-L51)
+- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
+- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
+- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
+
+章节来源
+- [cmd/server/main.go:22-96](file://cmd/server/main.go#L22-L96)
+- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
+- [README.md:1-123](file://README.md#L1-L123)
+
+## 核心组件
+- 路由与中间件
+  - 路由在 /api/v1 下提供健康检查，在 /audio 下提供品牌、型号、型号检索与设备上报接口。
+  - 中间件链：恢复、请求 ID、日志、CORS。
+- 统一响应
+  - 所有接口返回统一结构，包含 code、message、data 字段；错误时 code 为非零。
+- 搜索与缓存
+  - 型号检索通过 Meilisearch 客户端完成；设备上报通过 Redis Hash 存储。
+- 编码扩展
+  - 支持 base64Resp 参数，将响应体 JSON 再做自定义 Base64 编码传输，便于某些网络环境或协议需求。
+
+章节来源
+- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
+- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
+- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
+- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
+- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
+- [internal/search/meilisearch.go:17-46](file://internal/search/meilisearch.go#L17-L46)
+- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
+
+## 架构总览
+以下序列图展示一次典型请求从接入到响应的全链路：
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant G as "Gin 路由"
+participant MW as "中间件(CORS/日志/请求ID)"
+participant H as "处理器"
+participant S as "搜索/缓存/数据库"
+C->>G : "HTTP 请求"
+G->>MW : "中间件链"
+MW-->>G : "注入请求ID/日志/CORS"
+G->>H : "匹配路由并调用处理器"
+H->>S : "读取/写入(数据库/搜索/缓存)"
+S-->>H : "结果/错误"
+H-->>G : "统一响应体"
+G-->>C : "HTTP 响应(JSON/可选base64)"
+```
+
+图表来源
+- [internal/router/router.go:27-38](file://internal/router/router.go#L27-L38)
+- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
+- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
+- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
+- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
+- [internal/handler/model.go:26-51](file://internal/handler/model.go#L26-L51)
+- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
+- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
+- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
+
+## 详细接口说明
+
+### 版本与基础信息
+- 版本分组
+  - /api/v1：健康检查
+  - /audio：品牌、型号、型号检索、设备上报
+- 认证方式
+  - 当前实现未内置鉴权逻辑，未发现显式的 Token/签名/密钥校验流程。
+- 速率限制
+  - 当前实现未内置全局限流策略，如需请结合网关或中间件扩展。
+- 基础响应结构
+  - 成功：code=0，message="ok"，data 为业务数据
+  - 失败：code 非 0，message 为错误描述
+- base64Resp
+  - 可选查询参数 base64Resp=true|1|空 时，将响应体 JSON 再进行自定义 Base64 编码返回；默认开启。
+
+章节来源
+- [internal/router/router.go:27-38](file://internal/router/router.go#L27-L38)
+- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
+- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
+
+### 健康检查 /api/v1/health
+- 方法与路径
+  - GET /api/v1/health
+- 请求参数
+  - 无
+- 响应
+  - data.status = "up"
+- 错误处理
+  - 无内部错误路径，始终返回成功
+- 使用场景
+  - 服务存活探测、负载均衡探活
+- 示例
+  - curl: [README.md:83-99](file://README.md#L83-L99)
+
+章节来源
+- [internal/router/router.go:29](file://internal/router/router.go#L29)
+- [internal/handler/health.go:14-19](file://internal/handler/health.go#L14-L19)
+- [README.md:83-99](file://README.md#L83-L99)
+
+### 品牌管理 /audio/getBrand
+- 方法与路径
+  - GET /audio/getBrand
+- 请求参数
+  - brandName: 可选，用于模糊过滤品牌名称
+  - base64Resp: 可选，是否对响应体进行二次 Base64 编码
+- 响应数据
+  - 列表项包含品牌 id 与 name
+- 错误处理
+  - 数据库查询异常：统一返回内部错误
+  - 编码异常：统一返回内部错误
+- 使用场景
+  - 获取品牌列表，支持按名称模糊筛选
+- 示例
+  - curl: [README.md:101-109](file://README.md#L101-L109)
+
+章节来源
+- [internal/router/router.go:34](file://internal/router/router.go#L34)
+- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
+- [internal/repository/brand.go:20-51](file://internal/repository/brand.go#L20-L51)
+- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
+- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
+- [README.md:101-109](file://README.md#L101-L109)
+
+### 型号管理 /audio/getModel
+- 方法与路径
+  - GET /audio/getModel
+- 请求参数
+  - brandName: 可选，按品牌过滤
+  - modelName: 可选，按型号名称模糊过滤
+  - base64Resp: 可选，是否对响应体进行二次 Base64 编码
+- 响应数据
+  - 列表项包含 id、brand_name、name、form、rig、source、eq_key、create_at；部分字段可能为空
+- 错误处理
+  - 数据库查询异常：统一返回内部错误
+  - 编码异常：统一返回内部错误
+- 使用场景
+  - 获取指定品牌或型号的详细列表
+- 示例
+  - 无直接示例，但可通过组合 brandName 与 modelName 参数实现不同维度查询
+
+章节来源
+- [internal/router/router.go:35](file://internal/router/router.go#L35)
+- [internal/handler/model.go:26-51](file://internal/handler/model.go#L26-L51)
+- [internal/repository/model.go:20-95](file://internal/repository/model.go#L20-L95)
+- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
+- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
+
+### 型号检索 /audio/modelList
+- 方法与路径
+  - GET /audio/modelList
+- 请求参数
+  - key: 必填，检索关键词
+  - count: 可选，最大返回条数，默认 100
+  - base64Resp: 可选，是否对响应体进行二次 Base64 编码
+- 响应数据
+  - 列表项包含 rig、form、name、brand_name、source、eq_key 等字段
+- 错误处理
+  - 搜索异常：统一返回内部错误
+  - 编码异常：统一返回内部错误
+- 使用场景
+  - 基于关键词的型号检索，适用于推荐、搜索框等
+- 示例
+  - 无直接示例，但可参考 Meilisearch 的检索行为
+
+章节来源
+- [internal/router/router.go:36](file://internal/router/router.go#L36)
+- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
+- [internal/search/meilisearch.go:22-46](file://internal/search/meilisearch.go#L22-L46)
+- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
+- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
+
+### 设备上报 /audio/reportDevInfo
+- 方法与路径
+  - GET /audio/reportDevInfo
+- 请求参数
+  - mac: 必填，设备 MAC 地址
+  - model: 必填，设备型号
+  - ver: 可选，版本号
+  - X-Forwarded-For: 可选，客户端 IP（由代理注入）
+- 响应
+  - 成功：code=200，msg="操作成功"
+  - 参数缺失：code=400，msg="参数校验失败"
+  - 系统错误：code=500，msg="系统错误"
+- 存储行为
+  - 将设备信息以 JSON 形式写入 Redis Hash，键为 devices，field 为 mac
+- 错误处理
+  - 参数校验失败：返回业务错误
+  - JSON 序列化失败：返回内部错误
+  - Redis 写入失败：返回内部错误
+- 使用场景
+  - 客户端上报设备活跃信息，便于后续统计与分析
+- 示例
+  - 无直接示例，可参考响应结构与参数说明
+
+章节来源
+- [internal/router/router.go:37](file://internal/router/router.go#L37)
+- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
+- [internal/response/response.go:15-37](file://internal/response/response.go#L15-L37)
+
+## 依赖关系分析
+
+```mermaid
+classDiagram
+class Router {
+New(log, db, search, redis) Engine
+}
+class HealthHandler
+class BrandHandler {
+-repo BrandRepository
+GetBrand(c)
+}
+class ModelHandler {
+-repo ModelRepository
+GetModel(c)
+}
+class ModelListHandler {
+-search SearchClient
+ModelList(c)
+}
+class DeviceHandler {
+-redis RedisClient
+ReportDevInfo(c)
+}
+class BrandRepository {
+List(ctx, brandName) []Brand
+}
+class ModelRepository {
+List(ctx, brandName, modelName) []Model
+}
+class SearchClient {
+ModelList(ctx, key, count) []map
+}
+class Response {
+OK(c, data)
+Fail(c, httpStatus, code, msg)
+BadRequest(c, msg)
+InternalError(c, msg)
+}
+class Middleware_CORS
+class Middleware_Logger
+class Middleware_RequestID
+Router --> HealthHandler
+Router --> BrandHandler
+Router --> ModelHandler
+Router --> ModelListHandler
+Router --> DeviceHandler
+BrandHandler --> BrandRepository
+ModelHandler --> ModelRepository
+ModelListHandler --> SearchClient
+DeviceHandler --> Response
+BrandHandler --> Response
+ModelHandler --> Response
+ModelListHandler --> Response
+HealthHandler --> Response
+Router --> Middleware_CORS
+Router --> Middleware_Logger
+Router --> Middleware_RequestID
+```
+
+图表来源
+- [internal/router/router.go:14-42](file://internal/router/router.go#L14-L42)
+- [internal/handler/health.go:8-18](file://internal/handler/health.go#L8-L18)
+- [internal/handler/brand.go:14-24](file://internal/handler/brand.go#L14-L24)
+- [internal/handler/model.go:14-24](file://internal/handler/model.go#L14-L24)
+- [internal/handler/model_list.go:14-24](file://internal/handler/model_list.go#L14-L24)
+- [internal/handler/device.go:14-24](file://internal/handler/device.go#L14-L24)
+- [internal/repository/brand.go:12-18](file://internal/repository/brand.go#L12-L18)
+- [internal/repository/model.go:12-18](file://internal/repository/model.go#L12-L18)
+- [internal/search/meilisearch.go:13-20](file://internal/search/meilisearch.go#L13-L20)
+- [internal/response/response.go:9-37](file://internal/response/response.go#L9-L37)
+- [internal/middleware/cors.go:7-21](file://internal/middleware/cors.go#L7-L21)
+- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
+- [internal/middleware/request_id.go:20-31](file://internal/middleware/request_id.go#L20-L31)
+
+## 性能与可用性
+- 并发与超时
+  - 服务器设置读/写超时与空闲超时，避免慢请求占用资源。
+- 日志与追踪
+  - 中间件记录状态码、方法、路径、延迟、IP、请求 ID，便于定位问题。
+- 缓存与搜索
+  - 型号检索使用 Meilisearch，具备高性能全文检索能力；设备上报使用 Redis Hash，适合高并发写入。
+- 响应体积控制
+  - base64Resp 可降低传输体积，但会增加 CPU 开销；建议在带宽受限或协议限制场景启用。
+- 建议
+  - 对高频接口增加本地缓存（如品牌/型号列表）与 CDN 加速静态资源。
+  - 对设备上报接口增加幂等与去重策略，避免重复写入。
+
+章节来源
+- [cmd/server/main.go:66-72](file://cmd/server/main.go#L66-L72)
+- [internal/middleware/logger.go:10-46](file://internal/middleware/logger.go#L10-L46)
+- [internal/search/meilisearch.go:22-46](file://internal/search/meilisearch.go#L22-L46)
+- [pkg/encode/base64.go:44-52](file://pkg/encode/base64.go#L44-L52)
+
+## 故障排查指南
+- 健康检查失败
+  - 检查 /api/v1/health 是否返回 status=up；若失败，查看服务日志与数据库连接状态。
+- 品牌/型号接口异常
+  - 关注数据库连接与查询异常日志；确认 SQL 查询条件与参数传递正确。
+- 型号检索失败
+  - 检查 Meilisearch 连接、索引配置与 API Key；确认关键词与返回字段。
+- 设备上报失败
+  - 检查 Redis 连接与 HSET 写入；确认 mac 与 model 参数必填；关注 JSON 序列化错误。
+- 统一错误响应
+  - 所有错误均通过统一响应体返回，code 非 0 表示失败，message 描述错误原因。
+
+章节来源
+- [internal/handler/health.go:14-19](file://internal/handler/health.go#L14-L19)
+- [internal/handler/brand.go:30-35](file://internal/handler/brand.go#L30-L35)
+- [internal/handler/model.go:31-36](file://internal/handler/model.go#L31-L36)
+- [internal/handler/model_list.go:37-42](file://internal/handler/model_list.go#L37-L42)
+- [internal/handler/device.go:61-78](file://internal/handler/device.go#L61-L78)
+- [internal/response/response.go:23-37](file://internal/response/response.go#L23-L37)
+
+## 结论
+本项目采用清晰的分层架构与统一响应体设计，覆盖品牌、型号、检索与设备上报等核心业务场景。当前未内置鉴权与限流机制，建议在生产环境中补充安全与容量治理措施。通过中间件与日志体系，系统具备良好的可观测性，便于运维与排障。
+
+## 附录
+
+### 端到端调用流程（示例）
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Router as "路由"
+participant Handler as "处理器"
+participant DBMS as "数据库"
+participant Search as "Meilisearch"
+participant Cache as "Redis"
+Client->>Router : "GET /audio/getBrand?brandName=sony"
+Router->>Handler : "GetBrand"
+Handler->>DBMS : "查询品牌列表"
+DBMS-->>Handler : "品牌列表"
+Handler-->>Router : "统一响应"
+Router-->>Client : "JSON/可选base64"
+Client->>Router : "GET /audio/modelList?key=wha&count=50"
+Router->>Handler : "ModelList"
+Handler->>Search : "关键词检索"
+Search-->>Handler : "检索结果"
+Handler-->>Router : "统一响应"
+Router-->>Client : "JSON/可选base64"
+Client->>Router : "GET /audio/reportDevInfo?mac=xx&model=yy&ver=v1"
+Router->>Handler : "ReportDevInfo"
+Handler->>Cache : "HSET devices : mac -> JSON"
+Cache-->>Handler : "写入成功"
+Handler-->>Router : "统一响应"
+Router-->>Client : "JSON"
+```
+
+图表来源
+- [internal/router/router.go:34-37](file://internal/router/router.go#L34-L37)
+- [internal/handler/brand.go:26-50](file://internal/handler/brand.go#L26-L50)
+- [internal/handler/model_list.go:26-57](file://internal/handler/model_list.go#L26-L57)
+- [internal/handler/device.go:26-85](file://internal/handler/device.go#L26-L85)
+- [internal/repository/brand.go:20-51](file://internal/repository/brand.go#L20-L51)
+- [internal/search/meilisearch.go:22-46](file://internal/search/meilisearch.go#L22-L46)
+
+### 配置与部署要点
+- 环境变量
+  - APP_ENV、APP_HOST、APP_PORT、GIN_MODE 等；数据库、Meilisearch、Redis 配置通过独立模块加载。
+- 启动与运行
+  - 支持开发与生产模式；生产模式下 Gin 运行模式切换为 Release。
+- 健康检查
+  - 提供 /api/v1/health 作为探活端点。
+
+章节来源
+- [internal/config/config.go:18-64](file://internal/config/config.go#L18-L64)
+- [cmd/server/main.go:28-30](file://cmd/server/main.go#L28-L30)
+- [README.md:83-99](file://README.md#L83-L99)