ui 优化

2026-07-14 18:56:13 +08:00
parent 4f10cc1648
commit 003b44e2bd
32 changed files with 1082 additions and 375 deletions
@@ -0,0 +1,41 @@
+---
+kind: frontend_style
+name: Glassmorphism 深色主题与 Element Plus 定制体系
+category: frontend_style
+scope:
+    - '**'
+source_files:
+    - frontend/src/styles/lux-theme.css
+    - frontend/src/main.js
+    - frontend/src/App.vue
+    - frontend/src/layout/index.vue
+    - frontend/package.json
+---
+
+## 系统概述
+本项目前端采用 **Vue3 + Vite + Element Plus** 技术栈，通过自定义 CSS 变量与全局样式覆盖实现一套统一的 **Glassmorphism（玻璃拟态）深色主题**。主题以「深色宇宙底 + 半透明毛玻璃卡片 + 青紫渐变强调色」为核心视觉语言，贯穿侧栏、顶栏、卡片、表格、对话框等所有 UI 层级。
+
+## 核心文件与包
+- `frontend/src/styles/lux-theme.css` — 全站主题定义，包含设计令牌（CSS 变量）、Element Plus 组件覆盖、布局壳层样式
+- `frontend/src/main.js` — 应用入口，引入 Element Plus 暗黑模式 CSS 变量与 lux-theme.css
+- `frontend/src/App.vue` — 根组件，提供全局字体与基础 reset
+- `frontend/src/layout/index.vue` — 主布局壳层 `.lux-shell`，承载背景光球、侧栏、顶栏、内容区、底部版权
+- `frontend/package.json` — 依赖：element-plus、@element-plus/icons-vue、vue-router、axios
+
+## 架构与约定
+1. **设计令牌集中管理**：所有颜色、模糊半径、阴影、圆角、字号均通过 `:root` 下的 `--lux-*` CSS 变量声明，如 `--lux-cyan`、`--lux-glass-bg-card`、`--lux-blur-lg`、`--lux-radius-md` 等，新增/调整主题只需修改一处。
+2. **三层 L1/L2/L3 深度模型**：
+   - L0 背景：`.lux-shell-bg` 中的三个 `.lux-orb` 大光球（青色/紫色/珊瑚红），配合径向渐变底色营造“深空”氛围
+   - L1 内容层：`.el-card`、`.el-table` 使用半透明背景 + `backdrop-filter: blur()` 实现玻璃卡片与玻璃表格
+   - L2 浮动层：侧栏 `.sidebar-glass`、顶栏 `.lux-header` 独立浮于内容之上，带边框高光与内阴影
+   - L3 覆盖层：对话框、下拉菜单、消息框统一使用更高模糊度与更强阴影的 `.el-overlay .el-dialog` 等选择器
+3. **Element Plus 暗黑模式 + 全局覆盖**：在 `main.js` 中同时引入 `element-plus/theme-chalk/dark/css-vars.css` 与 `dist/index.css`，再通过 `.lux-shell` 作用域下的大量 `!important` 覆盖默认样式，确保主题一致性。
+4. **侧栏双态交互**：通过 `is-collapsed` 类在 64px 图标轨道与 220px 完整菜单间切换，hover 展开、离开收起，兼顾信息密度与空间效率。
+5. **响应式策略**：未引入 Tailwind 或媒体查询框架，主要依赖 Flexbox 布局与 CSS 变量；光球尺寸使用 `min(52vw, 400px)` 自适应，整体为桌面端优先的管理后台风格。
+
+## 开发者规范
+- **颜色使用**：优先引用 `var(--lux-*)` 变量，禁止硬编码十六进制值；品牌强调色限定为 `--lux-cyan` / `--lux-indigo` / `--lux-violet` / `--lux-coral`。
+- **玻璃效果**：需要半透明背景的元素统一搭配 `backdrop-filter: var(--lux-blur-*)` 与 `border: 1px solid var(--lux-glass-border)`，保持视觉层次一致。
+- **圆角与阴影**：遵循 `--lux-radius-{sm,md,lg,xl}` 与 `--lux-shadow-{1..4}` 阶梯，避免随意取值。
+- **组件覆盖范围**：所有 Element Plus 组件样式覆盖应包裹在 `.lux-shell` 选择器下，防止污染非管理界面。
+- **新页面结构**：页面根容器应置于 `<el-container class="lux-shell-body">` 内部，由 layout 统一提供侧栏/顶栏/页脚。
@@ -3,11 +3,11 @@ schema_version: 1
 locale: zh-CN
 branch: main
 nodes_managed: true
