新增项目文档

2026-06-30 14:46:52 +08:00
parent cac5bef5a7
commit 08da279275
79 changed files with 20860 additions and 0 deletions
@@ -0,0 +1,347 @@
+# 型号管理API
+
+<cite>
+**本文档引用的文件**
+- [backend/src/routes/models.js](file://backend/src/routes/models.js)
+- [backend/src/models/Model.js](file://backend/src/models/Model.js)
+- [backend/src/validators/model.js](file://backend/src/validators/model.js)
+- [backend/src/utils/response.js](file://backend/src/utils/response.js)
+- [backend/src/middleware/auth.js](file://backend/src/middleware/auth.js)
+- [frontend/src/api/model.js](file://frontend/src/api/model.js)
+- [backend/src/models/Ota.js](file://backend/src/models/Ota.js)
+- [backend/src/routes/ota.js](file://backend/src/routes/ota.js)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。
+
+## 项目结构
+型号管理API位于后端Express应用中，采用模块化设计：
+- 路由层：集中于 models.js，提供型号的增删改查、搜索推送、频响文件处理等接口
+- 模型层：Model.js 定义数据库表结构
+- 验证层：model.js 使用Zod进行请求体验证
+- 工具层：response.js 统一响应格式
+- 中间件：auth.js 提供鉴权保护
+- 前端封装：frontend/src/api/model.js 提供HTTP调用封装
+
+```mermaid
+graph TB
+FE["前端应用<br/>frontend/src/api/model.js"] --> R["路由层<br/>backend/src/routes/models.js"]
+R --> M["模型层<br/>backend/src/models/Model.js"]
+R --> V["验证层<br/>backend/src/validators/model.js"]
+R --> U["工具层<br/>backend/src/utils/response.js"]
+R --> A["中间件<br/>backend/src/middleware/auth.js"]
+R -. 关联 .-> OTA["OTA模型<br/>backend/src/models/Ota.js"]
+```
+
+图表来源
+- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
+- [backend/src/validators/model.js:1-22](file://backend/src/validators/model.js#L1-L22)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+- [frontend/src/api/model.js:1-151](file://frontend/src/api/model.js#L1-L151)
+- [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+
+章节来源
+- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
+- [backend/src/validators/model.js:1-22](file://backend/src/validators/model.js#L1-L22)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+- [frontend/src/api/model.js:1-151](file://frontend/src/api/model.js#L1-L151)
+- [backend/src/models/Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+
+## 核心组件
+- 路由控制器：models.js 提供型号的列表查询、详情获取、创建、更新、删除、搜索推送、频响文件上传与查询等接口
+- 数据模型：Model.js 定义型号字段及约束
+- 请求验证：model.js 使用Zod Schema进行创建/更新的输入校验
+- 统一响应：response.js 提供统一的响应结构
+- 鉴权中间件：auth.js 实现Bearer Token鉴权
+- 前端封装：frontend/src/api/model.js 提供HTTP调用封装
+
+章节来源
+- [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)
+- [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
+- [backend/src/validators/model.js:3-19](file://backend/src/validators/model.js#L3-L19)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+- [frontend/src/api/model.js:13-150](file://frontend/src/api/model.js#L13-L150)
+
+## 架构概览
+型号管理API采用分层架构，路由层负责HTTP协议与参数解析，模型层负责数据持久化，验证层确保输入合法性，工具层统一输出格式，中间件提供安全控制。
+
+```mermaid
+sequenceDiagram
+participant C as "客户端"
+participant R as "路由(models.js)"
+participant V as "验证(model.js)"
+participant M as "模型(Model.js)"
+participant U as "响应(response.js)"
+participant A as "鉴权(auth.js)"
+C->>R : "HTTP请求"
+R->>A : "鉴权检查"
+A-->>R : "通过/拒绝"
+R->>V : "请求体验证"
+V-->>R : "验证结果"
+R->>M : "数据库操作"
+M-->>R : "结果"
+R->>U : "封装响应"
+U-->>C : "统一响应"
+```
+
+图表来源
+- [backend/src/routes/models.js:307-361](file://backend/src/routes/models.js#L307-L361)
+- [backend/src/validators/model.js:3-19](file://backend/src/validators/model.js#L3-L19)
+- [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+
+## 详细组件分析
+
+### 型号数据模型
+型号实体包含以下字段：
+- id：自增主键
+- brand_name：品牌名称（必填，最大100字符）
+- name：型号名称（必填，最大100字符）
+- form：佩戴方式（可选，最大100字符）
+- rig：阻抗（可选，最大100字符）
+- source：来源（可选，最大100字符）
+- eq_key：EQ键（可选，最大255字符）
+- create_at：创建时间（默认当前时间）
+
+```mermaid
+erDiagram
+MODEL {
+int id PK
+string brand_name
+string name
+string form
+string rig
+string source
+string eq_key
+datetime create_at
+}
+```
+
+图表来源
+- [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
+
+章节来源
+- [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
+
+### 型号参数验证规则
+- 创建请求体验证：
+  - brand_name：字符串，长度1-100
+  - name：字符串，长度1-100
+  - form/rig/source/eq_key：字符串，最大长度分别为100、100、100、255，可为空
+- 更新请求体验证：
+  - 字段同上，但允许部分字段为空（表示不更新）
+
+章节来源
+- [backend/src/validators/model.js:3-19](file://backend/src/validators/model.js#L3-L19)
+
+### 型号CRUD接口
+
+#### 1) 型号列表查询
+- 方法与路径：GET /api/models/
+- 认证：需要登录（Bearer Token）
+- 查询参数：
+  - skip：跳过数量，默认0
+  - limit：返回数量，默认100，上限1000
+  - brand_name：品牌名称（模糊匹配）
+  - name：型号名称（模糊匹配）
+  - sort_by：排序字段，id 或 create_at，默认id
+  - sort_order：asc 或 desc，默认desc
+- 成功响应：包含items、total、skip、limit的分页数据
+- 异常响应：统一错误码与消息
+
+章节来源
+- [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+
+#### 2) 型号详情获取
+- 方法与路径：GET /api/models/:model_id
+- 认证：需要登录
+- 路径参数：model_id（整数）
+- 成功响应：型号基础字段
+- 异常响应：未找到或通用错误
+
+章节来源
+- [backend/src/routes/models.js:280-304](file://backend/src/routes/models.js#L280-L304)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+
+#### 3) 型号创建
+- 方法与路径：POST /api/models/
+- 认证：需要登录
+- 内容类型：multipart/form-data
+- 表单字段：
+  - measurement_file：频响文件（CSV/TXT/JSON），可选
+  - brand_name、name、form、rig、source、eq_key
+- 文件处理：
+  - TXT文件自动转换为CSV
+  - 仅允许.csv、.txt、.json
+  - 上传至S3，键值包含source、form、brand_name、name
+- 成功响应：创建后的型号信息
+- 异常响应：重复、格式不支持、通用错误
+
+章节来源
+- [backend/src/routes/models.js:306-361](file://backend/src/routes/models.js#L306-L361)
+- [backend/src/validators/model.js:3-10](file://backend/src/validators/model.js#L3-L10)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+
+#### 4) 型号更新
+- 方法与路径：PUT /api/models/:model_id
+- 认证：需要登录
+- 内容类型：multipart/form-data
+- 路径参数：model_id（整数）
+- 表单字段：同创建，支持部分字段更新（传入'null'表示保持原值）
+- 文件处理：同创建，若上传需提供source与form
+- 成功响应：更新后的型号信息
+- 异常响应：未找到、重复、格式不支持、通用错误
+
+章节来源
+- [backend/src/routes/models.js:363-436](file://backend/src/routes/models.js#L363-L436)
+- [backend/src/validators/model.js:12-19](file://backend/src/validators/model.js#L12-L19)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+
+#### 5) 型号删除
+- 方法与路径：DELETE /api/models/:model_id
+- 认证：需要登录
+- 路径参数：model_id（整数）
+- 删除流程：
+  - 先从Meilisearch删除对应文档
+  - 再删除数据库记录
+- 成功响应：删除成功
+- 异常响应：未找到、Meilisearch删除失败、通用错误
+
+章节来源
+- [backend/src/routes/models.js:438-464](file://backend/src/routes/models.js#L438-L464)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+
+### 型号搜索、过滤与排序
+- 支持按品牌名称与型号名称进行模糊过滤
+- 支持按id或create_at排序，升序/降序
+- 分页参数：skip、limit（上限1000）
+
+章节来源
+- [backend/src/routes/models.js:136-157](file://backend/src/routes/models.js#L136-L157)
+
+### 型号与OTA固件的一对多关联
+- 关联字段：OTA模型中的model字段用于标识对应设备型号
+- 查询示例：可通过OTA路由按model字段过滤
+- 级联建议：删除型号前应清理或迁移相关OTA记录，避免悬挂引用
+
+```mermaid
+erDiagram
+MODEL ||--o{ OTA : "一对多"
+MODEL {
+int id PK
+string brand_name
+string name
+}
+OTA {
+int id PK
+int verCode
+string verName
+string model
+}
+```
+
+图表来源
+- [backend/src/models/Model.js:4-50](file://backend/src/models/Model.js#L4-L50)
+- [backend/src/models/Ota.js:44-48](file://backend/src/models/Ota.js#L44-L48)
+
+章节来源
+- [backend/src/models/Ota.js:44-48](file://backend/src/models/Ota.js#L44-L48)
+
+### Meilisearch搜索推送与校验
+- 校验接口：POST /api/models/push-to-search/validate
+  - 输入：model_ids数组
+  - 输出：通过校验的型号数量或具体校验失败项
+- 推送接口：POST /api/models/push-to-search
+  - 输入：model_ids数组
+  - 输出：推送成功数量、任务ID与推送数据
+
+章节来源
+- [backend/src/routes/models.js:466-566](file://backend/src/routes/models.js#L466-L566)
+
+### 频响文件上传与查询
+- 上传：POST /api/models/（multipart/form-data），支持TXT自动转换为CSV
+- 查询：GET /api/models/:model_id/measurement（仅Eafonyoung来源且存在form时可用）
+
+章节来源
+- [backend/src/routes/models.js:306-361](file://backend/src/routes/models.js#L306-L361)
+- [backend/src/routes/models.js:246-278](file://backend/src/routes/models.js#L246-L278)
+
+### EQ缓存与Meilisearch文档查询
+- 获取Redis EQ缓存键：GET /api/models/:model_id/eq-cache
+- 获取指定Hash Field：GET /api/models/:model_id/eq-cache/field?key=...
+- 查询Meilisearch推送状态：GET /api/models/:model_id/meilisearch
+
+章节来源
+- [backend/src/routes/models.js:183-244](file://backend/src/routes/models.js#L183-L244)
+
+## 依赖分析
+- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互
+- 模型依赖：Model.js 依赖Sequelize ORM
+- 前端依赖：frontend/src/api/model.js 依赖通用请求封装
+
+```mermaid
+graph LR
+R["models.js"] --> M["Model.js"]
+R --> V["model.js(Zod)"]
+R --> U["response.js"]
+R --> A["auth.js"]
+R -. 外部 .-> MS["Meilisearch"]
+R -. 外部 .-> S3["S3存储"]
+```
+
+图表来源
+- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
+- [backend/src/validators/model.js:1-22](file://backend/src/validators/model.js#L1-L22)
+- [backend/src/utils/response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+
+章节来源
+- [backend/src/routes/models.js:1-569](file://backend/src/routes/models.js#L1-L569)
+
+## 性能考虑
+- 分页限制：列表查询limit上限为1000，避免一次性返回过多数据
+- Meilisearch超时：查询与删除文档设置超时，防止阻塞
+- 文件上传：内存存储multer，建议在高并发场景下优化为流式处理或外部对象存储直传
+- 验证前置：使用Zod在进入数据库操作前完成字段校验，减少无效请求
+
+## 故障排除指南
+- 401 未登录/无效凭证：检查Authorization头是否为Bearer Token且有效
+- 403 需要超级管理员权限：确认用户角色
+- 404 未找到资源：确认model_id是否存在
+- 重复型号：创建/更新时如提示品牌+型号已存在，请调整参数
+- 文件格式不支持：仅允许.csv、.txt、.json，TXT会自动转换为CSV
+- Meilisearch异常：检查服务连通性与API密钥
+
+章节来源
+- [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
+- [backend/src/routes/models.js:314-317](file://backend/src/routes/models.js#L314-L317)
+- [backend/src/routes/models.js:322-325](file://backend/src/routes/models.js#L322-L325)
+- [backend/src/routes/models.js:450-455](file://backend/src/routes/models.js#L450-L455)
+
+## 结论
+型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略，并在删除型号前做好OTA关联清理。