新增 luxsin-controller，更新 wiki

2026-07-10 16:51:05 +08:00
parent b9ba1d5ed4
commit fc88d42be9
28 changed files with 1009 additions and 270 deletions
@@ -0,0 +1,56 @@
+---
+kind: frontend_style
+name: LUXSIN 深色主题与 Element Plus 定制体系
+category: frontend_style
+scope:
+    - '**'
+source_files:
+    - frontend/src/styles/lux-theme.css
+    - frontend/src/main.js
+    - frontend/src/layout/index.vue
+    - frontend/src/components/SidebarLogo.vue
+    - frontend/package.json
+---
+
+## 系统概述
+前端采用 Vue3 + Vite + Element Plus 技术栈，通过自定义 CSS 变量与全局样式覆盖实现统一的「LUXSIN」深色宇宙风格主题。整体视觉以深空背景、玻璃态（glassmorphism）侧栏、青紫渐变强调色为特征。
+
+## 核心文件与依赖
+- `frontend/src/styles/lux-theme.css`：全站主题定义，包含 CSS 变量、Element Plus 组件覆盖、布局壳层样式
+- `frontend/src/main.js`：应用入口，注册 ElementPlus（含中文 locale）、加载主题与暗黑模式 CSS 变量
+- `frontend/src/layout/index.vue`：主布局壳层 `.lux-shell`，承载侧栏/顶栏/内容区结构
+- `frontend/src/components/SidebarLogo.vue`：品牌 Logo 组件，内嵌 SVG 渐变图标
+- `frontend/package.json`：声明 `element-plus@^2.3.14`、`@element-plus/icons-vue`、`vue-router`、`axios` 等依赖
+
+## 架构与约定
+### 设计令牌（CSS Variables）
+在 `:root` 中集中声明所有设计令牌，命名统一以 `--lux-` 前缀：
+- 字体：`--lux-font`
+- 背景：`--lux-page-bg`、`--lux-card-bg`、`--lux-glass-sidebar`、`--lux-glass-header`、`--lux-input-bg`
+- 文本：`--lux-text-strong`、`--lux-text-muted`
+- 强调色：`--lux-cyan`、`--lux-indigo`、`--lux-violet`
+- 边框：`--lux-card-border`
+
+### 主题策略
+1. **Element Plus 暗黑模式**：通过 `import 'element-plus/theme-chalk/dark/css-vars.css'` 启用 CSS 变量驱动的主题切换能力
+2. **全局覆盖**：`lux-theme.css` 使用大量 `!important` 覆盖 Element Plus 默认样式，包括卡片、表格、按钮、输入框、分页、对话框、下拉菜单、消息框等组件的深色外观
+3. **布局壳层**：所有页面嵌套在 `.lux-shell` 容器内，背景使用径向渐变 + 三个模糊光球（`.lux-orb-*`）营造空间感；侧栏使用 `backdrop-filter: blur(18px)` 实现毛玻璃效果
+4. **响应式侧栏**：支持折叠态（64px 图标轨道）与展开态（220px 完整菜单），通过 `is-collapsed` 类名切换
+
+### 组件库与图标
+- UI 组件：Element Plus 2.x，配合 `@element-plus/icons-vue` 图标集
+- 无第三方 CSS 框架（如 Tailwind），全部手写 CSS
+- 无 SCSS/Less 预处理器，纯 CSS
+
+### 视觉规范
+- 圆角：卡片 16px、按钮/输入框 10px、标签 8px、对话框 18px
+- 阴影：多层 box-shadow 模拟悬浮深度，强调色带发光效果
+- 字体：Inter / Segoe UI / PingFang SC / Microsoft YaHei 回退链
+- 颜色：主按钮使用 `#38bdf8` 青色，悬停变为 `#22d3ee`，警告/危险分别带橙色/红色发光阴影
+
+## 开发者应遵循的规则
+1. **新增颜色必须走 CSS 变量**：在 `:root` 中声明 `--lux-*` 变量，禁止在组件中硬编码颜色值
+2. **组件样式优先 scoped**：业务组件使用 `<style scoped>`，仅对 Element Plus 全局组件的覆盖放在 `lux-theme.css` 中
+3. **不要引入新的 CSS 框架**：保持纯 CSS + Element Plus 覆盖的统一风格，避免 Tailwind 等原子类混用
+4. **深色主题一致性**：所有新增组件需适配现有深色配色方案，确保文字可读性（`--lux-text-strong` / `--lux-text-muted`）
+5. **侧栏交互复用**：如需新导航项，参考 `layout/index.vue` 中的路由分组逻辑与 `sidebar-rail` 折叠态处理
@@ -3,7 +3,7 @@ schema_version: 1
 locale: zh-CN
 branch: main
 nodes_managed: true