-exported_at: "2026-07-10T07:20:08Z"
+exported_at: "2026-07-10T09:19:18Z"
 modules:
    "":
-        dir_name: 音频设备管理仪表盘（前后端单体仓库）
-        title: 音频设备管理仪表盘（前后端单体仓库）
+        dir_name: 音频设备 CMS 管理系统（前后端全栈）
+        title: 音频设备 CMS 管理系统（前后端全栈）
        scope: []
        source_files: []
        children: []
@@ -0,0 +1,44 @@
+---
+kind: dependency_management
+name: pnpm 包管理与锁定文件策略
+category: dependency_management
+scope:
+    - '**'
+source_files:
+    - backend/package.json
+    - frontend/package.json
+    - backend/pnpm-lock.yaml
+    - frontend/pnpm-lock.yaml
+    - frontend/pnpm-workspace.yaml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+---
+
+本仓库采用 pnpm 作为统一的 Node.js 依赖管理工具，前后端各自维护独立的 package.json，并通过各自的 pnpm-lock.yaml 锁定依赖版本，确保构建可复现。
+
+### 1. 使用的系统与工具
+- 包管理器：pnpm（通过 packageManager 字段强制使用 pnpm@11.5.2）
+- 锁文件：backend/pnpm-lock.yaml、frontend/pnpm-lock.yaml
+- 前端工作区配置：frontend/pnpm-workspace.yaml（仅启用 esbuild 构建支持）
+- Docker 构建：后端与前端 Dockerfile 均 COPY package.json + pnpm-lock.yaml，在镜像内执行安装
+
+### 2. 关键文件与位置
+- backend/package.json — Express/Sequelize 等后端依赖声明
+- frontend/package.json — Vue3/Element Plus/Vite 等前端依赖声明
+- backend/pnpm-lock.yaml / frontend/pnpm-lock.yaml — 精确依赖快照
+- frontend/pnpm-workspace.yaml — pnpm workspace 基础配置
+- DEPLOY.md、scripts/upload.sh — 部署脚本中显式包含 lock 文件上传
+
+### 3. 架构与约定
+- 双包根结构：backend 与 frontend 各自为独立 npm 项目，无跨包共享依赖；每个目录有自己 node_modules、pnpm-lock.yaml
+- 版本范围：所有依赖使用 ^ 语义化版本前缀，由 pnpm 解析到具体版本并写入 lock 文件
+- 锁定文件纳入版本控制：lock 文件随代码提交，保证 CI/生产环境安装结果一致
+- 忽略 node_modules：前后端 .gitignore 均排除 node_modules/，避免将本地缓存入库
+- 私有源/代理：未发现 .npmrc、.pnpmrc 或 NPM_CONFIG_* 环境变量，默认使用官方 npm registry
+
+### 4. 开发者应遵循的规则
+- 始终使用 pnpm 安装依赖：pnpm install（禁止改用 npm/yarn）
+- 新增/升级依赖后必须提交对应的 pnpm-lock.yaml 变更
+- 不要手动编辑 lock 文件，使用 pnpm add/update/remove 命令操作
+- 在容器/Docker 环境中依赖安装阶段不应跳过 lock 文件校验
+- 如需切换 npm 源或添加私有 registry，应在仓库根或对应子项目下提供 .npmrc/.pnpmrc 并纳入版本控制
@@ -0,0 +1,30 @@
+---
+kind: design
+name: 全站采用 Glassmorphism 视觉风格
+source: session
+category: adr
+---
+
+# 全站采用 Glassmorphism 视觉风格
+
+_来源：b9ba1d5 → 4f10cc1 提交周期内记录的编码计划——内容为规划时意图，实现可能滞后或有出入。_
+
+**状态：** accepted
+
+## 背景
+dashboard 前端需要统一视觉升级，将现有 Element Plus 默认样式替换为毛玻璃（glassmorphism）风格，涉及卡片、表格、输入框、对话框、按钮、分页、标签等大量基础组件。
+
+## 决策驱动
+- 统一的现代视觉风格
+- 通过 CSS 变量集中管理设计 Token
+- 最小化业务组件改动
+
+## 备选方案
+- **在 lux-theme.css 中扩展 :root 设计 Token 并覆盖 Element Plus 类名** — 优点：无需引入新 UI 库；通过 backdrop-filter + 半透明实现毛玻璃效果；CSS 变量便于后续主题切换
+- **替换为第三方 glassmorphism UI 组件库** _（已否决）_ — 优点：开箱即用；缺点：增加依赖体积；与现有 Element Plus 混用样式冲突风险高；迁移成本大
+
+## 决策
+在 lux-theme.css 的 :root 中新增 glass surface / blur / shadow / spacing / radius 等设计 Token，并通过重写 .el-card、.el-table、.el-input、.el-dialog、.el-button--primary、.el-pagination、.el-tag、.el-dropdown-menu、.el-message-box 等 Element Plus 类名实现全站玻璃化，同时修复 brand/index.vue、blacklist/index.vue、ota-target-device/index.vue 等页面中硬编码颜色导致的可读性问题。
+
+## 影响
+所有列表页和首页需配合使用新的 glass 样式类；backdrop-filter 对低端设备有性能开销；未来新增页面需遵循新的 design token 而非直接写死颜色值。
@@ -0,0 +1,38 @@
+---
+kind: error_handling
+name: 前后端错误处理体系：统一响应体 + 拦截器 + 中间件
+category: error_handling
+scope:
+    - '**'
+source_files:
+    - backend/src/utils/response.js
+    - backend/src/middleware/auth.js
+    - backend/src/routes/auth.js
+    - backend/src/app.js
+    - frontend/src/utils/request.js
+---
+
+本仓库在后端（Express）与前端（Vue3 + Axios）分别建立了结构化的错误处理机制，核心思路是“后端返回统一 JSON 结构，前端通过拦截器集中处理 HTTP 状态码与业务码”。
+
+## 后端（Express）
+- **统一响应体**：`backend/src/utils/response.js` 导出 `ApiResponse.success / error / noData`，所有路由以 `{ code, msg, data }` 形式返回。业务错误使用 `code: 0`，成功使用 `code: 1`，无数据使用 `code: 2`。
+- **认证中间件**：`backend/src/middleware/auth.js` 的 `authMiddleware` 校验 Bearer Token，失败直接返回 `401 { detail }`；`requireSuperAdmin` 对非超级管理员返回 `403 { detail }`。这些 4xx 响应走 HTTP 状态码通道，不走业务码通道。
+- **路由层 try/catch**：各路由文件（如 `routes/auth.js`、`routes/blacklist.js`）在每个接口内包裹 try/catch，捕获异常后记录 `logger.error` 并以 `ApiResponse.error('xxx')` 返回，避免未捕获异常导致进程崩溃。
+- **全局异常**：未发现 Express 级别的 `app.use((err, req, res, next) => ...)` 全局错误处理器，异常由路由自身 catch 兜底。
+- **外部依赖错误**：Redis 连接在 `config/redis.js` 中监听 `'error'` 事件并仅记录日志，不中断服务。
+
+## 前端（Axios 拦截器）
+- **请求拦截器**：`frontend/src/utils/request.js` 自动注入 `Authorization: Bearer <token>`，跳过 `/auth/login`。
+- **响应拦截器**：
+  - 当后端返回 `res.code === 0` 时，视为业务错误，构造 `Error(res.msg)` 并通过 `ElMessage.error` 提示；若调用方设置 `skipErrorToast` 则静默拒绝。
+  - HTTP 401：清除本地 token，解析 `response.data.detail` 提示，并跳转到 `/login?redirect=...`。
+  - HTTP 403：弹出 `detail` 警告。
+  - 其他网络错误：打印 `console.error` 并用 `ElMessage.error` 提示“网络错误”。
+- **组件级 catch**：视图中的异步操作（如 `useModelList.js`）在 catch 中再次用 `ElMessage.error` 做兜底提示，形成“拦截器通用提示 + 业务特定提示”的双层策略。
+
+## 约定与规则
+1. 后端所有业务错误必须通过 `ApiResponse.error(msg, code?)` 返回，不要直接 `throw` 裸 Error。
+2. 认证相关错误优先使用 HTTP 401/403 + `{ detail }` 结构，以便前端拦截器区分处理。
+3. 路由函数内部应包裹 try/catch，确保异常被记录并转为 `ApiResponse.error`。
+4. 前端如需自定义错误提示（如推送进度弹窗），在 axios 配置中传入 `skipErrorToast: true` 以抑制默认 ElMessage。
+5. 未实现全局错误中间件，新增路由需自行遵循 try/catch 模式。
@@ -0,0 +1,40 @@
+---
+kind: logging_system
+name: 后端日志系统（Winston 统一输出）
+category: logging_system
+scope:
+    - '**'
+source_files:
+    - backend/src/config/logger.js
+    - backend/src/app.js
+    - backend/src/routes/auth.js
+    - backend/src/config/redis.js
+    - backend/src/services/curveClient.js
+    - backend/src/services/measurementStorage.js
+    - backend/src/services/otaStorage.js
+---
+
+## 1. 使用的系统与框架
+- 后端采用 **Winston** 作为统一的日志框架，通过 `backend/src/config/logger.js` 集中创建并导出单例 logger。
+- 前端未引入独立日志库，调试主要依赖浏览器控制台，无统一前端日志方案。
+
+## 2. 核心文件与包
+- `backend/src/config/logger.js` — Winston 实例定义、格式与传输层配置。
+- `backend/logs/app.log` — 默认文件输出路径，由 Dockerfile / 启动脚本挂载持久化。
+- 各模块通过 `require('../config/logger')` 或同级相对路径引入 logger，如 `routes/auth.js`、`services/*.js`、`config/redis.js` 等。
+
+## 3. 架构与约定
+- **全局级别**：默认 `level: 'info'`，低于 info 的日志被丢弃。
+- **格式化**：时间戳 `YYYY-MM-DD HH:mm:ss` + level + message + 可选 meta JSON；meta 对象会被 `JSON.stringify` 拼接在末尾，便于结构化检索。
+- **双通道输出**：
+  - Console transport：容器标准输出，供 docker-compose / k8s 收集。
+  - File transport：写入 `backend/logs/app.log`，UTF-8 编码。
+- **使用模式**：业务代码直接调用 `logger.info/warn/error(...)`，参数为模板字符串，将关键上下文（用户名、URL、S3 key 等）拼入消息体，而非传递结构化对象。
+- **数据库 SQL 日志**：Sequelize 仅在开发环境启用 `console.log` 输出 SQL，生产环境关闭，避免污染主日志。
+
+## 4. 开发者应遵循的规则
+- 统一从 `../config/logger` 引入 logger，不要直接使用 `console.log` 记录业务事件。
+- 按语义选择级别：正常流程用 `info`，可恢复异常或降级用 `warn`，不可恢复错误用 `error`。
+- 将关键上下文（用户、设备、外部服务 URL、S3 key 等）以字符串形式嵌入 message，保持单行可读；如需结构化字段，可通过第三个参数传入对象，Winston 会自动序列化到末尾。
+- 敏感信息（密码、token）不得写入日志；认证失败仅记录用户名等非敏感字段。
+- 新增模块若需额外文件输出或按级别分片，应在 `config/logger.js` 中扩展 transports，而不是在各处重复创建 logger。
@@ -0,0 +1,52 @@
+---
+kind: configuration_system
+name: 后端环境变量与配置加载体系
+category: configuration_system
+scope:
+    - '**'
+source_files:
+    - backend/src/config/loadEnv.js
+    - backend/src/config/env.js
+    - backend/src/config/database.js
+    - backend/src/config/redis.js
+    - backend/src/config/logger.js
+    - .env.example
+    - backend/src/app.js
+---
+
+## 系统概述
+本项目的配置系统基于 Node.js 的 `dotenv` + 进程环境变量（`process.env`）实现，采用「根目录 `.env` 文件 + Docker compose env_file 注入」的双源模式，通过统一的入口在应用启动时完成加载。
+
+## 核心机制
+- **统一入口**：`backend/src/app.js` 首行 `require('./config/loadEnv')` 触发配置加载，确保所有后续模块都能读到环境变量。
+- **本地开发**：`loadEnv.js` 解析项目根目录 `dashboard/.env`（相对 `__dirname` 向上四层），使用 `dotenv.config({ path })` 注入到 `process.env`；若文件不存在则静默跳过。
+- **Docker 部署**：容器内无 `.env` 文件，由 `docker-compose.yml` 的 `env_file` 直接注入环境变量，`fs.existsSync` 判断避免覆盖已有值。
+- **环境判断**：`config/env.js` 暴露 `APP_ENV`、`isDevelopment`、`isProduction` 三个常量，供各模块按环境切换行为（如 Sequelize SQL 日志开关）。
+
+## 配置项组织
+所有可配置项集中在根级 `.env.example`，按功能域分组注释：
+- 数据库：`DATABASE_HOST/PORT/NAME/USER/PASSWORD`
+- 应用：`APP_NAME`、`APP_ENV`、`PORT`
+- JWT 与初始管理员：`JWT_SECRET`、`DASHBOARD_ADMIN_USERNAME/PASSWORD`
+- Meilisearch：`MEILISEARCH_URL/API_KEY/INDEX`
+- AWS S3：`AWS_REGION/ACCESS_KEY_ID/SECRET_ACCESS_KEY/S3_OTA_BUCKET/S3_MEASUREMENT_BUCKET`
+- OTA URL 与上传目录：`OTA_X8_PUBLIC_BASE`、`OTA_X9_URL_BASE`、`OTA_UPLOAD_DIR`
+- Curve API：`CURVE_API_BASE_URL`
+- Redis EQ 缓存：`REDIS_HOST/PORT/PASSWORD/EQ_DB`
+
+## 配置消费方式
+各模块直接通过 `process.env.XXX || '默认值'` 读取，形成「分散式消费」模式：
+- `config/database.js` → MySQL 连接参数
+- `config/redis.js` → ioredis 客户端（含密码可选、错误监听）
+- `config/logger.js` → winston 输出级别与文件路径
+- `services/otaStorage.js` → OTA 包上传目录与 S3 配置
+- `services/measurementStorage.js` → 频响测量文件 S3 存储
+- `routes/models.js` → Meilisearch 搜索索引
+- `services/curveClient.js` → 曲线查询外部 API 基地址
+
+## 设计约定与约束
+1. **禁止硬编码敏感信息**：所有密钥、密码、URL 必须来自环境变量，`.env` 已在 `.gitignore` 中排除。
+2. **默认值兜底**：每个 `process.env` 读取都提供合理默认值，保证本地开箱即用。
+3. **按域拆分配置文件**：数据库、Redis、日志等基础设施各自独立文件，便于扩展新依赖。
+4. **Docker 优先**：生产环境推荐通过 compose `env_file` 注入而非挂载 `.env` 文件。
+5. **新增配置项流程**：先在 `.env.example` 添加注释说明，再在各消费处补充 `process.env.XXX || default`。
@@ -0,0 +1,88 @@
+---
+kind: build_system
+name: 构建与部署体系（Docker Compose + pnpm + rsync）
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/vite.config.js
+    - backend/src/config/env.js
+    - scripts/upload.sh
+    - DEPLOY.md
+---
+
+## 1. 构建系统概览
+
+本项目采用 **多阶段 Docker 构建 + Docker Compose 编排** 的容器化部署方案，前端基于 Vite 静态资源构建，后端基于 Node.js 22 Alpine 镜像运行。开发环境通过 pnpm 管理依赖，生产环境通过 `scripts/upload.sh` 将代码同步至远端 EC2 服务器后由 Docker Compose 拉起服务。
+
+- **包管理器**：pnpm@11.5.2（前后端均声明 `packageManager` 字段锁定版本）
+- **前端构建**：Vite 6，产物输出到 `frontend/dist/`，使用 Rollup `manualChunks` 拆分 vendor 包
+- **后端运行**：Node.js 22-alpine，直接执行 `src/app.js`
+- **编排工具**：docker-compose.yml 定义 frontend（nginx:alpine）与 backend 两个服务
+- **发布脚本**：`scripts/upload.sh` 基于 rsync+ssh 增量同步代码到 AWS EC2
+
+## 2. 关键文件与职责
+
+| 文件 | 作用 |
+|------|------|
+| `docker-compose.yml` | 服务编排、端口映射、环境变量注入、日志轮转策略、OTA 数据卷挂载 |
+| `backend/Dockerfile` | 后端镜像构建：仅安装 prod 依赖，暴露 8000 端口 |
+| `frontend/Dockerfile` | 多阶段构建：node:18 构建 → nginx:alpine 托管 dist |
+| `frontend/vite.config.js` | 开发代理 `/api→localhost:8083`、手动分包、别名 `@` |
+| `backend/src/config/env.js` | 统一 APP_ENV 判断（development / production） |
+| `scripts/upload.sh` | 支持 `frontend/backend/compose/all` 目标及 `-n` 干跑模式 |
+| `DEPLOY.md` | 完整部署文档：目录结构、环境变量、更新流程、排错 |
+
+## 3. 架构与约定
+
+### 3.1 服务拓扑
+
+```
+浏览器 :8082 (Nginx) ──/api──▶ 容器内 backend:8000 (Express)
+                              ├── MySQL
+                              ├── Redis (EQ 缓存)
+                              └── S3 (OTA/测量数据)
+```
+
+- 宿主机端口：frontend 8082、backend 8083；容器内端口固定为 80 与 8000
+- 前端通过 Nginx 反向代理 `/api` 到 `http://backend:8000`
+- OTA 升级包通过宿主机卷 `/data/projects/source` 持久化
+
+### 3.2 构建流水线
+
+1. **本地开发**：`pnpm dev`（Vite 热重载，代理 API 到 8083）
+2. **本地构建**：`pnpm build` → 生成 `frontend/dist/`
+3. **上传**：`./scripts/upload.sh all` → rsync 同步 dist、backend/src、compose 到服务器
+4. **服务器部署**：`docker compose build --no-cache backend && docker compose up -d`
+
+### 3.3 环境变量策略
+
+- 所有配置集中在根目录 `.env`，Compose 通过 `env_file` 注入
+- 后端通过 `APP_ENV` 区分 development/production，影响日志、数据库等配置
+- `.env` 不被 Git 跟踪，也不被 `upload.sh` 上传，需在服务器单独维护
+
+### 3.4 镜像优化
+
+- 后端仅拷贝 `package.json`、`pnpm-lock.yaml`、`src/`，不拷贝测试/文档
+- 使用 `--frozen-lockfile` 确保依赖可重现
+- 前端多阶段构建，最终镜像仅包含静态资源与 Nginx
+
+## 4. 开发者应遵循的规则
+
+1. **依赖锁定**：修改 `package.json` 后必须重新生成 `pnpm-lock.yaml`，否则 Docker 构建会失败
+2. **环境变量**：新增配置需同步更新 `.env.example` 和 `DEPLOY.md` 的环境变量表
+3. **端口约定**：容器内后端固定 8000，不要随意修改，否则 Nginx 代理与健康检查会失效
+4. **OTA 存储路径**：后端读取的 OTA 包目录 `/data/projects/source` 必须在宿主机存在且对容器可写
+5. **上传范围**：默认不同步 `nginx.conf` 与 `Dockerfile`，如需变更请显式指定路径
+6. **重启策略**：修改 `.env` 后需 `docker compose up -d --force-recreate backend` 才能生效
+7. **日志查看**：使用 `docker compose logs -f backend` 或 `docker compose logs -f frontend`
+
+## 5. 未覆盖的领域
+
+- 无 CI/CD 流水线（GitHub Actions / GitLab CI 等），部署完全依赖本地脚本
+- 无 Makefile、Gradle、Maven 等传统构建工具
+- 无自动化测试脚本集成到构建流程
+- 版本号管理停留在 `package.json` 的 `version` 字段，无语义化版本发布流程
@@ -1,6 +1,6 @@
 schema_version: 1
 module_path: ""
