新增 luxsin-controller，更新 wiki

2026-07-10 16:51:05 +08:00
parent b9ba1d5ed4
commit fc88d42be9
28 changed files with 1009 additions and 270 deletions
@@ -2,6 +2,11 @@

 <cite>
 **本文引用的文件**   
+- [frontend/src/styles/lux-theme.css](file://frontend/src/styles/lux-theme.css)
+- [frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
+- [frontend/src/components/SidebarLogo.vue](file://frontend/src/components/SidebarLogo.vue)
+- [frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
+- [DESIGN.md](file://DESIGN.md)
 - [backend/src/app.js](file://backend/src/app.js)
 - [backend/src/routes/index.js](file://backend/src/routes/index.js)
 - [backend/src/routes/auth.js](file://backend/src/routes/auth.js)
@@ -13,28 +18,269 @@
 - [frontend/src/main.js](file://frontend/src/main.js)
 - [frontend/src/App.vue](file://frontend/src/App.vue)
 - [frontend/src/router/index.js](file://frontend/src/router/index.js)
- [frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
- [frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
 - [frontend/package.json](file://frontend/package.json)
 - [docker-compose.yml](file://docker-compose.yml)
 - [DEPLOY.md](file://DEPLOY.md)
 </cite>

+## 更新摘要
+**变更内容**   
+- 完全重构前端视觉设计系统，采用全新的玻璃拟态美学风格
+- 实现797+行自定义CSS属性，构建完整的空间主题色彩系统
+- 引入现代视觉语言，替代之前的Anthropic风格暖奶油设计
+- 新增多层级玻璃表面、模糊效果、光晕系统和深度层级管理
+
 ## 目录
 1. [简介](#简介)
-2. [项目结构](#项目结构)
-3. [核心组件](#核心组件)
-4. [架构总览](#架构总览)
-5. [详细组件分析](#详细组件分析)
-6. [依赖关系分析](#依赖关系分析)
-7. [性能与可扩展性](#性能与可扩展性)
-8. [故障排查指南](#故障排查指南)
-9. [结论](#结论)
-10. [附录](#附录)
+2. [设计哲学与核心理念](#设计哲学与核心理念)
+3. [空间主题色彩系统](#空间主题色彩系统)
+4. [玻璃拟态设计语言](#玻璃拟态设计语言)
+5. [组件设计规范](#组件设计规范)
+6. [项目结构](#项目结构)
+7. [核心组件](#核心组件)
+8. [架构总览](#架构总览)
+9. [详细组件分析](#详细组件分析)
+10. [依赖关系分析](#依赖关系分析)
+11. [性能与可扩展性](#性能与可扩展性)
+12. [故障排查指南](#故障排查指南)
+13. [结论](#结论)
+14. [附录](#附录)

 ## 简介
 本项目是一个面向耳机品牌与型号管理的后台管理系统，包含前后端分离的完整实现：前端基于 Vue 3 + Element Plus，后端基于 Express + Sequelize（MySQL），通过 Docker Compose 进行容器化部署。系统提供品牌管理、型号管理、OTA 升级包管理、黑名单管理、定向升级、分享码日志以及用户认证等能力。

+**最新更新**：系统已完成全面的设计系统重构，采用全新的玻璃拟态美学风格，结合空间主题色彩系统和现代视觉语言，为用户提供沉浸式的深色界面体验。
+
+## 设计哲学与核心理念
+
+### 三层融合设计语言
+Luxsin CMS Dashboard 采用三层融合设计语言，将登录页的精致玻璃美学统一到全站：
+
+| 层级 | 风格 | 占比 | 职责 |
+|---|---|---|---|
+| **主风格** | Glassmorphism | 60% | 半透明毛玻璃表面、`backdrop-filter` 模糊、微弱边框光晕 |
+| **辅助风格** | Dimensional Layering | 25% | 4 级 elevation 空间层级，通过阴影和浮起建立信息层次 |
+| **辅助风格** | Dark Mode OLED | 15% | 深空黑底色保障对比度，焦点 ring 反馈，minimal glow |
+
+### 设计原则
+1. **Glass everywhere** — 侧栏、顶栏、卡片、表格、对话框、输入框全部使用半透明玻璃
+2. **Depth through layers** — 4 级 elevation (bg → content → floating → overlay) 建立空间秩序
+3. **Contrast first** — 所有文本确保 WCAG AA (4.5:1)，关键文本 AAA (7:1)
+4. **Consistency over creativity** — 统一 Token 驱动，不做页面级定制
+
+**章节来源**
+- [DESIGN.md:9-24](file://DESIGN.md#L9-L24)
+
+## 空间主题色彩系统
+
+### 基础色板（Primitives）
+系统采用深空主题色彩体系，提供完整的颜色语义化变量：
+
+```css
+/* 基础色板 */
+--lux-space-900:  #020617;
+--lux-space-800:  #0a0e14;    /* 页面底色 */
+--lux-space-700:  #0f172a;    /* 输入框底色 */
+--lux-space-600:  #1e293b;    /* 卡片底色 */
+--lux-space-500:  #334155;
+--lux-space-400:  #475569;
+--lux-space-300:  #94a3b8;    /* muted text */
+--lux-space-200:  #cbd5e1;
+--lux-space-100:  #e2e8f0;    /* strong text */
+
+/* 品牌色 */
+--lux-cyan:       #38bdf8;    /* 主品牌 */
+--lux-cyan-light: #7dd3fc;
+--lux-cyan-glow:  rgba(56, 189, 248, 0.25);
+--lux-indigo:     #6366f1;
+--lux-violet:     #7c3aed;
+```
+
+### 语义化Token定义
+系统定义了丰富的语义化变量，涵盖页面、文本、玻璃表面、边框、模糊强度等多个维度：
+
+```css
+/* 页面 */
+--lux-page-bg:            #0a0e14;
+--lux-page-gradient:      radial-gradient(ellipse 120% 90% at 50% -15%, #1a2840 0%, #0d1117 48%, #0a0e14 100%);
+
+/* 文本 */
+--lux-text-strong:        #e2e8f0;    /* 标题、重要文本 — 对比度 13.5:1 */
+--lux-text-body:          #cbd5e1;    /* 正文 — 对比度 10.2:1 */
+--lux-text-muted:         #94a3b8;    /* 辅助文本 — 对比度 5.8:1 */
+--lux-text-dim:           #64748b;    /* 最弱文本 — 对比度 3.5:1 (仅装饰性) */
+
+/* 玻璃表面 */
+--lux-glass-bg-card:      rgba(30, 41, 59, 0.55);    /* 卡片 */
+--lux-glass-bg-table:     rgba(30, 41, 59, 0.45);    /* 表格 */
+--lux-glass-bg-input:     rgba(15, 23, 42, 0.45);    /* 输入框 */
+--lux-glass-bg-dialog:    rgba(30, 41, 59, 0.72);    /* 对话框 */
+--lux-glass-bg-sidebar:   rgba(15, 23, 42, 0.60);    /* 侧栏 */
+--lux-glass-bg-header:    rgba(30, 41, 59, 0.75);    /* 顶栏 */
+--lux-glass-bg-tab:       rgba(30, 41, 59, 0.35);    /* 标签页 */
+
+/* 玻璃边框 */
+--lux-glass-border:       rgba(255, 255, 255, 0.08);
+--lux-glass-border-hover: rgba(255, 255, 255, 0.14);
+--lux-glass-border-focus: rgba(56, 189, 248, 0.45);
+
+/* 模糊强度 */
+--lux-blur-sm:   blur(8px);
+--lux-blur-md:   blur(14px);
+--lux-blur-lg:   blur(20px);
+--lux-blur-xl:   blur(24px);
+```
+
+### 深度层级系统（Elevation）
+系统采用4级深度层级，通过阴影和透明度建立清晰的空间层次：
+
+```css
+/* 4级 Elevation */
+--lux-shadow-1:  0 2px 8px rgba(0, 0, 0, 0.18);                    /* 卡片 resting */
+--lux-shadow-2:  0 4px 16px rgba(0, 0, 0, 0.25);                   /* 卡片 hover / 浮起 */
+--lux-shadow-3:  0 8px 32px rgba(0, 0, 0, 0.35);                   /* 弹出层 */
+--lux-shadow-4:  0 25px 50px rgba(0, 0, 0, 0.50);                  /* 对话框 overlay */
+
+/* 品牌 glow (焦点态) */
+--lux-glow-cyan: 0 0 0 3px rgba(56, 189, 248, 0.15), 0 0 0 1px rgba(56, 189, 248, 0.45) inset;
+```
+
+**章节来源**
+- [DESIGN.md:28-97](file://DESIGN.md#L28-L97)
+- [frontend/src/styles/lux-theme.css:11-78](file://frontend/src/styles/lux-theme.css#L11-L78)
+
+## 玻璃拟态设计语言
+
+### 核心视觉特征
+新设计系统以玻璃拟态为核心，具有以下特征：
+
+1. **半透明表面**：所有主要UI元素都采用半透明背景，透出底层内容
+2. **背景模糊**：使用 `backdrop-filter: blur()` 创建毛玻璃效果
+3. **微妙边框**：极细的白色边框（rgba(255,255,255,0.08)）勾勒轮廓
+4. **光晕效果**：焦点状态下的青色光晕反馈
+5. **深度阴影**：多层阴影营造悬浮感和层次感
+
+### 动态背景系统
+系统实现了动态宇宙背景，包含三个渐变光球：
+
+```mermaid
+graph TB
+subgraph "动态背景层"
+BG["深空背景 #0a0e14"]
+ORB1["青色光球 #22d3ee<br/>位置：左上角"]
+ORB2["紫色光球 #a78bfa<br/>位置：右侧中部"]
+ORB3["珊瑚色光球 #fb7185<br/>位置：底部中央"]
+end
+subgraph "内容层"
+UI["UI组件层<br/>z-index: 1+"]
+end
+BG --> ORB1
+BG --> ORB2
+BG --> ORB3
+ORB1 --> UI
+ORB2 --> UI
+ORB3 --> UI
+```
+
+**图表来源** 
+- [frontend/src/styles/lux-theme.css:98-129](file://frontend/src/styles/lux-theme.css#L98-L129)
+- [frontend/src/layout/index.vue:3-7](file://frontend/src/layout/index.vue#L3-L7)
+
+### 字体系统与排版
+系统采用现代化的字体栈和排版规范：
+
+```css
+--lux-font: 'Inter', 'Segoe UI', system-ui, -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif;
+--lux-font-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', ui-monospace, monospace;
+```
+
+**字号层级**：
+- Hero: 24px / 700weight - 首页欢迎标题
+- H1: 18px / 700weight - 页面标题、卡片标题  
+- H2: 16px / 600weight - 子标题、对话框标题
+- Body: 14px / 400weight - 正文、表格单元格
+- Small: 13px / 400weight - 辅助文本、分页
+- XSmall: 12px / 500weight - 标签、徽章、脚注
+
+**章节来源**
+- [DESIGN.md:101-126](file://DESIGN.md#L101-L126)
+- [frontend/src/styles/lux-theme.css:13-23](file://frontend/src/styles/lux-theme.css#L13-L23)
+
+## 组件设计规范
+
+### 卡片组件（el-card）
+```
+背景:        var(--lux-glass-bg-card)
+模糊:        var(--lux-blur-lg)  [20px]
+边框:        1px solid var(--lux-glass-border)
+圆角:        var(--lux-radius-lg)  [14px]
+阴影:        var(--lux-shadow-1)
+hover 阴影:  var(--lux-shadow-2)
+padding:     20px (body), 16px 20px (header)
+```
+
+### 表格组件（el-table）
+```
+表头背景:    rgba(15, 23, 42, 0.65) + blur(14px)
+行背景:      transparent (卡片底色透出)
+hover 行:    rgba(56, 189, 248, 0.06)
+边框色:      rgba(255, 255, 255, 0.06)
+文字:        var(--lux-text-body)
+表头文字:    var(--lux-text-muted)
+圆角:        12px (overflow hidden)
+```
+
+### 对话框组件（el-dialog, Teleport）
+```
+背景:        var(--lux-glass-bg-dialog) + blur(24px)
+边框:        1px solid var(--lux-glass-border)
+圆角:        var(--lux-radius-xl)  [18px]
+阴影:        var(--lux-shadow-4) + inset glow
+header:      1px solid rgba(255, 255, 255, 0.08) 底分割
+```
+
+### 输入框组件（el-input, el-select）
+```
+背景:        var(--lux-glass-bg-input)
+圆角:        var(--lux-radius-md)  [10px]
+边框:        1px solid var(--lux-glass-border)
+focus:       1px solid var(--lux-glass-border-focus) + var(--lux-glow-cyan)
+placeholder: var(--lux-text-dim)
+```
+
+### 按钮组件 - Primary
+```
+背景:        linear-gradient(135deg, #38bdf8, #22d3ee)
+文字:        #fff
+圆角:        var(--lux-radius-md)  [10px]
+阴影:        0 4px 12px rgba(56, 189, 248, 0.25)
+hover 阴影:  0 6px 16px rgba(56, 189, 248, 0.35)
+```
+
+### 侧边栏组件
+```
+背景:        var(--lux-glass-bg-sidebar)
+模糊:        var(--lux-blur-lg)  [18px]
+宽度:        64px (collapsed) / 220px (expanded)
+边框右:      1px solid rgba(255, 255, 255, 0.08)
+z-index:     100 (L2)
+active item: gradient bg rgba(56,189,248,0.22) → rgba(99,102,241,0.14)
+             + 1px inset border rgba(56,189,248,0.25)
+```
+
+### 顶部导航栏
+```
+背景:        var(--lux-glass-bg-header)
+模糊:        var(--lux-blur-md)  [14px]
+高度:        44px
+圆角:        10px
+边框:        1px solid var(--lux-glass-border)
+阴影:        var(--lux-shadow-1)
+```
+
+**章节来源**
+- [DESIGN.md:169-279](file://DESIGN.md#L169-L279)
+
 ## 项目结构
 仓库采用前后端分层组织方式：
 - backend：Express 应用入口、路由、模型、配置、中间件、服务与工具模块
@@ -50,6 +296,8 @@ FE_app["frontend/src/App.vue"]
 FE_router["frontend/src/router/index.js"]
 FE_layout["frontend/src/layout/index.vue"]
 FE_home["frontend/src/views/home/index.vue"]
+FE_theme["frontend/src/styles/lux-theme.css"]
+FE_logo["frontend/src/components/SidebarLogo.vue"]
 end
 subgraph "后端"
 BE_app["backend/src/app.js"]
@@ -64,6 +312,8 @@ FE_main --> FE_app
 FE_app --> FE_router
 FE_router --> FE_layout
 FE_layout --> FE_home
+FE_layout --> FE_theme
+FE_layout --> FE_logo
 FE_main --> |"HTTP 请求 /api/*"| BE_app
 BE_app --> BE_routes
 BE_routes --> BE_auth
@@ -77,8 +327,10 @@ BE_app --> BE_db
 - [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
 - [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
 - [frontend/src/router/index.js:1-103](file://frontend/src/router/index.js#L1-L103)
- [frontend/src/layout/index.vue:1-348](file://frontend/src/layout/index.vue#L1-L348)
- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
+- [frontend/src/layout/index.vue:1-351](file://frontend/src/layout/index.vue#L1-L351)
+- [frontend/src/views/home/index.vue:1-334](file://frontend/src/views/home/index.vue#L1-L334)
+- [frontend/src/styles/lux-theme.css:1-1259](file://frontend/src/styles/lux-theme.css#L1-L1259)
+- [frontend/src/components/SidebarLogo.vue:1-135](file://frontend/src/components/SidebarLogo.vue#L1-L135)
 - [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
 - [backend/src/routes/index.js:1-15](file://backend/src/routes/index.js#L1-L15)
 - [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
@@ -104,6 +356,8 @@ BE_app --> BE_db
  - 使用 Sequelize 定义实体（如 Brand、Model），集中导出供路由与服务使用
 - 配置与基础设施
  - 数据库连接、环境变量加载、日志、Redis 等（部分在配置目录中）
+- **新增**：设计系统核心
+  - 全局CSS主题变量、玻璃拟态样式、响应式组件规范

 **章节来源**
 - [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
@@ -112,6 +366,7 @@ BE_app --> BE_db
 - [frontend/src/router/index.js:1-103](file://frontend/src/router/index.js#L1-L103)
 - [backend/src/models/index.js:1-10](file://backend/src/models/index.js#L1-L10)
 - [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
+- [frontend/src/styles/lux-theme.css:1-1259](file://frontend/src/styles/lux-theme.css#L1-L1259)

 ## 架构总览
 系统采用经典的前后端分离架构，前端静态资源由 Nginx 托管并通过反向代理将 /api 转发到后端；后端以 Express 提供服务，使用 Sequelize 访问 MySQL。
@@ -123,8 +378,10 @@ Nginx["Nginx(前端容器)"]
 API["Express(后端容器)"]
 DB["MySQL"]
 Redis["Redis(可选)"]
+Theme["Lux Theme System<br/>Glassmorphism + Space Colors"]
 Client --> Nginx
 Nginx --> |"/api/*" 代理| API
+Nginx --> Theme
 API --> DB
 API --> Redis
 ```
@@ -132,6 +389,7 @@ API --> Redis
 **图表来源** 
 - [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
 - [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
+- [frontend/src/styles/lux-theme.css:1-1259](file://frontend/src/styles/lux-theme.css#L1-L1259)

 ## 详细组件分析

@@ -175,7 +433,7 @@ API-->>U : 返回令牌与用户信息
 - [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
 - [backend/src/routes/auth.js:66-77](file://backend/src/routes/auth.js#L66-L77)

-### 首页“今日新增”数据流
+### 首页"今日新增"数据流
 首页展示当日新增的型号与 OTA 记录，调用仪表盘统计接口获取数据。

 ```mermaid
@@ -227,7 +485,7 @@ BRAND ||--o{ MODEL : "brand_name 关联"

 **章节来源**
 - [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-53)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)

 ### 布局与导航
 侧边栏支持折叠/展开、面包屑与用户菜单，结合路由元信息进行权限控制与高亮。
@@ -251,6 +509,23 @@ OpenDialog --> End
 **章节来源**
 - [frontend/src/layout/index.vue:174-231](file://frontend/src/layout/index.vue#L174-L231)

+### 品牌标识组件
+新的品牌标识组件采用SVG图形和渐变效果，支持折叠状态下的自适应显示。
+
+```mermaid
+flowchart LR
+Logo["SidebarLogo 组件"] --> Mark["SVG标志<br/>渐变填充 + 阴影滤镜"]
+Logo --> Wordmark["品牌文字<br/>渐变色 + 间距调整"]
+Mark --> Collapsed["折叠状态<br/>仅显示图标"]
+Wordmark --> Expanded["展开状态<br/>显示完整品牌名"]
+```
+
+**图表来源** 
+- [frontend/src/components/SidebarLogo.vue:1-135](file://frontend/src/components/SidebarLogo.vue#L1-L135)
+
+**章节来源**
+- [frontend/src/components/SidebarLogo.vue:1-135](file://frontend/src/components/SidebarLogo.vue#L1-L135)
+
 ## 依赖关系分析
 - 后端依赖
  - Express、Sequelize、MySQL、JSON Web Token、Multer、Axios、Zod、Winston、ioredis、AWS SDK（S3）等
@@ -289,6 +564,10 @@ Compose --> |"Node 8083 -> 8000"| BE_api["后端 API"]
  - 建议在网关层增加速率限制与请求体大小限制（后端已有 bodyLimit 中间件）
 - 扩展点
  - 可按功能域继续拆分路由与服务，引入缓存层（Redis）与消息队列以提升吞吐
+- **新增**：设计系统性能优化
+  - CSS变量预编译减少运行时开销
+  - backdrop-filter性能考虑（移动端降级方案）
+  - 动画过渡优化（GPU加速）

 [本节为通用指导，不直接分析具体文件]

@@ -301,12 +580,18 @@ Compose --> |"Node 8083 -> 8000"| BE_api["后端 API"]
  - 确认镜像基础版本与 pnpm 版本一致，确保上传了 package.json 与锁文件
 - 环境变量未生效
  - 重新创建容器使 .env 生效
+- **新增**：设计系统相关问题
+  - 样式未生效：检查 lux-theme.css 是否正确引入
+  - 玻璃效果异常：确认浏览器支持 backdrop-filter
+  - 颜色显示异常：检查CSS变量定义顺序

 **章节来源**
 - [DEPLOY.md:226-269](file://DEPLOY.md#L226-L269)

 ## 结论
-本设计系统以清晰的模块化与容器化部署为基础，提供了完整的品牌与型号管理能力，并在认证、路由、模型与部署方面形成了稳定的工程实践。后续可在缓存、监控与可观测性方面进一步增强，以满足更大规模的生产需求。
+本设计系统以清晰的模块化与容器化部署为基础，提供了完整的品牌与型号管理能力，并在认证、路由、模型与部署方面形成了稳定的工程实践。**最新的设计系统重构引入了革命性的玻璃拟态美学，通过797+行精心设计的CSS变量和组件规范，为用户创造了沉浸式的深色界面体验。**
+
+后续可在缓存、监控与可观测性方面进一步增强，以满足更大规模的生产需求。同时，设计系统的持续演进将为产品带来更一致的视觉语言和更好的用户体验。

 [本节为总结性内容，不直接分析具体文件]

@@ -321,5 +606,8 @@ Compose --> |"Node 8083 -> 8000"| BE_api["后端 API"]
  - 前端路由：[frontend/src/router/index.js](file://frontend/src/router/index.js)
  - 布局组件：[frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
  - 首页视图：[frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
+  - 品牌标识：[frontend/src/components/SidebarLogo.vue](file://frontend/src/components/SidebarLogo.vue)
+  - 设计系统规范：[DESIGN.md](file://DESIGN.md)
+  - 主题样式：[frontend/src/styles/lux-theme.css](file://frontend/src/styles/lux-theme.css)
  - 部署文档：[DEPLOY.md](file://DEPLOY.md)
  - 编排文件：[docker-compose.yml](file://docker-compose.yml)