-exported_at: "2026-07-10T03:11:01Z"
+exported_at: "2026-07-10T07:20:08Z"
 modules:
    "":
        dir_name: 音频设备管理仪表盘（前后端单体仓库）
@@ -13,23 +13,3 @@ modules:
        children: []
        depends_on: []
        related_to: []
-    backend:
-        dir_name: 耳机品牌与型号管理后端 API
-        title: 耳机品牌与型号管理后端 API
-        scope:
-            - backend/
-        source_files: []
-        children: []
-        depends_on: []
-        related_to:
-            - path: frontend
-    frontend:
-        dir_name: 耳机品牌与 OTA 升级管理前端
-        title: 耳机品牌与 OTA 升级管理前端
-        scope:
-            - frontend/
-        source_files: []
-        children: []
-        depends_on: []
-        related_to:
-            - path: backend
@@ -0,0 +1,30 @@
+---
+kind: design
+name: 将 model/index.vue 按功能边界拆分为子组件与 composable
+source: session
+category: adr
+---
+
+# 将 model/index.vue 按功能边界拆分为子组件与 composable
+
+_来源：b4926ba → 6bb39e9 提交周期内记录的编码计划——内容为规划时意图，实现可能滞后或有出入。_
+
+**状态：** accepted
+
+## 背景
+frontend/src/views/model/index.vue 文件膨胀至 1824 行，同时承载搜索列表、5 个对话框、大量状态管理与样式，导致可读性与可维护性下降。
+
+## 决策驱动
+- 单文件过大难以维护
+- 按功能边界提升复用性
+- 保持页面编排职责单一
+
+## 备选方案
+- **按功能拆分：components + composables** — 优点：每个对话框独立文件；列表逻辑抽到 useModelList.js；index.vue 仅保留编排与 API 调用
+- **不拆分，继续在同一文件中迭代** _（已否决）_ — 优点：改动最小；缺点：文件持续膨胀，新增功能成本更高
+
+## 决策
+将 index.vue 拆为 ~250 行的主页面编排文件，并新建 components/ModelFormDialog.vue、EqCacheDialog.vue、PushProgressDialog.vue、CsvViewerDialog.vue、PushViewDialog.vue 以及 composables/useModelList.js；各对话框的触发逻辑移入 index.vue 中直接调用 API 后将结果通过 props 传给子组件。
+
+## 影响
+index.vue 大幅瘦身，新增/编辑、EQ 缓存、推送进度等能力可被其他页面复用；但需要维护更多文件与父子通信契约（props/emits/expose）。
@@ -1,14 +0,0 @@
-schema_version: 1
-module_path: ""
-title: 耳机品牌与 OTA 升级管理平台（前后端编排）
-scope:
-    - .gitignore
-    - README.md
-    - DEPLOY.md
-    - docker-compose.yml
-    - scripts/
-    - .env
-    - .env.example
-source_files: []
-depends_on: []
-related_to: []
@@ -1,4 +0,0 @@
- **服务编排**：`docker-compose.yml` 定义 `backend`（Node.js + Sequelize）和 `frontend`（Nginx 静态托管）两个服务，共用 `audio-network` 桥接网络，前端通过 Nginx 反向代理 `/api` 至后端。
- **配置边界**：根目录 `.env` 为唯一环境变量源，Compose 注入后端容器；`.env.example` 提供模板，禁止子模块各自维护环境文件。
- **存储契约**：宿主机 `/data/projects/source` 挂载至后端容器，作为 OTA 升级包的持久化共享卷，前后端以此路径为约定进行文件交互。
- **部署流水线**：`scripts/upload.sh` 基于 rsync/ssh 将前端构建产物、后端源码与编排文件增量推送至服务器，配合 `DEPLOY.md` 形成本地→远端的标准化运维路径。
@@ -1 +0,0 @@
-通过 Docker Compose 统一编排 Vue 3 前端与 Express 后端，并以标准化脚本驱动从本地到远程服务器的增量同步与容器化部署。
@@ -1,9 +0,0 @@
-schema_version: 1
-module_path: frontend
-title: 耳机品牌与 OTA 升级管理前端
-scope:
-    - frontend/
-source_files: []
-depends_on: []
-related_to:
-    - path: backend
@@ -1 +0,0 @@
-Vue 3, Vite, Element Plus, Axios, Vue Router
@@ -1,4 +0,0 @@
- **技术栈**: 采用 Vue 3 (Composition API) + Vite 构建，UI 框架为 Element Plus，路由使用 vue-router。
- **目录结构**: 遵循经典的前端分层架构：`src/api` 封装 Axios 请求与业务接口；`src/views` 存放页面级组件；`src/components` 存放通用 UI 组件；`src/layout` 定义整体布局（侧边栏、顶部导航）；`src/utils` 提供认证、HTTP 拦截器等工具函数。
- **核心机制**: `src/utils/request.js` 实现了统一的 HTTP 拦截器，处理 JWT Token 注入、401/403 错误自动跳转登录及全局错误提示。`src/router/index.js` 配置了基于角色的路由守卫，支持超级管理员权限控制。
- **状态管理**: 未引入 Pinia/Vuex，认证状态（Token、用户信息）通过 `localStorage` 配合 `src/utils/auth.js` 中的工具函数进行持久化与管理。
@@ -1 +0,0 @@
-基于 Vue 3 和 Element Plus 构建的耳机品牌、型号及 OTA 升级管理的单页应用。
@@ -1,3 +0,0 @@
- API 模块按业务领域拆分（如 auth.js, brand.js），统一导出异步方法并依赖 @/utils/request 实例。
- 视图组件采用路径映射命名规范，每个业务模块在 views 下拥有独立文件夹及 index.vue 入口文件。
- 认证逻辑集中在 utils/auth.js，提供 getToken, isSuperAdmin, clearAuth 等原子操作供路由守卫和组件调用。
@@ -1,9 +0,0 @@
-schema_version: 1
-module_path: backend
-title: 耳机品牌与型号管理后端 API
-scope:
-    - backend/
-source_files: []
-depends_on: []
-related_to:
-    - path: frontend
@@ -1 +0,0 @@
-Node.js 22 (Alpine) + Express v4；Sequelize v6 + mysql2 访问 MySQL；ioredis 连接 Redis 缓存 EQ；@aws-sdk/client-s3 上传 OTA 包与测量文件；axios 调用 Meilisearch 搜索索引；jsonwebtoken 签发/验证 JWT；zod 做参数校验；winston 输出到 `logs/app.log`。
@@ -1,4 +0,0 @@
- 入口 `src/app.js` 加载 `.env`（`config/loadEnv.js` 从仓库根目录读取）、注册 CORS/JSON/bodyLimit 中间件、挂载路由数组并调用 `sequelize.sync()` 建表后执行 `ensureBootstrapSuperAdmin` 引导超级管理员。
- 分层组织：`routes/` 按业务域拆分（auth, brands, models, ota, blacklist, otaTargetDevice, shareCodeLogs, users, dashboard），由 `routes/index.js` 汇总导出供 app 遍历挂载；`models/` 使用 Sequelize 定义实体并通过 `index.js` 统一导出；`services/` 封装外部依赖（S3、Redis、Meilisearch、曲线服务）；`middleware/` 提供认证与请求体大小限制；`utils/` 暴露 JWT、密码哈希、统一响应格式；`validators/` 以 zod schema 校验入参。
- 认证边界：`middleware/auth.js` 解析 Bearer token 注入 `req.user`，受保护路由在各自文件中通过 `router.use(authMiddleware)` 全局启用，仅 `/health`、根路径等公开接口例外；`requireSuperAdmin` 用于超管专用端点。
- 启动流程：`start.sh` → `node src/app.js` → `loadEnv` → `sequelize.sync()` → `userBootstrap.ensureBootstrapSuperAdmin()` → `app.listen(8083)`，异常时降级继续运行。
@@ -1 +0,0 @@
-基于 Express + Sequelize 的 RESTful 服务，提供耳机品牌、型号、OTA 升级、用户与黑名单管理的后端接口。
@@ -1 +0,0 @@
-包管理器锁定为 `pnpm@11.5.2`，安装需 `pnpm install --frozen-lockfile`；本地开发可用 `pnpm dev`（nodemon 热重载），生产通过 `start.sh`/`stop.sh`/`restart.sh` 或 Docker 镜像启动；首次启动若 `dashboard_user` 为空则根据 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 环境变量创建初始超级管理员。
@@ -1,5 +0,0 @@
- 所有 API 返回统一 JSON 结构，包含 `code`（1:成功 / 0:错误 / 2:无数据）、`msg` 和 `data` 字段，由 `utils/response.js` 的 `ApiResponse` 生成。
- 受保护路由在各自文件顶部通过 `router.use(authMiddleware)` 全局启用 JWT 校验，仅健康检查等公开接口例外。
- 更新操作显式判断请求体字段是否为 `undefined` 或 `'null'` 字符串，区分“未提供”与“设为空”，避免覆盖现有值。
- 关键业务动作（登录、CRUD、权限拒绝）通过 `logger.info/warn/error` 记录到 `logs/app.log`，错误堆栈附带上下文信息。
- 环境变量集中通过 `config/loadEnv.js` 从仓库根目录 `.env` 加载，Docker 场景下由 compose env_file 注入而不覆盖已有变量。
				`@@ -1 +0,0 @@`
				`通过 Docker Compose 统一编排 Vue 3 前端与 Express 后端，并以标准化脚本驱动从本地到远程服务器的增量同步与容器化部署。`
				`@@ -1 +0,0 @@`
				`Vue 3, Vite, Element Plus, Axios, Vue Router`
				`@@ -1 +0,0 @@`
				`基于 Vue 3 和 Element Plus 构建的耳机品牌、型号及 OTA 升级管理的单页应用。`
				`@@ -1 +0,0 @@`
				Node.js 22 (Alpine) + Express v4；Sequelize v6 + mysql2 访问 MySQL；ioredis 连接 Redis 缓存 EQ；@aws-sdk/client-s3 上传 OTA 包与测量文件；axios 调用 Meilisearch 搜索索引；jsonwebtoken 签发/验证 JWT；zod 做参数校验；winston 输出到 `logs/app.log`。
				`@@ -1 +0,0 @@`
				`基于 Express + Sequelize 的 RESTful 服务，提供耳机品牌、型号、OTA 升级、用户与黑名单管理的后端接口。`
				`@@ -1 +0,0 @@`
				包管理器锁定为 `pnpm@11.5.2`，安装需 `pnpm install --frozen-lockfile`；本地开发可用 `pnpm dev`（nodemon 热重载），生产通过 `start.sh`/`stop.sh`/`restart.sh` 或 Docker 镜像启动；首次启动若 `dashboard_user` 为空则根据 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 环境变量创建初始超级管理员。