-title: 音频设备管理仪表盘（前后端单体仓库）
+title: 音频设备 CMS 管理系统（前后端全栈）
 scope: []
 source_files: []
 depends_on: []
@@ -0,0 +1 @@
+前端：Vue 3.3 + Vite 6 + Element Plus 2.3（暗黑 CSS 变量 + 中文 locale）+ vue-router 4 + axios；后端：Express 4 + Sequelize 6 + mysql2 + JWT + Zod 校验 + AWS S3 SDK + Winston 日志 + ioredis；构建与编排：pnpm@11、Docker Compose、Nginx Alpine。
@@ -0,0 +1,5 @@
+仓库为典型的前后端分离单仓结构：
+- `backend/src` 采用 Express 应用层 + Sequelize ORM 的数据访问层划分：`config/` 集中加载 `.env`、数据库、Redis、日志；`middleware/` 放置全局中间件（鉴权、bodyLimit）；`models/` 通过 `index.js` 统一 `sync()` 并导出；`routes/` 按资源拆分路由文件并在 `routes/index.js` 聚合挂载；`services/` 封装外部依赖（S3、Curve、EQ 缓存、OTA 存储、用户引导）；`validators/` 使用 zod 做入参校验；入口 `app.js` 在启动时执行 `sequelize.sync()` 与超级管理员引导。
+- `frontend/src` 基于 Vite + Vue3 + Element Plus，`main.js` 引入 Element Plus 暗黑 CSS 变量与自定义 `lux-theme.css`，`router/index.js` 声明式路由，`api/` 目录按资源一一对应后端 REST 接口，`views/` 按功能域组织页面组件，`components/` 存放跨页面复用组件。
+- 部署由根级 `docker-compose.yml` 编排：`backend` 容器暴露 8083，`frontend` 使用 nginx:alpine 静态托管 `dist` 并通过 `nginx.conf` 反向代理到后端，共享 `audio-network` 网络。
+- 顶层 `autoeq/` 存放测量数据 CSV/TXT 样本，`scripts/upload.sh` 用于上传脚本，`DEPLOY.md` / `DESIGN.md` 记录部署与设计说明。
@@ -0,0 +1 @@
+基于 Vue3 + Element Plus 与 Express + Sequelize 的耳机品牌/型号、OTA 升级、黑名单与用户管理后台，提供 Glassmorphism 深色主题 UI。
@@ -0,0 +1 @@
+开发：`cd frontend && pnpm dev` 启动 Vite 热更新；`cd backend && pnpm start` 或 `pnpm dev`（nodemon）。生产：`docker compose up -d --build`，需先复制 `.env.example` 为 `.env` 填写 DB/Redis/S3/JWT 等环境变量；前端构建产物位于 `frontend/dist`，由 nginx 容器以只读方式挂载。
@@ -0,0 +1,5 @@
+- 前端样式集中在 `src/styles/lux-theme.css`，通过 `:root` CSS 变量定义色板、模糊半径、阴影层级，所有组件覆盖均以 `.lux-shell .el-*` 选择器限定作用域，不修改业务逻辑代码。
+- 后端路由按资源拆分为独立文件（如 `brands.js`、`models.js`、`ota.js`），在 `routes/index.js` 中统一遍历注册，新资源只需新增路由文件并加入数组即可生效。
+- 模型定义遵循 Sequelize 标准模式，并在 `models/index.js` 中集中 `sync({ force: false })`，避免在各路由中重复初始化连接。
+- 请求参数校验统一放在 `validators/` 目录下对应模块，使用 zod schema 描述后在路由 handler 中调用，保持路由层仅负责编排。
+- 前端 API 调用集中在 `src/api/` 下与后端资源一一对应的 JS 文件中，组件侧仅 import 函数而不直接写 axios 请求。
@@ -1 +0,0 @@
-后端：Express 4 + Sequelize 6 + mysql2 + jsonwebtoken + multer + @aws-sdk/client-s3 + winston + ioredis + zod；前端：Vue 3 + vue-router 4 + Element Plus（含 dark css-vars）+ vite 6 + axios；部署：Docker Compose（backend 镜像自 build，frontend 使用 nginx:alpine 静态托管）。
@@ -1,5 +0,0 @@
-仓库采用前后端分离的单体结构：
- `backend/src` 为 Express API 服务，入口 `app.js` 统一挂载 CORS、JSON 解析、`bodyLimit` 中间件，并通过 `routes/index.js` 聚合 auth/brands/models/ota/blacklist/otaTargetDevice/shareCodeLogs/users/dashboard 等路由；数据层使用 Sequelize + mysql2，模型集中在 `models/` 并导出到 `models/index.js`；外部依赖通过 `services/` 抽象（curveClient 调用第三方曲线服务、eqCacheStorage/squiglink 处理 EQ 缓存、measurementStorage/otaStorage 对接 S3、userBootstrap 负责超级管理员初始化）；鉴权由 `middleware/auth.js` + `utils/jwt.js` 实现。
- `frontend/src` 为 Vite + Vue3 + Element Plus SPA，`router/index.js` 集中声明所有页面路由并在 `beforeEach` 中做 token 校验与超级管理员权限拦截；`api/` 下每个文件对应一个后端模块的 axios 封装；`views/` 按功能域分目录组织页面，`components/` 存放全局复用组件（ChangePasswordDialog、SidebarLogo、TabsView），`layout/index.vue` 提供侧边栏+标签页布局。
- 顶层 `docker-compose.yml` 编排 backend（Node）与 frontend（nginx:alpine 静态托管 dist），共享 `audio-network` 网络；`.env.example` 提供环境变量模板。
- 依赖方向单向：前端 → 后端 REST API，后端 → MySQL/S3/Redis/第三方 curve 服务，无跨包反向引用。
@@ -1 +0,0 @@
-基于 Vue3 + Express/Sequelize 的耳机品牌、型号、OTA 与用户管理后台，提供曲线上传、S3 存储与 Element Plus 驱动的 Web 界面。
@@ -1 +0,0 @@
-开发：`pnpm install` 后分别进入 `backend` 和 `frontend` 执行 `pnpm dev`；生产：`cd frontend && pnpm build` 生成 `dist/`，再 `docker compose up -d --build` 启动双容器，需提前准备 `.env`（参考 `.env.example`）并挂载 `/data/projects/source` 供 S3 本地模拟访问。
@@ -1,5 +0,0 @@
- 后端路由以独立文件暴露 express router，再由 `routes/index.js` 统一收集注册，避免在 app.js 内散写 use()。
- Sequelize 模型按领域单文件定义（Brand/Model/Ota/BlackList 等），并通过 `models/index.js` 集中 re-export 给 routes/services 使用。
- 前端路由采用懒加载 `() => import('@/views/...')` 形式，meta 字段声明 title/icon/requiresAuth/requiresSuperAdmin 控制导航与守卫。
- 前端 API 调用按业务域拆分到 `src/api/*.js`，每个文件对应一个后端路由模块，统一通过 `axios` 实例发起请求。
- 前端页面按功能域在 `views/<domain>/index.vue` 下组织，复杂页面内部再拆 `components/` 与 `composables/` 子目录。
				`@@ -0,0 +1 @@`
				`前端：Vue 3.3 + Vite 6 + Element Plus 2.3（暗黑 CSS 变量 + 中文 locale）+ vue-router 4 + axios；后端：Express 4 + Sequelize 6 + mysql2 + JWT + Zod 校验 + AWS S3 SDK + Winston 日志 + ioredis；构建与编排：pnpm@11、Docker Compose、Nginx Alpine。`
				`@@ -0,0 +1 @@`
				`基于 Vue3 + Element Plus 与 Express + Sequelize 的耳机品牌/型号、OTA 升级、黑名单与用户管理后台，提供 Glassmorphism 深色主题 UI。`
				`@@ -0,0 +1 @@`
				开发：`cd frontend && pnpm dev` 启动 Vite 热更新；`cd backend && pnpm start` 或 `pnpm dev`（nodemon）。生产：`docker compose up -d --build`，需先复制 `.env.example` 为 `.env` 填写 DB/Redis/S3/JWT 等环境变量；前端构建产物位于 `frontend/dist`，由 nginx 容器以只读方式挂载。
				`@@ -1 +0,0 @@`
				`后端：Express 4 + Sequelize 6 + mysql2 + jsonwebtoken + multer + @aws-sdk/client-s3 + winston + ioredis + zod；前端：Vue 3 + vue-router 4 + Element Plus（含 dark css-vars）+ vite 6 + axios；部署：Docker Compose（backend 镜像自 build，frontend 使用 nginx:alpine 静态托管）。`
				`@@ -1 +0,0 @@`
				`基于 Vue3 + Express/Sequelize 的耳机品牌、型号、OTA 与用户管理后台，提供曲线上传、S3 存储与 Element Plus 驱动的 Web 界面。`
				`@@ -1 +0,0 @@`
				开发：`pnpm install` 后分别进入 `backend` 和 `frontend` 执行 `pnpm dev`；生产：`cd frontend && pnpm build` 生成 `dist/`，再 `docker compose up -d --build` 启动双容器，需提前准备 `.env`（参考 `.env.example`）并挂载 `/data/projects/source` 供 S3 本地模拟访问。