全新的 ui，soybean admin

2026-07-17 09:35:32 +08:00
parent e59d9c72ee
commit 1da6d72544
501 changed files with 11790 additions and 22638 deletions
@@ -23,11 +23,11 @@

 ## 更新摘要
 **变更内容**
- 统一操作按钮样式为圆形图标格式，提升可访问性和用户体验
- 所有功能按钮（搜索、重置、新增等）采用统一的圆形设计语言
- 为每个按钮添加适当的title属性，增强屏幕阅读器支持
- 简化按钮实现，从冗长的文本按钮转换为简洁的图标按钮
- 保持功能完整性，同时优化界面视觉一致性
+- OTA固件管理功能完全重写，增强了上传能力、进度跟踪和设备定向功能
+- 改进了固件版本管理系统，支持更灵活的版本控制和发布策略
+- 新增了黑名单管理和定向升级功能，实现设备级别的精细化管控
+- 统一了操作按钮的视觉风格，采用圆形图标设计提升可访问性和用户体验
+- 优化了前端界面交互，提供更友好的用户操作流程

 ## 目录
 1. [简介](#简介)
@@ -41,10 +41,10 @@
 9. [结论](#结论)

 ## 简介
-本文件面向OTA固件管理页面的使用者与维护者，系统性阐述固件版本管理功能，涵盖固件上传、版本控制、强制更新配置、发布状态管理、兼容性检查、更新策略配置、用户通知机制、下载统计、版本历史与回滚功能，以及进度监控、错误处理与用户体验优化方案。**本次更新统一了操作按钮的视觉风格，采用圆形图标设计提升界面的可访问性和用户体验**。
+本文件面向OTA固件管理页面的使用者与维护者，系统性阐述固件版本管理功能，涵盖固件上传、版本控制、强制更新配置、发布状态管理、兼容性检查、更新策略配置、用户通知机制、下载统计、版本历史与回滚功能，以及进度监控、错误处理与用户体验优化方案。**本次更新对OTA固件管理进行了完全重写，大幅增强了上传能力、进度跟踪、设备定向和固件版本管理系统**。

 ## 项目结构
-系统采用前后端分离架构，前端使用Vue 3 + Element Plus，后端使用Node.js + Express + Sequelize，数据库为MySQL。OTA模块位于独立的路由与模型中，存储策略针对不同设备型号采用差异化方案（X8上传至S3，X9本地存储）。**新增了黑名单和定向升级的独立管理模块，并统一了所有操作按钮的圆形图标样式**。
+系统采用前后端分离架构，前端使用Vue 3 + Element Plus，后端使用Node.js + Express + Sequelize，数据库为MySQL。OTA模块位于独立的路由与模型中，存储策略针对不同设备型号采用差异化方案（X8上传至S3，X9本地存储）。**新版本完全重写了OTA固件管理功能，新增了黑名单和定向升级的独立管理模块，并统一了所有操作按钮的圆形图标样式**。

 ```mermaid
 graph TB
@@ -74,14 +74,14 @@ FE --> THEME["主题样式<br/>styles/lux-theme.css"]
 - [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)

 ## 核心组件
- 前端视图组件：负责搜索、分页、表单校验、上传与CRUD操作，提供友好的用户交互体验。**所有操作按钮已统一采用圆形图标设计，提升可访问性**。
- API封装：统一封装GET/POST/PUT/DELETE请求，处理超时与认证头注入。
- 后端路由：提供OTA版本列表、详情、创建、更新、删除与升级包上传接口。**新增黑名单和定向升级的CRUD接口**。
- 数据模型：定义OTA版本的数据结构与约束，确保版本号唯一性与字段完整性。**新增黑名单和定向升级的数据模型**。
- 存储服务：根据设备型号选择不同的存储策略（S3/X9本地），并生成公开访问链接。
- 响应封装：统一返回格式，便于前端处理与展示。
- 环境配置：区分开发/生产环境，影响存储目录与S3凭据策略。
- **主题样式**：统一的圆形按钮样式和玻璃拟态效果，提升整体视觉一致性。
+- **增强版前端视图组件**：负责搜索、分页、表单校验、上传与CRUD操作，提供友好的用户交互体验。**所有操作按钮已统一采用圆形图标设计，提升可访问性**。
+- **改进的API封装**：统一封装GET/POST/PUT/DELETE请求，处理超时与认证头注入。
+- **重构的后端路由**：提供OTA版本列表、详情、创建、更新、删除与升级包上传接口。**新增黑名单和定向升级的CRUD接口**。
+- **增强的数据模型**：定义OTA版本的数据结构与约束，确保版本号唯一性与字段完整性。**新增黑名单和定向升级的数据模型**。
+- **优化的存储服务**：根据设备型号选择不同的存储策略（S3/X9本地），并生成公开访问链接。
+- **统一的响应封装**：统一返回格式，便于前端处理与展示。
+- **灵活的环境配置**：区分开发/生产环境，影响存储目录与S3凭据策略。
+- **现代化的主题样式**：统一的圆形按钮样式和玻璃拟态效果，提升整体视觉一致性。

 **章节来源**
 - [index.vue:1-1059](file://frontend/src/views/ota/index.vue#L1-L1059)
@@ -139,15 +139,15 @@ API-->>FE : 渲染结果

 ## 详细组件分析

-### 前端页面组件（OTA管理）
- 搜索与筛选：支持按版本名称、设备型号、状态、版本号精确/模糊查询。
- 表格展示：显示版本号、版本名、设备型号、硬件版本、包地址、强升、灰度、状态等字段。
- 表单与校验：版本号必填且为整数，版本名1-20字符，MD5必须为32位十六进制，下载地址在非上传模式下必填。
- 上传流程：仅当设备型号为X8/X9时显示上传按钮，自动计算MD5并生成公开下载地址。
- CRUD操作：支持新增、编辑、复制（基于现有行）、删除，均通过API封装调用后端接口。
- 分页与加载：支持每页数量切换与页码切换，加载状态通过Element Plus的loading指示。
- **新增功能**：在更多操作菜单中集成了黑名单管理和定向升级功能，支持对单个OTA版本进行设备级别的管控。
- **统一按钮样式**：**所有操作按钮已标准化为圆形图标格式，包括搜索、重置、新增等操作，每个按钮都添加了适当的title属性以提升可访问性**。
+### 增强版前端页面组件（OTA管理）
+- **增强的搜索与筛选**：支持按版本名称、设备型号、状态、版本号精确/模糊查询。
+- **改进的表格展示**：显示版本号、版本名、设备型号、硬件版本、包地址、强升、灰度、状态等字段。
+- **完善的表单与校验**：版本号必填且为整数，版本名1-20字符，MD5必须为32位十六进制，下载地址在非上传模式下必填。
+- **优化的上传流程**：仅当设备型号为X8/X9时显示上传按钮，自动计算MD5并生成公开下载地址。
+- **完整的CRUD操作**：支持新增、编辑、复制（基于现有行）、删除，均通过API封装调用后端接口。
+- **智能的分页与加载**：支持每页数量切换与页码切换，加载状态通过Element Plus的loading指示。
+- **新增的设备管控功能**：在更多操作菜单中集成了黑名单管理和定向升级功能，支持对单个OTA版本进行设备级别的管控。
+- **统一的按钮样式**：**所有操作按钮已标准化为圆形图标格式，包括搜索、重置、新增等操作，每个按钮都添加了适当的title属性以提升可访问性**。

 ```mermaid
 flowchart TD
@@ -184,8 +184,8 @@ Reload --> Render
 - [index.vue:1-1059](file://frontend/src/views/ota/index.vue#L1-L1059)
 - [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/（需登录），支持分页与多条件过滤。
@@ -195,8 +195,8 @@ Reload --> Render
  - 删除：DELETE /api/ota/:ota_id（需登录）。
  - **新增黑名单接口**：GET/POST/PUT/DELETE /api/blacklist/（需登录），支持黑名单的CRUD操作。
  - **新增定向升级接口**：GET/POST/PUT/DELETE /api/ota-target-device/（需登录），支持定向升级设备的CRUD操作。
- 参数校验：使用Zod Schema进行严格的字段类型与长度校验。
- 错误处理：统一使用ApiResponse封装，区分成功、错误与无数据三类返回码。
+- **严格的参数校验**：使用Zod Schema进行严格的字段类型与长度校验。
+- **统一的错误处理**：统一使用ApiResponse封装，区分成功、错误与无数据三类返回码。

 ```mermaid
 sequenceDiagram
@@ -245,8 +245,8 @@ TD_RT-->>FE : ApiResponse.success()
 - [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
 - [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

-### 数据模型与约束
- 关键字段：
+### 增强的数据模型与约束
+- **关键字段**：
  - verCode：整数版本号，用于排序与比较。
  - verName：版本名称，最大20字符。
  - url：升级包下载地址。
@@ -256,8 +256,8 @@ TD_RT-->>FE : ApiResponse.success()
  - hw：硬件版本号。
  - target/beta/status：定向发布、灰度发布与启用状态。
  - startTime/endTime：发布时间窗口。
- 唯一性约束：verCode+model组合唯一，防止重复版本。
- 默认值：force、target、beta、status等字段提供合理默认值。
+- **唯一性约束**：verCode+model组合唯一，防止重复版本。
+- **默认值设置**：force、target、beta、status等字段提供合理默认值。
 - **新增黑名单模型**：包含ota_id（关联OTA版本）、mac（MAC地址）字段，支持按OTA版本和MAC地址进行设备级管控。
 - **新增定向升级模型**：包含ota_id（关联OTA版本）、mac_addr（MAC地址）字段，支持指定设备进行定向升级。

@@ -306,14 +306,14 @@ OTA ||--o{ OTA_TARGET_DEVICE : "包含"
 - [BlackList.js:1-36](file://backend/src/models/BlackList.js#L1-L36)
 - [OtaTargetDevice.js:1-37](file://backend/src/models/OtaTargetDevice.js#L1-L37)

-### 存储策略与安全
- 设备型号差异化：
+### 优化的存储策略与安全
+- **设备型号差异化存储**：
  - Luxsin-X8：上传至S3，生成公开访问URL，支持显式凭证或IAM角色。
  - Luxsin-X9：保存到本地目录（/data/projects/source），按年月与MD5前缀组织目录结构，生成公开URL。
- 目录与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凭据策略。
@@ -337,26 +337,26 @@ BuildX9 --> Return
 - [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，失败时给出具体错误信息。
@@ -365,7 +365,7 @@ BuildX9 --> Return
  - **新增弹窗管理**：黑名单和定向升级分别通过独立弹窗进行管理，支持MAC地址的批量添加和删除。
  - **MAC地址格式校验**：支持AA:BB:CC:DD:EE:FF格式的MAC地址输入和验证。
  - **统一按钮样式**：**所有操作按钮已标准化为圆形图标格式，提供更好的可访问性和一致的视觉体验**。
- 后端：
+- **后端增强**：
  - 统一响应格式：code=1成功、code=0错误、code=2无数据。
  - 错误分类：参数错误、业务冲突（版本已存在）、存储异常（S3上传失败）、权限错误等。
  - 日志记录：关键操作与异常均有日志输出，便于排查。
@@ -376,7 +376,7 @@ BuildX9 --> Return
 - [ota.js:25-66](file://backend/src/routes/ota.js#L25-L66)
 - [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)

-### 统一按钮样式设计
+### 统一的按钮样式设计
 - **圆形图标按钮**：所有主要操作按钮（搜索、重置、新增等）均采用圆形设计，提升界面的一致性和现代感。
 - **可访问性增强**：每个按钮都添加了适当的title属性，确保屏幕阅读器能够正确描述按钮功能。
 - **图标语义化**：使用Element Plus提供的图标库，如Search（搜索）、Refresh（重置）、Plus（新增）等，确保图标含义清晰。
@@ -390,14 +390,14 @@ BuildX9 --> Return
 - [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)

 ### 黑名单管理功能
- 功能概述：支持将特定设备的MAC地址加入黑名单，阻止这些设备接收OTA更新。
- 界面集成：在OTA版本的"更多操作"菜单中新增"黑名单"选项，点击后弹出黑名单管理弹窗。
- 操作流程：
+- **功能概述**：支持将特定设备的MAC地址加入黑名单，阻止这些设备接收OTA更新。
+- **界面集成**：在OTA版本的"更多操作"菜单中新增"黑名单"选项，点击后弹出黑名单管理弹窗。
+- **操作流程**：
  - 打开黑名单弹窗后，输入设备MAC地址并点击"添加"按钮。
  - 支持批量MAC地址添加，每个MAC地址一行。
  - 可以查看当前OTA版本的所有黑名单设备列表。
  - 支持删除不需要的黑名单设备。
- 数据验证：MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式，且每个MAC地址都必须唯一。
+- **数据验证**：MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式，且每个MAC地址都必须唯一。

 **章节来源**
 - [index.vue:683-772](file://frontend/src/views/ota/index.vue#L683-L772)
@@ -405,32 +405,32 @@ BuildX9 --> Return
 - [blacklist.js:96-204](file://backend/src/routes/blacklist.js#L96-L204)

 ### 定向升级功能
- 功能概述：支持指定特定设备的MAC地址进行定向升级，只有这些设备能够接收到OTA更新。
- 界面集成：在OTA版本的"更多操作"菜单中新增"定向升级"选项，点击后弹出定向升级管理弹窗。
- 操作流程：
+- **功能概述**：支持指定特定设备的MAC地址进行定向升级，只有这些设备能够接收到OTA更新。
+- **界面集成**：在OTA版本的"更多操作"菜单中新增"定向升级"选项，点击后弹出定向升级管理弹窗。
+- **操作流程**：
  - 打开定向升级弹窗后，输入目标设备的MAC地址并点击"添加"按钮。
  - 支持批量MAC地址添加，每个MAC地址一行。
  - 可以查看当前OTA版本的所有定向升级设备列表。
  - 支持删除不需要的定向升级设备。
- 数据验证：MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式，且每个MAC地址在同一个OTA版本内必须唯一。
+- **数据验证**：MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式，且每个MAC地址在同一个OTA版本内必须唯一。

 **章节来源**
- [index.vue:774-855](file://frontend/src/views/ota/index.vue#L774-L855)
+- [index.vue:774-855](file://frontend/src/views/ota/index.vue#L774-855)
 - [otaTargetDevice.js:12-55](file://frontend/src/api/otaTargetDevice.js#L12-L55)
 - [otaTargetDevice.js:96-208](file://backend/src/routes/otaTargetDevice.js#L96-L208)

 ## 依赖关系分析
- 前端依赖：
+- **前端依赖**：
  - 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
@@ -462,18 +462,18 @@ BE --> AW["AWS SDK"]
 - [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)

 ## 性能考虑
- 文件上传：
+- **文件上传优化**：
  - 使用内存存储缓冲区，适合中小文件；大文件建议分片上传或流式传输。
  - 上传超时设置为5分钟，适用于较大包体的上传场景。
- 数据查询：
+- **数据查询优化**：
  - 列表接口限制每页最大1000条，避免一次性返回过多数据。
  - 搜索条件尽量使用索引字段（如verCode、model、status），减少全表扫描。
- 存储策略：
+- **存储策略优化**：
  - X8使用S3，具备高可用与全球分发优势；X9本地存储需关注磁盘空间与IO瓶颈。
  - 目录按年月与MD5前缀组织，有利于快速定位与清理。
- 响应格式：
+- **响应格式优化**：
  - 统一的响应结构便于前端缓存与错误处理，减少重复解析成本。
- **黑名单和定向升级查询优化**：
+- **设备管控查询优化**：
  - 黑名单和定向升级列表查询支持按OTA版本过滤，减少不必要的数据传输。
  - 支持MAC地址模糊查询，提升用户体验。
 - **按钮样式性能**：
@@ -481,19 +481,19 @@ BE --> AW["AWS SDK"]
  - CSS样式采用高效的类选择器，避免了复杂的嵌套样式计算。

 ## 故障排除指南
- 上传失败：
+- **上传问题**：
  - 检查设备型号是否在支持列表（Luxsin-X8/Luxsin-X9）。
  - 确认S3配置（区域、桶名、凭据）或本地存储目录权限。
  - 查看后端日志中的错误信息（如S3上传失败）。
- 版本冲突：
+- **版本冲突**：
  - 创建/更新时提示"该版本已存在"，请修改版本号或设备型号组合。
- 权限问题：
+- **权限问题**：
  - 未登录或Token过期时会被重定向到登录页；超级管理员权限不足时会被拒绝访问。
- 网络异常：
+- **网络异常**：
  - 前端请求拦截器会捕获401/403错误并提示，同时清除本地认证信息。
- 页面空白或API失败：
+- **页面空白或API失败**：
  - 检查Nginx代理是否指向后端服务，确认容器健康状态与日志输出。
- **黑名单和定向升级问题**：
+- **设备管控问题**：
  - MAC地址格式错误：确保输入AA:BB:CC:DD:EE:FF格式。
  - OTA版本不存在：确认选择的OTA版本ID有效。
  - 重复的MAC地址：黑名单和定向升级中的MAC地址在同一OTA版本内必须唯一。
@@ -511,4 +511,4 @@ BE --> AW["AWS SDK"]
 - [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)

 ## 结论
-OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式，实现了从版本上传、存储、查询到发布的完整闭环。**本次更新统一了操作按钮的视觉风格，采用圆形图标设计显著提升了界面的可访问性和用户体验**。X8/X9差异化存储策略兼顾了可扩展性与易用性，配合严格的参数校验与完善的错误处理，为设备端的兼容性检查与更新策略提供了可靠支撑。**新增的黑名单和定向升级功能使得OTA管理更加灵活，能够满足不同场景下的设备管控需求**。统一的圆形按钮设计不仅提升了界面的现代化程度，还增强了屏幕阅读器的支持，使整个系统更加符合无障碍访问标准。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能，并持续优化上传体验与性能表现。
+OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式，实现了从版本上传、存储、查询到发布的完整闭环。**本次更新对OTA固件管理进行了完全重写，大幅增强了上传能力、进度跟踪、设备定向和固件版本管理系统**。X8/X9差异化存储策略兼顾了可扩展性与易用性，配合严格的参数校验与完善的错误处理，为设备端的兼容性检查与更新策略提供了可靠支撑。**新增的黑名单和定向升级功能使得OTA管理更加灵活，能够满足不同场景下的设备管控需求**。统一的圆形按钮设计不仅提升了界面的现代化程度，还增强了屏幕阅读器的支持，使整个系统更加符合无障碍访问标准。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能，并持续优化上传体验与性能表现。