新增项目文档

2026-06-30 14:46:52 +08:00
parent cac5bef5a7
commit 08da279275
79 changed files with 20860 additions and 0 deletions
@@ -0,0 +1,388 @@
+# OTA固件管理页面
+
+<cite>
+**本文档引用的文件**
+- [Ota.js](file://backend/src/models/Ota.js)
+- [ota.js](file://backend/src/routes/ota.js)
+- [otaStorage.js](file://backend/src/services/otaStorage.js)
+- [index.vue](file://frontend/src/views/ota/index.vue)
+- [ota.js](file://frontend/src/api/ota.js)
+- [response.js](file://backend/src/utils/response.js)
+- [env.js](file://backend/src/config/env.js)
+- [request.js](file://frontend/src/utils/request.js)
+- [router/index.js](file://frontend/src/router/index.js)
+- [DEPLOY.md](file://DEPLOY.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+本文件面向OTA固件管理页面的使用者与维护者，系统性阐述固件版本管理功能，涵盖固件上传、版本控制、强制更新配置、发布状态管理、兼容性检查、更新策略配置、用户通知机制、下载统计、版本历史与回滚功能，以及进度监控、错误处理与用户体验优化方案。文档以仓库现有代码为依据，结合前后端交互流程，提供可操作的实践指导。
+
+## 项目结构
+系统采用前后端分离架构，前端使用Vue 3 + Element Plus，后端使用Node.js + Express + Sequelize，数据库为MySQL。OTA模块位于独立的路由与模型中，存储策略针对不同设备型号采用差异化方案（X8上传至S3，X9本地存储）。
+
+```mermaid
+graph TB
+FE["前端界面<br/>views/ota/index.vue"] --> API["API封装<br/>api/ota.js"]
+API --> AXIOS["HTTP请求封装<br/>utils/request.js"]
+AXIOS --> ROUTER["路由守卫<br/>router/index.js"]
+ROUTER --> BE["后端服务<br/>routes/ota.js"]
+BE --> MODEL["数据模型<br/>models/Ota.js"]
+BE --> STORAGE["存储服务<br/>services/otaStorage.js"]
+STORAGE --> ENV["环境配置<br/>config/env.js"]
+```
+
+图表来源
+- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+- [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
+- [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
+- [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+
+章节来源
+- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+- [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
+- [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
+- [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+
+## 核心组件
+- 前端视图组件：负责搜索、分页、表单校验、上传与CRUD操作，提供友好的用户交互体验。
+- API封装：统一封装GET/POST/PUT/DELETE请求，处理超时与认证头注入。
+- 后端路由：提供OTA版本列表、详情、创建、更新、删除与升级包上传接口。
+- 数据模型：定义OTA版本的数据结构与约束，确保版本号唯一性与字段完整性。
+- 存储服务：根据设备型号选择不同的存储策略（S3/X9本地），并生成公开访问链接。
+- 响应封装：统一返回格式，便于前端处理与展示。
+- 环境配置：区分开发/生产环境，影响存储目录与S3凭据策略。
+
+章节来源
+- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+- [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
+- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+
+## 架构总览
+OTA固件管理页面的端到端流程如下：
+- 用户在前端页面进行搜索与分页浏览；
+- 通过API封装发起HTTP请求；
+- 后端路由接收请求，进行鉴权与参数校验；
+- 数据模型层保证数据一致性；
+- 存储服务根据设备型号执行差异化存储；
+- 统一响应格式返回给前端，前端渲染结果。
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant FE as "前端视图<br/>index.vue"
+participant API as "API封装<br/>api/ota.js"
+participant AX as "HTTP封装<br/>utils/request.js"
+participant RT as "后端路由<br/>routes/ota.js"
+participant MD as "数据模型<br/>models/Ota.js"
+participant ST as "存储服务<br/>services/otaStorage.js"
+U->>FE : 搜索/分页/新增/编辑
+FE->>API : 调用列表/创建/更新/删除/上传
+API->>AX : 发起HTTP请求
+AX->>RT : 路由处理鉴权/参数校验
+RT->>MD : 查询/写入数据库
+RT->>ST : 上传升级包按设备型号
+ST-->>RT : 返回存储结果URL/MD5/S3Key
+RT-->>AX : 统一响应格式
+AX-->>API : 返回数据
+API-->>FE : 渲染结果
+```
+
+图表来源
+- [index.vue:420-579](file://frontend/src/views/ota/index.vue#L420-L579)
+- [ota.js:13-67](file://frontend/src/api/ota.js#L13-L67)
+- [request.js:11-69](file://frontend/src/utils/request.js#L11-L69)
+- [ota.js:24-268](file://backend/src/routes/ota.js#L24-L268)
+- [Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
+- [otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
+
+## 详细组件分析
+
+### 前端页面组件（OTA管理）
+- 搜索与筛选：支持按版本名称、设备型号、状态、版本号精确/模糊查询。
+- 表格展示：显示版本号、版本名、设备型号、硬件版本、包地址、强升、灰度、状态等字段。
+- 表单与校验：版本号必填且为整数，版本名1-20字符，MD5必须为32位十六进制，下载地址在非上传模式下必填。
+- 上传流程：仅当设备型号为X8/X9时显示上传按钮，自动计算MD5并生成公开下载地址。
+- CRUD操作：支持新增、编辑、复制（基于现有行）、删除，均通过API封装调用后端接口。
+- 分页与加载：支持每页数量切换与页码切换，加载状态通过Element Plus的loading指示。
+
+```mermaid
+flowchart TD
+Start(["进入页面"]) --> LoadData["加载数据<br/>getOtaList()"]
+LoadData --> Render["渲染表格与分页"]
+Render --> Search["用户输入搜索条件"]
+Search --> Apply["应用筛选并重新加载"]
+Apply --> Render
+Render --> Action{"用户操作"}
+Action --> |新增| OpenAdd["打开新增对话框"]
+Action --> |编辑| OpenEdit["打开编辑对话框"]
+Action --> |复制| CopyRow["复制行数据到表单"]
+Action --> |删除| ConfirmDel["确认删除"]
+OpenAdd --> Submit["提交表单"]
+OpenEdit --> Submit
+CopyRow --> Submit
+ConfirmDel --> Delete["调用删除接口"]
+Submit --> Reload["刷新列表"]
+Delete --> Reload
+Reload --> Render
+```
+
+图表来源
+- [index.vue:420-579](file://frontend/src/views/ota/index.vue#L420-L579)
+- [ota.js:13-49](file://frontend/src/api/ota.js#L13-L49)
+
+章节来源
+- [index.vue:1-628](file://frontend/src/views/ota/index.vue#L1-L628)
+- [ota.js:1-68](file://frontend/src/api/ota.js#L1-L68)
+
+### 后端路由与控制器
+- 接口设计：
+  - 上传升级包：POST /api/ota/upload-package（需登录），支持X8/X9两种设备型号，返回MD5、文件名、URL等。
+  - 最新版本检查：GET /api/ota/latest/check（无需登录），设备端调用，返回满足条件的最新版本。
+  - 列表查询：GET /api/ota/（需登录），支持分页与多条件过滤。
+  - 详情查询：GET /api/ota/:ota_id（需登录）。
+  - 创建：POST /api/ota/（需登录），校验版本号唯一性与字段合法性。
+  - 更新：PUT /api/ota/:ota_id（需登录），支持部分字段更新与版本号冲突检测。
+  - 删除：DELETE /api/ota/:ota_id（需登录）。
+- 参数校验：使用Zod Schema进行严格的字段类型与长度校验。
+- 错误处理：统一使用ApiResponse封装，区分成功、错误与无数据三类返回码。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端"
+participant RT as "后端路由<br/>routes/ota.js"
+participant VL as "校验器<br/>validators/ota.js"
+participant MD as "模型<br/>models/Ota.js"
+participant ST as "存储服务<br/>services/otaStorage.js"
+FE->>RT : POST /api/ota/upload-package
+RT->>VL : 校验请求体
+RT->>ST : 读取内容并计算MD5
+alt X9
+RT->>ST : 本地保存并生成URL
+else X8
+RT->>ST : 上传S3并生成URL
+end
+ST-->>RT : 返回存储结果
+RT-->>FE : ApiResponse.success()
+FE->>RT : POST /api/ota/
+RT->>VL : 校验创建Schema
+RT->>MD : 检查版本号唯一性
+RT->>MD : 写入数据库
+MD-->>RT : 返回新记录
+RT-->>FE : ApiResponse.success()
+```
+
+图表来源
+- [ota.js:24-268](file://backend/src/routes/ota.js#L24-L268)
+- [ota.js:3-33](file://backend/src/validators/ota.js#L3-L33)
+- [Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
+- [otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
+
+章节来源
+- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
+- [ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+
+### 数据模型与约束
+- 关键字段：
+  - verCode：整数版本号，用于排序与比较。
+  - verName：版本名称，最大20字符。
+  - url：升级包下载地址。
+  - md5：32位十六进制MD5值，用于完整性校验。
+  - force：是否强制更新（0/1）。
+  - model：设备型号（Luxsin-X8/Luxsin-X9）。
+  - hw：硬件版本号。
+  - target/beta/status：定向发布、灰度发布与启用状态。
+  - startTime/endTime：发布时间窗口。
+- 唯一性约束：verCode+model组合唯一，防止重复版本。
+- 默认值：force、target、beta、status等字段提供合理默认值。
+
+```mermaid
+erDiagram
+OTA {
+int id PK
+int verCode
+string verName
+string url
+string md5
+smallint force
+string desc
+string model
+int hw
+smallint target
+smallint beta
+datetime startTime
+datetime endTime
+smallint status
+datetime create_at
+}
+```
+
+图表来源
+- [Ota.js:4-94](file://backend/src/models/Ota.js#L4-L94)
+
+章节来源
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+
+### 存储策略与安全
+- 设备型号差异化：
+  - Luxsin-X8：上传至S3，生成公开访问URL，支持显式凭证或IAM角色。
+  - Luxsin-X9：保存到本地目录（/data/projects/source），按年月与MD5前缀组织目录结构，生成公开URL。
+- 目录与URL构建：
+  - X8：S3 Key为 `ota/{YYYYMM}/x8/{md5前5位}/LUXSIN_X8.PKG`，公开URL基于配置拼接。
+  - X9：本地路径为 `{OTA_UPLOAD_DIR}/ota/{YYYYMM}/x9/{md5前5位}/LUXSIN.PKG`，公开URL基于配置拼接。
+- 环境变量：
+  - AWS_REGION、AWS_S3_OTA_BUCKET、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY。
+  - OTA_X8_PUBLIC_BASE、OTA_X9_URL_BASE、OTA_UPLOAD_DIR。
+  - APP_ENV决定开发/生产环境，影响存储目录与S3凭据策略。
+
+```mermaid
+flowchart TD
+Upload["上传请求"] --> Detect["识别设备型号"]
+Detect --> |X8| S3["上传S3"]
+Detect --> |X9| Local["本地保存"]
+S3 --> BuildX8["构建S3 Key与URL"]
+Local --> BuildX9["构建本地路径与URL"]
+BuildX8 --> Return["返回MD5/URL/S3Key"]
+BuildX9 --> Return
+```
+
+图表来源
+- [otaStorage.js:46-103](file://backend/src/services/otaStorage.js#L46-L103)
+- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+
+章节来源
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+- [env.js:1-13](file://backend/src/config/env.js#L1-L13)
+
+### 兼容性检查与更新策略
+- 设备端最新版本检查：
+  - 接口：GET /api/ota/latest/check，参数包含当前版本号、设备型号与硬件版本。
+  - 逻辑：查询状态为可用、版本号大于当前版本、匹配设备型号与硬件版本的最高版本。
+  - 结果：若找到则返回该版本信息，否则返回无数据。
+- 强制更新与定向发布：
+  - 强制更新：force=1时，客户端应阻止用户跳过更新。
+  - 定向发布：target=1时，仅对特定用户或设备生效。
+  - 灰度发布：beta=1时，按比例或规则逐步放量。
+- 时间窗口：
+  - startTime/endTime限定发布时间范围，超出范围的版本不应被推送。
+
+章节来源
+- [ota.js:68-102](file://backend/src/routes/ota.js#L68-L102)
+
+### 用户体验与错误处理
+- 前端：
+  - 加载状态：表格区域整体loading，避免闪烁。
+  - 表单校验：实时校验版本号、版本名、MD5与下载地址，错误提示明确。
+  - 上传反馈：上传成功后自动填充MD5与URL，失败时给出具体错误信息。
+  - 删除确认：二次确认对话框，防止误删。
+  - 分页与重置：支持页码与每页数量调整，重置搜索条件。
+- 后端：
+  - 统一响应格式：code=1成功、code=0错误、code=2无数据。
+  - 错误分类：参数错误、业务冲突（版本已存在）、存储异常（S3上传失败）等。
+  - 日志记录：关键操作与异常均有日志输出，便于排查。
+
+章节来源
+- [index.vue:305-338](file://frontend/src/views/ota/index.vue#L305-L338)
+- [response.js:1-25](file://backend/src/utils/response.js#L1-L25)
+- [ota.js:25-66](file://backend/src/routes/ota.js#L25-L66)
+
+## 依赖关系分析
+- 前端依赖：
+  - Element Plus：UI组件库，提供表格、表单、对话框、分页等。
+  - Axios：HTTP客户端，封装基础URL与拦截器。
+  - Vue Router：路由守卫，控制访问权限与超级管理员限制。
+- 后端依赖：
+  - Express：Web框架，提供REST接口。
+  - Sequelize：ORM，连接MySQL并管理模型。
+  - Zod：Schema校验，确保请求参数合法。
+  - Multer：内存存储上传文件缓冲区。
+  - AWS SDK：S3上传能力。
+- 环境变量：
+  - 前后端共享的关键变量：JWT密钥、数据库连接、S3配置、OTA相关URL与存储目录。
+
+```mermaid
+graph LR
+FE["前端"] --> EP["Element Plus"]
+FE --> AX["Axios"]
+FE --> VR["Vue Router"]
+BE["后端"] --> EX["Express"]
+BE --> SQ["Sequelize"]
+BE --> ZD["Zod"]
+BE --> ML["Multer"]
+BE --> AW["AWS SDK"]
+```
+
+图表来源
+- [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
+- [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+
+章节来源
+- [request.js:1-72](file://frontend/src/utils/request.js#L1-L72)
+- [router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+- [ota.js:1-292](file://backend/src/routes/ota.js#L1-L292)
+- [Ota.js:1-97](file://backend/src/models/Ota.js#L1-L97)
+- [ota.js:1-36](file://backend/src/validators/ota.js#L1-L36)
+- [otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
+
+## 性能考虑
+- 文件上传：
+  - 使用内存存储缓冲区，适合中小文件；大文件建议分片上传或流式传输。
+  - 上传超时设置为5分钟，适用于较大包体的上传场景。
+- 数据查询：
+  - 列表接口限制每页最大1000条，避免一次性返回过多数据。
+  - 搜索条件尽量使用索引字段（如verCode、model、status），减少全表扫描。
+- 存储策略：
+  - X8使用S3，具备高可用与全球分发优势；X9本地存储需关注磁盘空间与IO瓶颈。
+  - 目录按年月与MD5前缀组织，有利于快速定位与清理。
+- 响应格式：
+  - 统一的响应结构便于前端缓存与错误处理，减少重复解析成本。
+
+## 故障排除指南
+- 上传失败：
+  - 检查设备型号是否在支持列表（Luxsin-X8/Luxsin-X9）。
+  - 确认S3配置（区域、桶名、凭据）或本地存储目录权限。
+  - 查看后端日志中的错误信息（如S3上传失败）。
+- 版本冲突：
+  - 创建/更新时提示“该版本已存在”，请修改版本号或设备型号组合。
+- 权限问题：
+  - 未登录或Token过期时会被重定向到登录页；超级管理员权限不足时会被拒绝访问。
+- 网络异常：
+  - 前端请求拦截器会捕获401/403错误并提示，同时清除本地认证信息。
+- 页面空白或API失败：
+  - 检查Nginx代理是否指向后端服务，确认容器健康状态与日志输出。
+
+章节来源
+- [ota.js:25-66](file://backend/src/routes/ota.js#L25-L66)
+- [request.js:44-69](file://frontend/src/utils/request.js#L44-L69)
+- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
+
+## 结论
+OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式，实现了从版本上传、存储、查询到发布的完整闭环。X8/X9差异化存储策略兼顾了可扩展性与易用性，配合严格的参数校验与完善的错误处理，为设备端的兼容性检查与更新策略提供了可靠支撑。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能，并持续优化上传体验与性能表现。