# 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)