Files

T

eafonyang fc88d42be9 新增 luxsin-controller，更新 wiki

2026-07-10 16:51:05 +08:00

24 KiB

Raw Blame History

设计系统

**本文引用的文件** - [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) - [backend/src/models/index.js](file://backend/src/models/index.js) - [backend/src/models/Brand.js](file://backend/src/models/Brand.js) - [backend/src/models/Model.js](file://backend/src/models/Model.js) - [backend/src/config/database.js](file://backend/src/config/database.js) - [backend/package.json](file://backend/package.json) - [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/package.json](file://frontend/package.json) - [docker-compose.yml](file://docker-compose.yml) - [DEPLOY.md](file://DEPLOY.md)

更新摘要

变更内容

完全重构前端视觉设计系统，采用全新的玻璃拟态美学风格
实现797+行自定义CSS属性，构建完整的空间主题色彩系统
引入现代视觉语言，替代之前的Anthropic风格暖奶油设计
新增多层级玻璃表面、模糊效果、光晕系统和深度层级管理

简介

本项目是一个面向耳机品牌与型号管理的后台管理系统，包含前后端分离的完整实现：前端基于 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

设计原则

Glass everywhere — 侧栏、顶栏、卡片、表格、对话框、输入框全部使用半透明玻璃
Depth through layers — 4 级 elevation (bg → content → floating → overlay) 建立空间秩序
Contrast first — 所有文本确保 WCAG AA (4.5:1)，关键文本 AAA (7:1)
Consistency over creativity — 统一 Token 驱动，不做页面级定制

章节来源

DESIGN.md:9-24

空间主题色彩系统

基础色板（Primitives）

系统采用深空主题色彩体系，提供完整的颜色语义化变量：

/* 基础色板 */
--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定义

系统定义了丰富的语义化变量，涵盖页面、文本、玻璃表面、边框、模糊强度等多个维度：

/* 页面 */
--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级深度层级，通过阴影和透明度建立清晰的空间层次：

/* 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;

章节来源

玻璃拟态设计语言

核心视觉特征

新设计系统以玻璃拟态为核心，具有以下特征：

半透明表面：所有主要UI元素都采用半透明背景，透出底层内容
背景模糊：使用 backdrop-filter: blur() 创建毛玻璃效果
微妙边框：极细的白色边框（rgba(255,255,255,0.08)）勾勒轮廓
光晕效果：焦点状态下的青色光晕反馈
深度阴影：多层阴影营造悬浮感和层次感

动态背景系统

系统实现了动态宇宙背景，包含三个渐变光球：

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

图表来源

字体系统与排版

系统采用现代化的字体栈和排版规范：

--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 - 标签、徽章、脚注

章节来源

组件设计规范

卡片组件（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

项目结构

仓库采用前后端分层组织方式：

backend：Express 应用入口、路由、模型、配置、中间件、服务与工具模块
frontend：Vue 3 应用入口、路由、布局、视图、API 封装、样式与工具
docker-compose.yml：编排前端 Nginx 与后端 Node 服务
DEPLOY.md：部署与环境说明

graph TB
subgraph "前端"
FE_main["frontend/src/main.js"]
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"]
BE_routes["backend/src/routes/index.js"]
BE_auth["backend/src/routes/auth.js"]
BE_models["backend/src/models/index.js"]
BE_brand["backend/src/models/Brand.js"]
BE_model["backend/src/models/Model.js"]
BE_db["backend/src/config/database.js"]
end
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
BE_auth --> BE_models
BE_models --> BE_brand
BE_models --> BE_model
BE_app --> BE_db

图表来源

章节来源

核心组件

应用入口
- 后端：Express 应用初始化、全局中间件、健康检查、路由挂载、数据库同步与启动监听
- 前端：Vue 应用创建、Element Plus 注册、路由挂载、加载遮罩处理
路由层
- 后端：按功能域拆分路由并统一汇总挂载
- 前端：基于 vue-router 的页面路由与导航守卫（鉴权、超级管理员控制）
数据模型
- 使用 Sequelize 定义实体（如 Brand、Model），集中导出供路由与服务使用
配置与基础设施
- 数据库连接、环境变量加载、日志、Redis 等（部分在配置目录中）
新增：设计系统核心
- 全局CSS主题变量、玻璃拟态样式、响应式组件规范

章节来源

架构总览

系统采用经典的前后端分离架构，前端静态资源由 Nginx 托管并通过反向代理将 /api 转发到后端；后端以 Express 提供服务，使用 Sequelize 访问 MySQL。

graph TB
Client["浏览器客户端"]
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

图表来源

详细组件分析

认证流程（登录与鉴权）

该流程涵盖前端导航守卫、后端登录接口、JWT 签发与受保护接口的鉴权中间件。

sequenceDiagram
participant U as "用户"
participant FE as "前端路由守卫"
participant API as "后端认证路由"
participant DB as "数据库"
participant JWT as "JWT工具"
U->>FE : 访问受保护页面
FE->>FE : 检查本地令牌是否过期
alt 无令牌或已过期
FE-->>U : 重定向至登录页
else 有有效令牌
FE->>API : GET /api/auth/me
API->>DB : 查询当前用户
DB-->>API : 返回用户信息
API-->>FE : 返回用户信息
FE-->>U : 放行并渲染页面
end
U->>API : POST /api/auth/login
API->>DB : 校验用户名/状态
DB-->>API : 返回用户记录
API->>API : 校验密码哈希
API->>JWT : 生成访问令牌
JWT-->>API : 返回令牌
API-->>U : 返回令牌与用户信息

图表来源

章节来源

首页"今日新增"数据流

首页展示当日新增的型号与 OTA 记录，调用仪表盘统计接口获取数据。

sequenceDiagram
participant V as "Home 视图"
participant API as "Dashboard API"
participant S as "后端路由/服务"
participant DB as "数据库"
V->>API : 请求今日统计数据
API->>S : 进入业务逻辑
S->>DB : 聚合当日新增型号/OTA
DB-->>S : 返回统计结果
S-->>API : 组装响应
API-->>V : 返回 models/otas 列表
V->>V : 渲染卡片与列表

图表来源

frontend/src/views/home/index.vue:127-148

章节来源

frontend/src/views/home/index.vue:127-148

数据模型与关系（简化）

以下模型用于品牌与型号管理，字段注释清晰，便于理解数据结构。

erDiagram
BRAND {
int id PK
string name UK
}
MODEL {
int id PK
string brand_name
string name
string form
string rig
string source
string eq_key
datetime create_at
}
BRAND ||--o{ MODEL : "brand_name 关联"

图表来源

章节来源

布局与导航

侧边栏支持折叠/展开、面包屑与用户菜单，结合路由元信息进行权限控制与高亮。

flowchart TD
Start(["进入 Layout"]) --> ResolveMenu["根据当前路径计算展开菜单"]
ResolveMenu --> Breadcrumb["解析面包屑标题与分组"]
Breadcrumb --> UserMenu{"用户菜单操作"}
UserMenu --> |退出| Logout["清除本地认证并重定向登录"]
UserMenu --> |账号管理| ToUsers["跳转系统用户管理"]
UserMenu --> |修改密码| OpenDialog["打开修改密码弹窗"]
Logout --> End(["结束"])
ToUsers --> End
OpenDialog --> End

图表来源

frontend/src/layout/index.vue:174-231

章节来源

frontend/src/layout/index.vue:174-231

品牌标识组件

新的品牌标识组件采用SVG图形和渐变效果，支持折叠状态下的自适应显示。

flowchart LR
Logo["SidebarLogo 组件"] --> Mark["SVG标志<br/>渐变填充 + 阴影滤镜"]
Logo --> Wordmark["品牌文字<br/>渐变色 + 间距调整"]
Mark --> Collapsed["折叠状态<br/>仅显示图标"]
Wordmark --> Expanded["展开状态<br/>显示完整品牌名"]

图表来源

frontend/src/components/SidebarLogo.vue:1-135

章节来源

frontend/src/components/SidebarLogo.vue:1-135

依赖关系分析

后端依赖
- Express、Sequelize、MySQL、JSON Web Token、Multer、Axios、Zod、Winston、ioredis、AWS SDK（S3）等
前端依赖
- Vue 3、Element Plus、Vue Router、Axios、JSON Pretty 等
运行时编排
- Docker Compose 编排前端 Nginx 与后端 Node 服务，端口映射与网络互通

graph LR
FE_pkg["frontend/package.json"]
BE_pkg["backend/package.json"]
Compose["docker-compose.yml"]
FE_pkg --> |"构建产物 dist"| Compose
BE_pkg --> |"镜像构建/运行"| Compose
Compose --> |"Nginx 8082 -> 80"| FE_static["前端静态资源"]
Compose --> |"Node 8083 -> 8000"| BE_api["后端 API"]

图表来源

章节来源

性能与可扩展性

数据库连接
- 使用 Sequelize 连接 MySQL，建议在生产环境启用连接池与慢查询日志，合理设置超时与重试策略
静态资源
- 前端通过 Nginx 缓存静态资源，开启 Gzip/Brotli 压缩可提升首屏加载速度
鉴权与限流
- 建议在网关层增加速率限制与请求体大小限制（后端已有 bodyLimit 中间件）
扩展点
- 可按功能域继续拆分路由与服务，引入缓存层（Redis）与消息队列以提升吞吐
新增：设计系统性能优化
- CSS变量预编译减少运行时开销
- backdrop-filter性能考虑（移动端降级方案）
- 动画过渡优化（GPU加速）

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

故障排查指南

前端空白
- 确认 dist 已上传且 Nginx 配置正确，查看浏览器控制台是否有 404 或跨域错误
API 请求失败
- 检查后端容器状态与健康检查接口，查看后端日志定位数据库/Redis 连接问题
后端构建失败
- 确认镜像基础版本与 pnpm 版本一致，确保上传了 package.json 与锁文件
环境变量未生效
- 重新创建容器使 .env 生效
新增：设计系统相关问题
- 样式未生效：检查 lux-theme.css 是否正确引入
- 玻璃效果异常：确认浏览器支持 backdrop-filter
- 颜色显示异常：检查CSS变量定义顺序

章节来源

DEPLOY.md:226-269

结论

本设计系统以清晰的模块化与容器化部署为基础，提供了完整的品牌与型号管理能力，并在认证、路由、模型与部署方面形成了稳定的工程实践。最新的设计系统重构引入了革命性的玻璃拟态美学，通过797+行精心设计的CSS变量和组件规范，为用户创造了沉浸式的深色界面体验。

后续可在缓存、监控与可观测性方面进一步增强，以满足更大规模的生产需求。同时，设计系统的持续演进将为产品带来更一致的视觉语言和更好的用户体验。

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

附录

关键入口与脚本
- 后端入口：backend/src/app.js
- 前端入口：frontend/src/main.js
- 路由汇总：backend/src/routes/index.js
- 认证路由：backend/src/routes/auth.js
- 模型索引：backend/src/models/index.js
- 数据库配置：backend/src/config/database.js
- 前端路由：frontend/src/router/index.js
- 布局组件：frontend/src/layout/index.vue
- 首页视图：frontend/src/views/home/index.vue
- 品牌标识：frontend/src/components/SidebarLogo.vue
- 设计系统规范：DESIGN.md
- 主题样式：frontend/src/styles/lux-theme.css
- 部署文档：DEPLOY.md
- 编排文件：docker-compose.yml

24 KiB Raw Blame History Unescape Escape

设计系统

更新摘要

目录

简介

设计哲学与核心理念

三层融合设计语言

设计原则

空间主题色彩系统

基础色板（Primitives）

语义化Token定义

深度层级系统（Elevation）

玻璃拟态设计语言

核心视觉特征

动态背景系统

字体系统与排版

组件设计规范

卡片组件（el-card）

表格组件（el-table）

对话框组件（el-dialog, Teleport）

输入框组件（el-input, el-select）

按钮组件 - Primary

侧边栏组件

顶部导航栏

项目结构

核心组件

架构总览

详细组件分析

认证流程（登录与鉴权）

首页"今日新增"数据流

数据模型与关系（简化）

布局与导航

品牌标识组件

依赖关系分析

性能与可扩展性

故障排查指南

结论

附录

24 KiB

Raw Blame History