docs(tabs): 更新标签页视图组件设计与交互细节

- 采用固定内边距策略,解决标签页悬停时的布局抖动问题
- 统一关闭按钮尺寸为14x14px,提升视觉一致性
- 优化活动标签和悬停状态的层级管理,确保视觉层次正确
- 增强视觉反馈,添加内嵌阴影效果改善用户体验
- 添加平滑颜色过渡动画(0.2秒),提升交互流畅度
- 支持玻璃拟态设计系统,实现现代化视觉风格
- 完善工具箱图标支持,确保标签页工具功能准确显示
This commit is contained in:
eafonyang
2026-07-15 09:58:56 +08:00
parent 003b44e2bd
commit f48f1cce70
27 changed files with 670 additions and 212 deletions
@@ -1,7 +1,7 @@
# 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)
@@ -18,15 +18,16 @@
- [request.js](file://frontend/src/utils/request.js)
- [router/index.js](file://frontend/src/router/index.js)
- [DEPLOY.md](file://DEPLOY.md)
- [lux-theme.css](file://frontend/src/styles/lux-theme.css)
</cite>
## 更新摘要
**变更内容**
- 集成黑名单管理功能,支持按MAC地址阻止设备接收OTA更新
- 集成定向升级功能,支持指定设备进行定向升级
- 在OTA管理页面中新增黑名单和定向升级的操作入口
- 新增黑名单和定向升级的独立管理页面
- 完善OTA版本管理的完整生命周期管理体验
- 统一操作按钮样式为圆形图标格式,提升可访问性和用户体验
- 所有功能按钮(搜索、重置、新增等)采用统一的圆形设计语言
- 为每个按钮添加适当的title属性,增强屏幕阅读器支持
- 简化按钮实现,从冗长的文本按钮转换为简洁的图标按钮
- 保持功能完整性,同时优化界面视觉一致性
## 目录
1. [简介](#简介)
@@ -40,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本地存储)。**新增了黑名单和定向升级的独立管理模块,并统一了所有操作按钮的圆形图标样式**。
```mermaid
graph TB
@@ -60,32 +61,36 @@ BLACKLIST_BE --> BLACKLIST_MODEL["黑名单模型<br/>models/BlackList.js"]
FE --> TARGET_API["定向升级API<br/>api/otaTargetDevice.js"]
TARGET_API --> TARGET_BE["定向升级路由<br/>routes/otaTargetDevice.js"]
TARGET_BE --> TARGET_MODEL["定向升级模型<br/>models/OtaTargetDevice.js"]
FE --> THEME["主题样式<br/>styles/lux-theme.css"]
```
**图表来源**
- [index.vue:1-1003](file://frontend/src/views/ota/index.vue#L1-L1003)
- [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)
- [blacklist.js:1-57](file://frontend/src/api/blacklist.js#L1-L57)
- [otaTargetDevice.js:1-57](file://frontend/src/api/otaTargetDevice.js#L1-L57)
- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)
- [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)
## 核心组件
- 前端视图组件:负责搜索、分页、表单校验、上传与CRUD操作,提供友好的用户交互体验。**新增了黑名单和定向升级的弹窗管理功能**。
- 前端视图组件:负责搜索、分页、表单校验、上传与CRUD操作,提供友好的用户交互体验。**所有操作按钮已统一采用圆形图标设计,提升可访问性**。
- API封装:统一封装GET/POST/PUT/DELETE请求,处理超时与认证头注入。
- 后端路由:提供OTA版本列表、详情、创建、更新、删除与升级包上传接口。**新增黑名单和定向升级的CRUD接口**。
- 数据模型:定义OTA版本的数据结构与约束,确保版本号唯一性与字段完整性。**新增黑名单和定向升级的数据模型**。
- 存储服务:根据设备型号选择不同的存储策略(S3/X9本地),并生成公开访问链接。
- 响应封装:统一返回格式,便于前端处理与展示。
- 环境配置:区分开发/生产环境,影响存储目录与S3凭据策略。
- **主题样式**:统一的圆形按钮样式和玻璃拟态效果,提升整体视觉一致性。
**章节来源**
- [index.vue:1-1003](file://frontend/src/views/ota/index.vue#L1-L1003)
- [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)
- [blacklist.js:1-57](file://frontend/src/api/blacklist.js#L1-L57)
- [otaTargetDevice.js:1-57](file://frontend/src/api/otaTargetDevice.js#L1-L57)
- [blacklist.js:1-223](file://backend/src/routes/blacklist.js#L1-L223)
- [otaTargetDevice.js:1-248](file://backend/src/routes/otaTargetDevice.js#L1-L248)
- [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)
## 架构总览
OTA固件管理页面的端到端流程如下:
@@ -106,7 +111,7 @@ 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 : 搜索/分页/新增/编辑
U->>FE : 点击圆形图标按钮
FE->>API : 调用列表/创建/更新/删除/上传
API->>AX : 发起HTTP请求
AX->>RT : 路由处理鉴权/参数校验
@@ -127,7 +132,7 @@ API-->>FE : 渲染结果
```
**图表来源**
- [index.vue:420-831](file://frontend/src/views/ota/index.vue#L420-L831)
- [index.vue:56-66](file://frontend/src/views/ota/index.vue#L56-L66)
- [ota.js:13-67](file://frontend/src/api/ota.js#L13-L67)
- [blacklist.js:12-56](file://frontend/src/api/blacklist.js#L12-L56)
- [otaTargetDevice.js:12-55](file://frontend/src/api/otaTargetDevice.js#L12-L55)
@@ -142,6 +147,7 @@ API-->>FE : 渲染结果
- CRUD操作:支持新增、编辑、复制(基于现有行)、删除,均通过API封装调用后端接口。
- 分页与加载:支持每页数量切换与页码切换,加载状态通过Element Plus的loading指示。
- **新增功能**:在更多操作菜单中集成了黑名单管理和定向升级功能,支持对单个OTA版本进行设备级别的管控。
- **统一按钮样式**:**所有操作按钮已标准化为圆形图标格式,包括搜索、重置、新增等操作,每个按钮都添加了适当的title属性以提升可访问性**。
```mermaid
flowchart TD
@@ -171,11 +177,11 @@ Reload --> Render
```
**图表来源**
- [index.vue:420-831](file://frontend/src/views/ota/index.vue#L420-L831)
- [index.vue:56-66](file://frontend/src/views/ota/index.vue#L56-L66)
- [ota.js:13-49](file://frontend/src/api/ota.js#L13-L49)
**章节来源**
- [index.vue:1-1003](file://frontend/src/views/ota/index.vue#L1-L1003)
- [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)
### 后端路由与控制器
@@ -358,15 +364,30 @@ BuildX9 --> Return
- 分页与重置:支持页码与每页数量调整,重置搜索条件。
- **新增弹窗管理**:黑名单和定向升级分别通过独立弹窗进行管理,支持MAC地址的批量添加和删除。
- **MAC地址格式校验**:支持AA:BB:CC:DD:EE:FF格式的MAC地址输入和验证。
- **统一按钮样式**:**所有操作按钮已标准化为圆形图标格式,提供更好的可访问性和一致的视觉体验**。
- 后端:
- 统一响应格式:code=1成功、code=0错误、code=2无数据。
- 错误分类:参数错误、业务冲突(版本已存在)、存储异常(S3上传失败)、权限错误等。
- 日志记录:关键操作与异常均有日志输出,便于排查。
**章节来源**
- [index.vue:305-338](file://frontend/src/views/ota/index.vue#L305-L338)
- [index.vue:56-66](file://frontend/src/views/ota/index.vue#L56-L66)
- [response.js:1-25](file://backend/src/utils/response.js#L1-L25)
- [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(新增)等,确保图标含义清晰。
- **交互反馈**:圆形按钮保持了良好的hover和active状态反馈,提供清晰的视觉交互提示。
- **响应式设计**:圆形按钮在不同屏幕尺寸下都能保持良好的显示效果和可用性。
**章节来源**
- [index.vue:56-66](file://frontend/src/views/ota/index.vue#L56-L66)
- [blacklist.js:40-50](file://frontend/src/views/blacklist/index.vue#L40-L50)
- [otaTargetDevice.js:40-50](file://frontend/src/views/ota-target-device/index.vue#L40-L50)
- [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)
### 黑名单管理功能
- 功能概述:支持将特定设备的MAC地址加入黑名单,阻止这些设备接收OTA更新。
@@ -379,7 +400,7 @@ BuildX9 --> Return
- 数据验证:MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式,且每个MAC地址都必须唯一。
**章节来源**
- [index.vue:645-734](file://frontend/src/views/ota/index.vue#L645-L734)
- [index.vue:683-772](file://frontend/src/views/ota/index.vue#L683-L772)
- [blacklist.js:12-56](file://frontend/src/api/blacklist.js#L12-L56)
- [blacklist.js:96-204](file://backend/src/routes/blacklist.js#L96-L204)
@@ -394,7 +415,7 @@ BuildX9 --> Return
- 数据验证:MAC地址格式必须符合AA:BB:CC:DD:EE:FF格式,且每个MAC地址在同一个OTA版本内必须唯一。
**章节来源**
- [index.vue:736-817](file://frontend/src/views/ota/index.vue#L736-L817)
- [index.vue:774-855](file://frontend/src/views/ota/index.vue#L774-L855)
- [otaTargetDevice.js:12-55](file://frontend/src/api/otaTargetDevice.js#L12-L55)
- [otaTargetDevice.js:96-208](file://backend/src/routes/otaTargetDevice.js#L96-L208)
@@ -455,6 +476,9 @@ BE --> AW["AWS SDK"]
- **黑名单和定向升级查询优化**
- 黑名单和定向升级列表查询支持按OTA版本过滤,减少不必要的数据传输。
- 支持MAC地址模糊查询,提升用户体验。
- **按钮样式性能**
- 圆形图标按钮减少了DOM节点复杂度,提升了渲染性能。
- CSS样式采用高效的类选择器,避免了复杂的嵌套样式计算。
## 故障排除指南
- 上传失败:
@@ -473,6 +497,10 @@ BE --> AW["AWS SDK"]
- MAC地址格式错误:确保输入AA:BB:CC:DD:EE:FF格式。
- OTA版本不存在:确认选择的OTA版本ID有效。
- 重复的MAC地址:黑名单和定向升级中的MAC地址在同一OTA版本内必须唯一。
- **按钮样式问题**
- 如果圆形按钮显示异常,检查Element Plus图标库是否正确引入。
- 确认CSS主题样式文件已正确加载,特别是lux-theme.css文件。
- 检查浏览器控制台是否有CSS相关的错误信息。
**章节来源**
- [ota.js:25-66](file://backend/src/routes/ota.js#L25-L66)
@@ -480,6 +508,7 @@ BE --> AW["AWS SDK"]
- [blacklist.js:159-183](file://backend/src/routes/blacklist.js#L159-L183)
- [otaTargetDevice.js:142-208](file://backend/src/routes/otaTargetDevice.js#L142-L208)
- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
- [lux-theme.css:479-521](file://frontend/src/styles/lux-theme.css#L479-L521)
## 结论
OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式,实现了从版本上传、存储、查询到发布的完整闭环。**本次更新集成了黑名单管理和定向升级功能,显著提升了OTA管理的精细化程度和安全性**。X8/X9差异化存储策略兼顾了可扩展性与易用性,配合严格的参数校验与完善的错误处理,为设备端的兼容性检查与更新策略提供了可靠支撑。**新增的黑名单和定向升级功能使得OTA管理更加灵活,能够满足不同场景下的设备管控需求**。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能,并持续优化上传体验与性能表现。
OTA固件管理页面通过清晰的前后端职责划分与统一的响应格式,实现了从版本上传、存储、查询到发布的完整闭环。**本次更新统一了操作按钮的视觉风格,采用圆形图标设计显著提升了界面的可访问性和用户体验**。X8/X9差异化存储策略兼顾了可扩展性与易用性,配合严格的参数校验与完善的错误处理,为设备端的兼容性检查与更新策略提供了可靠支撑。**新增的黑名单和定向升级功能使得OTA管理更加灵活,能够满足不同场景下的设备管控需求**。统一的圆形按钮设计不仅提升了界面的现代化程度,还增强了屏幕阅读器的支持,使整个系统更加符合无障碍访问标准。建议在后续迭代中进一步完善下载统计、版本历史与回滚功能,并持续优化上传体验与性能表现。