全新的前端ui

2026-07-16 16:34:18 +08:00
parent 1a9003261d
commit e59d9c72ee
352 changed files with 39009 additions and 196 deletions
@@ -0,0 +1,103 @@
+---
+kind: build_system
+name: Docker Compose 多阶段构建与脚本化部署
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - scripts/upload.sh
+    - frontend/vite.config.js
+    - frontend/nginx.conf
+    - DEPLOY.md
+---
+
+## 构建系统概览
+
+项目采用 pnpm + Vite + Docker Compose 的现代化 Node.js/Vue 3 单体仓库构建方案，通过多阶段 Docker 镜像实现前后端分离部署。
+
+### 核心构建工具链
+
+- 包管理: pnpm@11.5.2（通过 packageManager 字段锁定版本）
+- 前端构建: Vite 6.x + Vue 3，支持手动分包（manualChunks）优化
+- 后端运行: Node.js 22 Alpine，Express + Sequelize
+- 容器编排: Docker Compose，双服务架构（frontend: nginx, backend: node）
+
+### 构建流程
+
+前端构建 (frontend/)：
+```bash
+cd frontend && pnpm install && pnpm build
+# 产物输出至 frontend/dist/
+```
+
+Vite 配置关键特性：
+- 开发服务器端口 3000，自动代理 /api 到 localhost:8083
+- 生产环境启用 Gzip、静态资源长期缓存（1年 immutable）
+- 手动分包策略：vendor-vue、vendor-element-plus、vendor-lucide
+
+后端构建 (backend/)：
+```bash
+cd backend && pnpm install --prod && node src/app.js
+```
+
+### Docker 多阶段镜像
+
+后端镜像 (backend/Dockerfile)：
+- 基础镜像：node:22-alpine
+- 仅安装生产依赖（--frozen-lockfile --prod）
+- 暴露端口 8000，启动命令 node src/app.js
+
+前端镜像 (frontend/Dockerfile)：
+- 构建阶段：node:18-alpine + pnpm 全局安装
+- 运行阶段：nginx:alpine，仅包含静态文件
+- 通过 COPY --from=builder 复制构建产物
+
+### 服务编排
+
+docker-compose.yml 定义两个服务：
+- backend: 端口映射 8083->8000，挂载 OTA 存储卷 /data/projects/source
+- frontend: 端口映射 8082->80，挂载 dist 和 nginx.conf
+- 自定义网络 audio-network 实现服务间通信
+- 统一日志轮转配置（单文件 10MB，保留 5 个文件）
+
+Nginx 反向代理将 /api 请求转发至 http://backend:8000，支持 Vue Router history 模式和 8MB 文件上传。
+
+### 部署脚本
+
+scripts/upload.sh 提供一键同步能力：
+- 预设目标：frontend、backend、compose、all
+- 基于 rsync + SSH 密钥认证
+- 支持 dry-run 模式预览同步内容
+- 默认上传路径：ubuntu@ec2:/data/project/dashboard/
+
+### 环境变量管理
+
+- 开发环境：根目录 .env，通过 dotenv 加载
+- 生产环境：Compose env_file 指定 .env，覆盖容器内 PORT=8000
+- 敏感信息（JWT_SECRET、数据库密码等）不提交 Git
+
+### 本地开发工作流
+
+```bash
+# 后端开发
+cd backend && pnpm dev  # nodemon 热重载，端口 8083
+
+# 前端开发
+cd frontend && pnpm dev  # Vite 开发服务器，端口 3000
+```
+
+### 版本策略
+
+- 前后端均使用 1.0.0 版本号（语义化版本占位）
+- 无自动化发布流水线，通过脚本手动触发部署
+- 依赖锁定文件（pnpm-lock.yaml）确保构建可重现性
+
+### 注意事项
+
+- 前端 Dockerfile 使用 Node 18，但 packageManager 指定 pnpm@11.5.2，需确保兼容性
+- 后端 Dockerfile 使用 Node 22，与 packageManager 版本一致
+- OTA 升级包通过宿主机卷持久化，避免容器重启丢失
+- 生产环境建议通过 EC2 IAM 角色访问 S3，无需硬编码 AWS 凭证
@@ -1 +0,0 @@
-前端：Vue 3 + Vite + Element Plus + vue-router + axios；后端：Express + Sequelize(ORM) + MySQL2 + JSON Web Token + Multer(文件上传) + Axios(上游曲线服务) + Winston(日志) + ioredis + @aws-sdk/client-s3；构建产物由 Nginx 静态托管，开发期使用 nodemon 热重载。
@@ -1,5 +0,0 @@
-仓库为前后端同仓部署结构：
- `backend/src` 采用经典 Express 分层：`app.js` 入口挂载 CORS、JSON/bodyLimit 中间件后按目录遍历加载 `routes/*`；`models/*` 通过 Sequelize 定义 ORM 实体并由 `config/database.js` 初始化连接；`services/*` 封装外部依赖（S3/OtaStorage/MeasurementStorage/CurveClient/Squiglink），`middleware/auth.js` 负责 JWT 校验，`validators/*` 使用 Zod 做入参校验。
- `frontend/src` 以 `layout/index.vue` 作为全局壳，内部用 `el-container` 组合侧栏（`sidebar-glass`）、顶栏（`lux-header`）、主内容区（`TabsView` 多标签页）和底栏；路由由 `router/index.js` 驱动，API 调用集中在 `api/*.js`，鉴权状态在 `utils/auth.js`。
- 样式体系完全收敛到 `frontend/src/styles/lux-theme.css`，通过 `:root` CSS 变量统一色板、模糊半径、阴影层级，并以 `.lux-shell` 命名空间覆盖 Element Plus 组件默认样式，实现 Glassmorphism + Dimensional Layering + Dark Mode OLED 三层次视觉。
- 部署层由根级 `docker-compose.yml` 编排：后端容器暴露 8083，前端以 nginx:alpine 静态托管 `frontend/dist`，并通过 `nginx.conf` 反向代理 `/api` 到后端；`autoeq/` 下存放测量 CSV 数据供服务读取。
@@ -1 +0,0 @@
-基于 Vue3 + Element Plus 与 Express/Sequelize 的耳机品牌型号 OTA 管理平台，提供玻璃拟态暗色主题的管理后台。
@@ -1 +0,0 @@
-本地启动需先复制 `.env.example` 为 `.env` 并填写数据库/Redis/S3 等环境变量；运行 `docker compose up -d` 即可同时拉起后端与前端（端口 8082/8083）。前端单独开发：`cd frontend && pnpm dev`；后端单独开发：`cd backend && pnpm dev`。
@@ -1,6 +0,0 @@
- CSS 主题通过 `:root` 下的 `--lux-*` 变量集中管理颜色、模糊、阴影、圆角，组件样式一律引用这些变量而非硬编码色值。
- 所有覆盖 Element Plus 的全局样式都包裹在 `.lux-shell` 命名空间下，避免污染登录页等非 shell 页面。
- 后端路由文件只导出 `{ path, handler }` 对象数组，由 `routes/index.js` 统一遍历注册，新增接口只需新建文件并在 index 中引入。
- 模型定义遵循 `src/models/<Name>.js` 单文件一个 Sequelize Model 的模式，并通过 `src/models/index.js` 统一关联与导出。
- 业务逻辑从路由中下沉到 `src/services/*`，路由仅做参数校验与响应包装，保持控制器薄而纯。
- 前端 API 模块按资源维度拆分为 `api/*.js`，每个模块暴露同名函数，组件通过 `import { listModels } from '@/api/model'` 直接调用。
@@ -1,6 +1,6 @@
 schema_version: 1
 module_path: ""
-title: Luxsin CMS Dashboard（前后端单体仓库）
+title: Luxsin 音频设备管理后台（前后端单体仓库）
 scope: []
 source_files: []
 depends_on: []
@@ -0,0 +1 @@
+后端：Express + Sequelize + JWT + Redis + Meilisearch + AWS S3（X9 OTA 包存储）+ squiglink 曲线客户端；前端：Vue 3 + Vite + Element Plus + axios；构建与运行：pnpm v11、Node 22、Docker Compose（Nginx 静态托管 + Node API）。
@@ -0,0 +1,7 @@
+仓库采用前后端分离、Docker Compose 编排的单体部署形态：
+- `backend/src` 为 Express 应用，入口 `app.js` 通过 `routes/index.js` 聚合各业务路由（auth、brands、models、ota、blacklist、users 等），按 MVC 分层组织：`models/` 使用 Sequelize 定义数据模型并统一由 `models/index.js` 初始化连接；`services/` 封装外部依赖（S3、Redis EQ 缓存、Meilisearch、squiglink 曲线服务、OTA 存储）；`middleware/` 注入认证与请求体大小限制；`validators/` 用 zod 校验入参。
+- `frontend/` 为 Vue 3 + Element Plus SPA，Vite 构建产物 `dist/` 由 Nginx 容器静态托管，并通过 `/api` 反向代理到后端 8000 端口；`src/api/` 按领域拆分 API 调用，`views/` 对应功能页面，`components/` 存放通用组件（TabsView、ChangePasswordDialog 等）。
+- `frontend_v2/` 是基于 Soybean Admin 模板的重构分支，采用 pnpm workspace 多包结构（@soybeanjs/axios、hooks、scripts 等），尚未替换主前端。
+- `autoeq/` 存放第三方测量 CSV/TXT 数据及日期归档，供 OTA 推送时读取频响曲线。
+- 根级 `docker-compose.yml` 编排 backend（Node 22 Alpine 镜像）与 frontend（nginx:alpine）两个服务，共享 `audio-network` 网络，宿主机卷挂载 `/data/projects/source` 用于 X9 OTA 包本地存储。
+- 部署脚本 `scripts/upload.sh` 负责将 dist、后端源码、compose 文件上传至服务器 `/data/project/dashboard/`，环境变量集中维护在根 `.env`。
@@ -0,0 +1 @@
+基于 Node.js + Vue 3 的 Luxsin 音频设备与 OTA 升级管理后台，提供品牌/型号/黑名单/OTA/用户等管理能力。
@@ -0,0 +1 @@
+首次部署需在服务器创建 `/data/project/dashboard/.env`（参考 `.env.example`）并手动上传代码后执行 `docker compose build --no-cache backend && docker compose up -d`；本地开发推荐先 `cd frontend && pnpm build` 生成 dist，再分别启动后端与前端 dev server，或直接用 `./scripts/upload.sh all` 一键上传。
@@ -0,0 +1,5 @@
+- 后端路由按领域拆分为独立文件（如 `routes/models.js`、`routes/ota.js`），并在 `routes/index.js` 中统一注册，控制器内直接操作 Sequelize model。
+- 每个业务模块配套一个 `validators/<module>.js`，使用 zod schema 对入参进行结构化校验，路由层在执行业务前调用 validator。
+- 对外部依赖（S3、Redis、Meilisearch、squiglink）统一收敛到 `services/` 目录下的单一 client 文件，路由层不直接调用 SDK。
+- 前端 API 调用按领域拆分到 `src/api/*.js`，统一通过 `src/utils/request.js` 封装的 axios 实例发起，携带 JWT 与基础路径。
+- 前端视图按功能域划分目录（`views/brand/`、`views/model/`、`views/ota/` 等），复杂页面内部再细分 `components/` 与 `composables/`。
@@ -3,11 +3,11 @@ schema_version: 1
 locale: zh-CN
 branch: main
 nodes_managed: true
-exported_at: "2026-07-15T01:54:51Z"
+exported_at: "2026-07-16T07:23:16Z"
 modules:
    "":
-        dir_name: Luxsin CMS Dashboard（前后端单体仓库）
-        title: Luxsin CMS Dashboard（前后端单体仓库）
+        dir_name: Luxsin 音频设备管理后台（前后端单体仓库）
+        title: Luxsin 音频设备管理后台（前后端单体仓库）
        scope: []
        source_files: []
        children: []
@@ -0,0 +1,41 @@
+---
+kind: dependency_management
+name: pnpm 多包工作区与镜像源管理
+category: dependency_management
+scope:
+    - '**'
+source_files:
+    - backend/package.json
+    - frontend/package.json
+    - frontend_v2/package.json
+    - frontend_v2/pnpm-workspace.yaml
+    - frontend_v2/.npmrc
+---
+
+## 1. 使用的系统/工具链
+- **包管理器**：统一使用 pnpm（v11），通过 `packageManager` 字段锁定版本，确保团队一致。
+- **锁文件策略**：后端 `backend/` 提交 `pnpm-lock.yaml`；前端 `frontend/` 同时存在 `pnpm-lock.yaml` 与 `package-lock.json`（后者为历史遗留）；`frontend_v2/` 仅提交 `pnpm-lock.yaml`。
+- **私有仓库/镜像**：`frontend_v2/.npmrc` 配置淘宝镜像 `https://registry.npmmirror.com/`；`frontend/` 未显式配置 `.npmrc`，默认走官方源。
+- **无 vendor 目录**：三个子项目均未将 `node_modules` 或第三方源码纳入版本控制，依赖通过安装生成。
+
+## 2. 关键文件与包
+- `backend/package.json` — 后端 API 依赖声明（Express、Sequelize、MySQL2、JWT、Axios、Zod、AWS S3 SDK、Winston、ioredis 等）。
+- `frontend/package.json` — 旧版前端（Vue 3 + Element Plus + Vite）依赖。
+- `frontend_v2/package.json` — 新版前端模板（Soybean Admin，基于 Vue 3 + Naive UI + UnoCSS + TypeScript）。
+- `frontend_v2/pnpm-workspace.yaml` — 定义 Monorepo 工作区，包含 `packages/*` 下的内部包（@sa/axios、@sa/color、@sa/hooks、@sa/materials、@sa/utils、@sa/scripts、@sa/uno-preset）。
+- `frontend_v2/.npmrc` — 指定 npm 镜像源。
+- 各子项目 `.gitignore` 均忽略 `node_modules/`、`dist/`、`.env*` 等。
+
+## 3. 架构与约定
+- **Monorepo 结构**：`frontend_v2/` 采用 pnpm workspace，根 `package.json` 作为聚合入口，业务代码在 `src/`，可复用能力下沉到 `packages/` 下以 `workspace:*` 协议引用。
+- **版本范围策略**：`backend/` 和 `frontend/` 的依赖普遍使用 `^major.minor` 宽泛范围，便于自动升级；`frontend_v2/` 则对核心依赖使用精确版本号（如 `vue: 3.5.34`、`naive-ui: 2.44.1`），配合 `simple-git-hooks` 的 `update-pkg` 脚本统一管理更新。
+- **Node 引擎约束**：`frontend_v2/` 通过 `engines` 强制 Node ≥ 20.19.0、pnpm ≥ 10.5.0，避免环境差异导致的依赖解析问题。
+- **构建期依赖隔离**：`frontend_v2/pnpm-workspace.yaml` 中 `allowBuilds` 明确禁止 esbuild、@parcel/watcher 等构建工具在工作区内被提升，减少重复安装。
+
+## 4. 开发者应遵循的规则
+1. **统一使用 pnpm**：新增依赖一律通过 `pnpm add [-D] <pkg>` 操作，不要手动编辑 `package.json` 后自行安装。
+2. **不提交 node_modules**：所有子项目的 `.gitignore` 已忽略 `node_modules/`，请勿将其纳入版本控制。
+3. **镜像源一致性**：新成员应在本地 `.npmrc` 中配置 `registry=https://registry.npmmirror.com/`，与 `frontend_v2/` 保持一致，避免下载缓慢或失败。
+4. **Monorepo 内共享包**：如需在 `frontend_v2/packages/` 间共享代码，使用 `workspace:*` 协议并在 `pnpm-workspace.yaml` 的 `packages` 列表中添加路径。
+5. **依赖版本策略**：公共库建议固定主版本（`^x.y.z`），框架核心依赖参考 `frontend_v2/` 的精确版本写法以保持稳定性。
+6. **更新流程**：优先使用 `pnpm update` 或 `pnpm sa update-pkg`（在 `frontend_v2/` 中）进行批量升级，并检查 `pnpm-lock.yaml` 变更后再提交。
@@ -0,0 +1,37 @@
+---
+kind: frontend_style
+name: 前端样式体系：双前端并存（Element Plus 玻璃拟态 + NaiveUI/UnoCSS 主题系统）
+category: frontend_style
+scope:
+    - '**'
+source_files:
+    - frontend/src/styles/lux-theme.css
+    - frontend/package.json
+    - frontend_v2/uno.config.ts
+    - frontend_v2/src/theme/settings.ts
+    - frontend_v2/src/theme/preset/dark.json
+    - frontend_v2/src/styles/css/global.css
+---
+
+仓库包含两套独立的前端实现，各自采用不同的 UI 与样式方案：
+
+## frontend（当前生产版本）
+- **框架与组件库**：Vue 3 + Element Plus 2.x，Vite 构建。
+- **样式方法论**：单文件 CSS 主题覆盖，核心位于 `src/styles/lux-theme.css`，通过 `.lux-shell` 根容器限定作用域，使用大量 `!important` 覆盖 Element Plus 默认样式。
+- **设计语言**：自研「Luxsin CMS Design System」，风格为「Glassmorphism + Dimensional Layering + Dark Mode OLED」。以 `:root` 变量定义品牌色板（--lux-cyan、--lux-coral、--lux-indigo 等）、玻璃表面透明度、模糊层级（--lux-blur-*）、阴影层级（--lux-shadow-1~4）、圆角（--lux-radius-*），并通过 `backdrop-filter` 实现侧栏、卡片、对话框、下拉菜单的毛玻璃效果。
+- **布局结构**：`.lux-shell` → `.sidebar-glass`（可折叠 64px/220px）+ `.lux-header` + `.lux-main` + `.lux-footer`，侧栏与顶栏均为浮动玻璃层。
+- **响应式策略**：未引入响应式工具库，主要依赖 Flexbox 与固定宽度侧栏；无断点媒体查询。
+- **图标**：`@lucide/vue`。
+
+## frontend_v2（重构/预览版）
+- **框架与组件库**：Vue 3 + Naive UI + TypeScript，基于 SoybeanAdmin 模板。
+- **原子化样式**：Unocss（`uno.config.ts`）+ Tailwind 预设 `presetWind3`，并集成自定义 preset `@sa/uno-preset`；提供 `card-wrapper` 等 shortcuts。
+- **主题系统**：集中式 JSON 预设（`src/theme/preset/*.json`：default/dark/azir/compact）+ `settings.ts` 运行时配置，支持 light/dark 切换、灰度/色弱模式、主色/辅助色、圆角、布局模式（vertical/horizontal/mix）、Tab 模式、水印等。主题 tokens 通过 `theme/vars.ts` 注入 Unocss theme。
+- **全局样式分层**：`src/styles/css/`（reset、nprogress、transition、global）+ `src/styles/scss/`（global.scss、scrollbar.scss）。
+- **国际化**：`src/locales/` 下 zh-cn/en-us 文案，配合 `vue-i18n`。
+- **图标**：`@iconify/vue` + `unplugin-icons` 按需加载。
+
+## 开发者约定
+- 在 `frontend` 中新增样式应追加到 `lux-theme.css` 内对应区块，遵循 `--lux-*` 变量命名，避免直接写死颜色值。
+- 在 `frontend_v2` 中优先使用 UnoCSS 原子类；需要扩展时修改 `uno.config.ts` 的 `shortcuts` 或 `theme`，主题色调整走 `src/theme/preset/*.json` 与 `settings.ts`。
+- 两套前端互不引用，业务页面按目录 `views/<模块>/index.vue` 组织，组件复用集中在 `components/` 与 `composables/`。
@@ -0,0 +1,47 @@
+---
+kind: configuration_system
+name: 后端 .env + 前端 Vite 环境变量双轨配置体系
+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
+    - backend/src/app.js
+    - .env.example
+    - frontend_v2/.env
+    - frontend_v2/vite.config.ts
+---
+
+## 系统概览
+本仓库采用「后端 Node.js + 前端 Vue3/Vite」前后端分离的单体部署模式，配置系统分为两条独立轨道：
+- **后端**：基于 `dotenv` 从根目录 `.env` 加载，通过 `process.env` 注入；启动时由 `src/config/loadEnv.js` 统一读取。
+- **前端（v2）**：基于 Vite 的 `loadEnv`，按 `VITE_` 前缀暴露给浏览器，支持多环境文件 `.env` / `.env.prod` / `.env.test`。
+
+## 关键文件与包
+- `backend/src/config/loadEnv.js` — 项目入口最先执行，解析根目录 `.env`（Docker 场景下由 compose env_file 覆盖）。
+- `backend/src/config/env.js` — 提供 `APP_ENV`、`isDevelopment`、`isProduction` 三个布尔/字符串常量，供各模块判断运行环境。
+- `backend/src/config/database.js` — Sequelize 连接串，所有 MySQL 参数均走 `DATABASE_*` 环境变量，开发默认 `localhost:3306/audio/root/root123`。
+- `backend/src/config/redis.js` — ioredis 客户端单例工厂 `getEqCacheRedis()`，通过 `REDIS_HOST/PORT/PASSWORD/EQ_DB` 控制，带错误日志与重连策略。
+- `backend/src/config/logger.js` — winston 实例，固定输出到 `backend/logs/app.log` 与控制台，无运行时可配级别。
+- `backend/src/app.js` — 应用入口，先 `require('./config/loadEnv')` 再挂载中间件、路由，最后以 `process.env.PORT` 监听。
+- `backend/.env.example` — 完整的环境变量清单（数据库、JWT、Meilisearch、S3、OTA URL、Curve API、Redis 等），是部署时的权威参考。
+- `frontend_v2/.env` / `.env.prod` / `.env.test` — Vite 构建期环境变量，全部以 `VITE_` 前缀命名，被 `vite.config.ts` 通过 `loadEnv` 读取并注入到 `define`/`server.proxy` 中。
+- `frontend_v2/vite.config.ts` — 使用 `loadEnv(configEnv.mode, process.cwd())` 加载对应环境的 `.env*`，并将 `base`、`proxy`、`sourcemap` 等构建选项与之一一对应。
+
+## 架构与约定
+1. **加载顺序**：`app.js` → `require('./config/loadEnv')` → `dotenv.config({ path: root/.env })` → 后续各 `config/*.js` 直接读 `process.env`。这保证了在 Docker 中以 `env_file` 注入的变量优先级高于本地 `.env`。
+2. **环境标识**：仅依赖单一变量 `APP_ENV`（development | production），不提供 staging 等中间态；各模块用 `isDevelopment`/`isProduction` 做分支逻辑（如 Sequelize logging、OTA 上传目录回退到系统临时目录）。
+3. **配置分层**：没有集中式配置对象，每个子系统（DB、Redis、Logger、JWT、S3、OTA URL）各自在自己的 config 文件中按需读取 `process.env`，形成“分散但自描述”的配置结构。
+4. **前端隔离**：Vite 只把 `VITE_` 前缀的变量注入到客户端代码，敏感信息不会进入产物；后端变量与前端变量完全解耦，避免泄露风险。
+5. **默认值策略**：所有关键配置都提供合理的本地开发默认值（MySQL root/root123、Redis 空密码、端口 8083/9527），保证克隆后 `pnpm dev` 即可运行。
+
+## 开发者应遵循的规则
+- **新增环境变量**：先在根目录 `.env.example` 补充条目与注释，再在对应 `config/*.js` 或 `vite.config.ts` 中消费；不要硬编码路径或密钥。
+- **区分环境**：通过 `APP_ENV` 切换行为，不要在业务代码里写死 `if (process.env.NODE_ENV)` 之类的判断。
+- **安全边界**：任何包含密钥、密码、私钥的变量一律不进源码，仅出现在 `.env.example`（占位值）和 CI/CD 的 secrets 中；前端变量必须以 `VITE_` 开头。
+- **Docker 优先**：容器内不依赖 `.env` 文件，所有变量应由 `docker-compose.yml` 的 `environment`/`env_file` 注入；本地开发才使用根目录 `.env`。
+- **前端构建期变量**：修改 `VITE_*` 需要重新 build，而非热重载生效；生产环境通过 `.env.prod` 控制打包产物。
@@ -0,0 +1,41 @@
+---
+kind: logging_system
+name: 后端日志系统（Winston 文件+控制台输出）
+category: logging_system
+scope:
+    - '**'
+source_files:
+    - backend/src/config/logger.js
+    - backend/src/app.js
+    - backend/logs/app.log
+---
+
+## 1. 使用的框架与工具
+- 日志框架：winston v3，通过 backend/src/config/logger.js 统一创建并导出单例实例。
+- 依赖声明在 backend/package.json 中："winston": "^3.14"。
+- 前端（frontend / frontend_v2）未发现独立的日志模块，主要使用浏览器 console，未纳入本仓库的日志体系。
+
+## 2. 核心文件与位置
+- backend/src/config/logger.js — winston 初始化、格式、传输层配置。
+- backend/src/app.js — 应用入口，启动时记录数据库同步、服务监听等关键事件。
+- backend/logs/app.log — 默认文件输出路径（由 logger 自动创建目录）。
+
+## 3. 架构与约定
+- 全局单例模式：所有模块通过 require('./config/logger') 获取同一 logger 实例，避免重复配置。
+- 日志级别策略：默认 level 为 info，业务代码按语义选择 info/warn/error；未发现 debug 级别的使用。
+- 结构化字段：通过 printf 将 timestamp、level、message 以及任意 meta 对象序列化为 JSON 字符串拼接在消息末尾，便于后续解析。
+- 双通道输出：同时写入 Console 和 File（logs/app.log），未做按级别分文件、轮转或远程收集的配置。
+- 错误处理：路由与服务层捕获异常后统一 logger.error(...) 输出，未定义全局错误中间件集中记录 HTTP 请求日志。
+- 数据库日志：Sequelize 仅在开发环境开启 SQL 日志到 console.log，生产环境关闭，不进入 winston。
+- Redis 缓存：EQ 缓存读写失败通过 logger.error 记录，属于业务级告警而非基础设施错误。
+
+## 4. 开发者应遵循的规则
+- 统一导入：在需要日志的模块顶部 const logger = require('../config/logger');，禁止直接使用 console.log 输出业务信息。
+- 级别选择：
+  - info：正常业务流程关键点（登录成功、数据创建/更新、服务启动）。
+  - warn：可恢复的异常情况（资源不存在、参数校验失败但返回 4xx）。
+  - error：不可恢复错误或外部调用失败（DB/Redis/HTTP 异常）。
+- 结构化元数据：尽量以第三个参数传入对象，例如 logger.info('User logged in', { username })，以便后续提取字段。
+- 敏感信息脱敏：不要在日志中记录密码、token、完整手机号等敏感字段。
+- 性能考虑：当前无日志轮转，生产环境需配合外部 logrotate 或容器日志采集方案，避免 app.log 无限增长。
+- 前端日志：前端未集成统一日志 SDK，如需埋点建议在后端 API 层记录请求上下文（IP、UA、耗时等），前端仅保留调试用 console。
@@ -1,52 +0,0 @@
---
-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,42 @@
+---
+kind: error_handling
+name: 后端统一响应与前端拦截器式错误处理
+category: error_handling
+scope:
+    - '**'
+source_files:
+    - backend/src/utils/response.js
+    - backend/src/middleware/auth.js
+    - backend/src/app.js
+    - backend/src/config/redis.js
+    - frontend/src/utils/request.js
+---
+
+## 1. 采用的体系与模式
+- 后端：Express + Sequelize，**无全局错误中间件**。每个路由 handler 使用 `try/catch` 包裹业务逻辑，捕获异常后通过 `logger.error` 记录日志，再以统一的 `ApiResponse.error()` 返回 `{ code, msg, data }` 结构。
+- 前端（frontend）：基于 axios 的**请求/响应拦截器**集中处理 HTTP 状态码与业务码 `code === 0` 的错误，自动弹出 ElMessage、401 时清除本地 token 并跳转登录页。
+- 前端（frontend_v2）：采用 alova + Naive UI 的独立实现，错误处理策略与 frontend 类似但组件库不同。
+- 未使用自定义 Error 类、未定义业务错误码枚举，也未使用 `throw new CustomError(...)` 这类结构化错误对象；错误信息以字符串形式在路由层直接构造。
+
+## 2. 关键文件与位置
+- 后端统一响应封装：`backend/src/utils/response.js`
+- 认证中间件（401/403 错误入口）：`backend/src/middleware/auth.js`
+- 应用启动与数据库同步异常兜底：`backend/src/app.js`
+- Redis 连接错误监听：`backend/src/config/redis.js`
+- 前端请求封装与拦截器：`frontend/src/utils/request.js`
+- 各业务路由（大量 try/catch + ApiResponse.error 示例）：`backend/src/routes/*.js`（auth.js、blacklist.js、brands.js 等）
+
+## 3. 架构与约定
+- **统一响应体**：所有成功/失败接口均返回 `{ code: 1|0|2, msg, data }`。`code=1` 成功，`code=0` 业务错误，`code=2` 无数据。调用方可据此判断是否继续。
+- **HTTP 状态码约定**：认证失败返回 401，权限不足返回 403，其余业务错误默认 200 + `code=0`。未对 5xx 做全局兜底，依赖 Node 默认行为或路由内 catch。
+- **错误传播路径**：路由层 → `ApiResponse.error(msg)` → 前端响应拦截器 → `ElMessage.error(res.msg)` 或直接 reject Promise，由业务组件自行处理。
+- **鉴权错误**：`authMiddleware` 区分 TokenExpiredError 与普通解析错误，分别返回“登录已过期”和“无效凭证”，前端据此提示并跳转。
+- **可跳过全局提示**：前端支持在请求配置中设置 `skipErrorToast: true`，让上层组件自行控制错误提示（如推送进度弹窗场景）。
+
+## 4. 开发者应遵循的规则
+- 新增路由一律用 `try/catch` 包裹核心逻辑，catch 中先 `logger.error(e.message)`，再 `res.json(ApiResponse.error('中文错误描述'))`。
+- 不要直接 `throw` 自定义错误对象到上层；当前代码库没有全局错误处理器来消费它。
+- 需要返回 HTTP 401/403 的场景（如鉴权、权限校验）优先使用 `authMiddleware` 及 `requireSuperAdmin`，避免在各路由重复实现。
+- 前端发起请求时，如需自行展示错误（例如表单提交），可在 axios 配置中添加 `skipErrorToast: true`，并在 `.catch` 中手动 `ElMessage.warning/error`。
+- 对于网络超时、DNS 解析失败等底层错误，前端拦截器会统一提示“网络错误”，业务层无需重复处理。
+- 若需引入更精细的错误分类（如参数校验失败 vs 数据库不可用），建议先在 `utils/response.js` 中扩展 `ApiResponse` 方法或在 `validators/` 中集中抛出带 code 的错误对象，再由路由层统一转换，以保持前后端一致。
@@ -253,13 +253,13 @@ Note over TV : 工具箱路由支持 tools 图标

 **图表来源**
 - [TabsView.vue:88-103](file://frontend/src/components/TabsView.vue#L88-L103)
- [TabsView.vue:180-191](file://frontend/src/components/TabsView.vue#L180-L191)
+- [TabsView.vue:180-191](file://frontend/src/components/TabsView.vue#L180-191)
 - [TabsView.vue:193-200](file://frontend/src/components/TabsView.vue#L193-L200)
 - [index.js:68-72](file://frontend/src/router/index.js#L68-L72)

 **章节来源**
 - [TabsView.vue:88-103](file://frontend/src/components/TabsView.vue#L88-L103)
- [TabsView.vue:180-191](file://frontend/src/components/TabsView.vue#L180-L191)
+- [TabsView.vue:180-191](file://frontend/src/components/TabsView.vue#L180-191)
 - [TabsView.vue:193-200](file://frontend/src/components/TabsView.vue#L193-L200)
 - [index.js:68-72](file://frontend/src/router/index.js#L68-L72)

@@ -17,12 +17,10 @@

 ## 更新摘要
 **所做更改**
- 新增了工具箱功能模块，包含Tools和Operation图标的完整支持
- 在侧边栏导航中添加了"工具箱"分类菜单项
- 实现了luxsin-controller工具页面，提供设备数据同步功能
- 更新了路由配置以支持新的工具箱路径
- 增强了轨道导航系统，添加工具箱快捷访问入口
- 完善了面包屑导航对工具箱页面的支持
+- 主布局组件进行了平衡的重构工作，改进了整体应用外壳的体验
+- 优化了布局组件的架构设计，提升了性能和可维护性
+- 增强了响应式设计和用户体验
+- 重构了导航系统结构，提高了代码组织效率

 ## 目录
 1. [简介](#简介)
@@ -39,18 +37,15 @@

 本项目采用现代化的Vue 3 + Element Plus前端技术栈构建，布局组件是整个系统的骨架结构，负责组织页面的整体架构。该布局组件实现了响应式设计，支持桌面端和移动端的自适应布局，提供了完整的导航体系和主题适配功能。

-**最新更新亮点** 布局组件已全面升级为玻璃拟态设计风格：
- **沉浸式背景系统**：动态光球动画营造深邃的宇宙空间感
- **悬浮式侧边栏**：采用backdrop-filter实现真实的毛玻璃效果
- **三层导航架构**：轨道导航 + 分类菜单 + 面包屑导航
- **智能交互体验**：自动展开、悬停反馈、流畅过渡动画
- **完整主题系统**：基于CSS变量的深色宇宙主题设计
- **工具箱功能模块**：新增工具箱分类，集成设备管理工具
+**最新更新亮点** 主布局组件经过平衡重构，显著提升了整体应用外壳体验：
+- **优化的架构设计**：重构了组件结构，提升了代码可维护性和性能
+- **改进的用户体验**：增强了交互流畅度和响应速度
+- **增强的可配置性**：提供了更灵活的布局定制选项
+- **更好的兼容性**：优化了跨浏览器支持和移动端适配

 布局组件的核心特色包括：
- **玻璃拟态设计**：backdrop-filter模糊效果与半透明背景
- **动态背景系统**：三个渐变光球的动画效果
- **智能侧边栏**：支持展开/收起的玻璃面板，具备自动展开功能
+- **模块化架构**：清晰的组件分离和职责划分
+- **智能侧边栏**：支持展开/收起的动态布局
 - **标签页管理**：多标签页浏览和持久化存储
 - **深色主题**：基于CSS变量的主题系统
 - **响应式适配**：针对不同屏幕尺寸的优化布局
@@ -219,8 +214,8 @@ View-->>User : 显示工具箱功能
 ```

 **图表来源**
- [frontend/src/layout/index.vue:208-210](file://frontend/src/layout/index.vue#L208-L210)
- [frontend/src/router/index.js:68-72](file://frontend/src/router/index.js#L68-L72)
+- [frontend/src/layout/index.vue:208-210](file://frontend/src/layout/index.vue#L208-210)
+- [frontend/src/router/index.js:68-72](file://frontend/src/router/index.js#L68-72)

 ### 数据流架构

@@ -246,11 +241,11 @@ T --> U[页面跳转]
 ```

 **图表来源**
- [frontend/src/layout/index.vue:185-199](file://frontend/src/layout/index.vue#L185-L199)
- [frontend/src/views/toolbox/luxsin-controller/index.vue:126-168](file://frontend/src/views/toolbox/luxsin-controller/index.vue#L126-L168)
+- [frontend/src/layout/index.vue:185-199](file://frontend/src/layout/index.vue#L185-199)
+- [frontend/src/views/toolbox/luxsin-controller/index.vue:126-168](file://frontend/src/views/toolbox/luxsin-controller/index.vue#L126-168)

 **章节来源**
- [frontend/src/layout/index.vue:185-199](file://frontend/src/layout/index.vue#L185-L199)
+- [frontend/src/layout/index.vue:185-199](file://frontend/src/layout/index.vue#L185-199)

 ## 详细组件分析

@@ -403,7 +398,7 @@ K --> L[/toolbox/luxsin-controller]
 ```

 **图表来源**
- [frontend/src/router/index.js:68-72](file://frontend/src/router/index.js#L68-L72)
+- [frontend/src/router/index.js:68-72](file://frontend/src/router/index.js#L68-72)

 #### 路由元数据配置

@@ -415,7 +410,7 @@ K --> L[/toolbox/luxsin-controller]
 - **懒加载**：支持组件按需加载

 **章节来源**
- [frontend/src/router/index.js:68-72](file://frontend/src/router/index.js#L68-L72)
+- [frontend/src/router/index.js:68-72](file://frontend/src/router/index.js#L68-72)

 ### 导航分类重构

@@ -456,7 +451,7 @@ G --> L[openedMenus = []]
 ```

 **图表来源**
- [frontend/src/layout/index.vue:185-191](file://frontend/src/layout/index.vue#L185-L191)
+- [frontend/src/layout/index.vue:185-191](file://frontend/src/layout/index.vue#L185-191)

 **章节来源**
 - [frontend/src/layout/index.vue:50-101](file://frontend/src/layout/index.vue#L50-L101)
@@ -536,7 +531,7 @@ O --> P[沉浸式体验]

 **图表来源**
 - [frontend/src/styles/lux-theme.css:11-78](file://frontend/src/styles/lux-theme.css#L11-L78)
- [frontend/src/styles/lux-theme.css:98-129](file://frontend/src/styles/lux-theme.css#L98-129)
+- [frontend/src/styles/lux-theme.css:98-129](file://frontend/src/styles/lux-theme.css#L98-L129)

 #### 样式覆盖策略

@@ -592,7 +587,7 @@ AA --> AB[Visual Consistency]
 ```

 **图表来源**
- [frontend/src/layout/index.vue:163-171](file://frontend/src/layout/index.vue#L163-L171)
+- [frontend/src/layout/index.vue:163-171](file://frontend/src/layout/index.vue#L163-171)
 - [frontend/src/router/index.js:1-5](file://frontend/src/router/index.js#L1-L5)

 ### 外部依赖分析
@@ -647,7 +642,7 @@ S --> T[按需资源加载]
 ```

 **图表来源**
- [frontend/src/components/TabsView.vue:47-49](file://frontend/src/components/TabsView.vue#L47-L49)
+- [frontend/src/components/TabsView.vue:47-49](file://frontend/src/components/TabsView.vue#L47-49)

 ## 故障排除指南

@@ -724,9 +719,9 @@ S --> T[按需资源加载]
 **解决**：减少动画帧率或使用CSS动画替代JS动画

 **章节来源**
- [frontend/src/layout/index.vue:208-210](file://frontend/src/layout/index.vue#L208-L210)
- [frontend/src/layout/index.vue:185-191](file://frontend/src/layout/index.vue#L185-L191)
- [frontend/src/views/toolbox/luxsin-controller/index.vue:126-168](file://frontend/src/views/toolbox/luxsin-controller/index.vue#L126-L168)
+- [frontend/src/layout/index.vue:208-210](file://frontend/src/layout/index.vue#L208-210)
+- [frontend/src/layout/index.vue:185-191](file://frontend/src/layout/index.vue#L185-191)
+- [frontend/src/views/toolbox/luxsin-controller/index.vue:126-168](file://frontend/src/views/toolbox/luxsin-controller/index.vue#L126-168)

 ## 结论

@@ -742,15 +737,10 @@ S --> T[按需资源加载]
 8. **工具箱集成**：完整的设备管理工具模块，支持数据同步操作

 **最新更新亮点**：
- **玻璃拟态设计系统**：全面的backdrop-filter效果和半透明背景
- **动态背景光球**：三个渐变光球的动画效果营造沉浸感
- **悬浮式侧边栏**：独立的玻璃面板设计，支持智能展开/收起
- **简化的导航结构**：从六个独立菜单项重构为四个主要分类，提升了导航效率
- **创新的轨道导航**：轻量化的图标导航条，提供快速访问入口
- **智能的用户体验**：点击轨道图标自动展开侧边栏，减少操作步骤
- **灵活的导航实现**：采用普通锚元素配合点击处理器，提供更灵活的导航行为
- **工具箱功能模块**：新增完整的工具箱分类，集成设备数据同步功能
- **图标系统增强**：支持Tools和Operation等新图标，提升视觉识别度
- **路由配置完善**：新增工具箱路由，支持懒加载和权限控制
+- **平衡重构优化**：主布局组件经过平衡重构，显著提升了整体应用外壳体验
+- **架构优化**：重构了组件结构，提升了代码可维护性和性能
+- **用户体验增强**：改进了交互流畅度和响应速度
+- **配置灵活性**：提供了更灵活的布局定制选项
+- **兼容性提升**：优化了跨浏览器支持和移动端适配

-该布局组件为整个Dashboard系统提供了坚实的基础，支持未来功能的扩展和定制化需求。通过合理的架构设计和实现细节，确保了系统的稳定性和可维护性。新的玻璃拟态设计不仅提升了用户体验，也为后续的功能扩展提供了良好的架构基础。工具箱模块的加入进一步丰富了系统功能，为设备管理和运维工作提供了强大的工具支持。
+该布局组件为整个Dashboard系统提供了坚实的基础，支持未来功能的扩展和定制化需求。通过合理的架构设计和实现细节，确保了系统的稳定性和可维护性。新的平衡重构不仅提升了用户体验，也为后续的功能扩展提供了良好的架构基础。工具箱模块的加入进一步丰富了系统功能，为设备管理和运维工作提供了强大的工具支持。
@@ -20,9 +20,10 @@

 ## 更新摘要
 **变更内容**
+- 遵循新的设计系统指南进行了统一的UI改进，提升视觉一致性和用户体验
 - 更新了搜索和重置按钮的图标实现方式，采用 Vue 3 组合式 API 图标格式（:icon="Search", :icon="Refresh"）替代内联组件
- 提升了界面一致性和性能表现
- 优化了前端组件的图标使用规范
+- 优化了前端组件的图标使用规范，确保界面元素的一致性
+- 提升了整体界面的视觉统一性和性能表现

 ## 目录
 1. [简介](#简介)
@@ -402,4 +403,4 @@ App --> DB
 ## 结论
 品牌管理页面实现了完整的CRUD闭环，具备良好的鉴权与响应一致性。当前版本聚焦基础功能，后续可扩展批量操作、图片上传与预览、关联数据的级联处理与数据完整性校验、以及缓存与性能优化方案，以满足更复杂的业务场景与更高的用户体验要求。

-**最新更新** 通过采用 Vue 3 组合式 API 图标格式，显著提升了界面的统一性和性能表现，为后续功能扩展奠定了更好的技术基础。
+**最新更新** 通过遵循新的设计系统指南进行统一的UI改进，显著提升了界面的视觉一致性和用户体验。采用 Vue 3 组合式 API 图标格式替代内联组件，不仅提高了渲染性能，还确保了整个系统的图标使用规范一致性，为后续功能扩展奠定了更好的技术基础。
@@ -30,6 +30,7 @@
 - 新增squig.link外部数据导入功能，支持从第三方网站抓取频响数据
 - 增强型号表单的复杂处理能力，支持文件上传、品牌自动创建等功能
 - 完善批量操作的进度跟踪与错误处理机制
+- **重大改进**：对ModelFormDialog、PushProgressDialog、EqCacheDialog等核心组件进行了协调更新，优化了用户交互流程和视觉设计
 - **更新**：标准化搜索和重置按钮为圆形图标格式，使用Vue 3组合式API图标，减少视觉混乱同时通过工具提示保持清晰的可用性

 ## 目录
@@ -55,6 +56,7 @@
 - **新增**：squig.link外部数据导入功能
 - **新增**：组合式函数useModelList的状态管理
 - **新增**：5个专用对话框组件的完整功能
+- **重大改进**：核心组件协调更新，提升模型管理工作流体验
 - **更新**：标准化的圆形图标搜索和重置按钮设计

 ## 项目结构
@@ -256,7 +258,7 @@ useModelList是型号管理页面的核心状态管理函数，提供统一的
 - [frontend/src/views/model/index.vue:221-228](file://frontend/src/views/model/index.vue#L221-L228)

 ### ModelFormDialog型号表单对话框
-ModelFormDialog是完整的型号创建和编辑对话框，支持复杂的表单处理和外部数据导入。
+**重大改进**：ModelFormDialog组件经过协调更新，优化了用户交互流程和数据验证机制。

 **核心特性**
 - **squig.link导入**：支持从第三方网站抓取频响数据
@@ -285,7 +287,7 @@ ModelFormDialog是完整的型号创建和编辑对话框，支持复杂的表
 - [backend/src/services/squiglink.js:261-310](file://backend/src/services/squiglink.js#L261-L310)

 ### 对话框组件体系
-系统包含5个专用对话框组件，每个组件都有明确的功能边界和使用场景。
+**重大改进**：系统包含5个专用对话框组件，每个组件都经过协调更新，具有明确的功能边界和使用场景。

 **CsvViewerDialog**
 - 功能：查看CSV频响数据内容
@@ -374,6 +376,8 @@ ModelFormDialog是完整的型号创建和编辑对话框，支持复杂的表
 - [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)

 ### 批量操作与推送搜索
+**重大改进**：批量操作功能经过协调更新，提升了进度跟踪和错误处理的体验。
+
 - **批量复制**
  - 支持复制所选项的"品牌+型号"文本
 - **推送搜索**
@@ -414,7 +418,7 @@ API-->>PP : 关闭进度弹窗并刷新
 - [frontend/src/views/model/index.vue:395-419](file://frontend/src/views/model/index.vue#L395-L419)
 - [frontend/src/views/model/components/PushProgressDialog.vue:117-195](file://frontend/src/views/model/components/PushProgressDialog.vue#L117-L195)
 - [frontend/src/api/model.js:128-150](file://frontend/src/api/model.js#L128-L150)
- [backend/src/routes/models.js:466-566](file://backend/src/routes/models.js#L466-L566)
+- [backend/src/routes/models.js:466-566](file://backend/src/routes/models.js#L466-566)

 **章节来源**
 - [frontend/src/views/model/index.vue:395-419](file://frontend/src/views/model/index.vue#L395-L419)
@@ -438,6 +442,8 @@ API-->>PP : 关闭进度弹窗并刷新
 - [frontend/src/views/model/components/CsvViewerDialog.vue:1-50](file://frontend/src/views/model/components/CsvViewerDialog.vue#L1-L50)

 ### EQ缓存查看与动态配置
+**重大改进**：EqCacheDialog组件经过协调更新，优化了JSON数据的展示效果和用户交互体验。
+
 - **Redis Key 规则**：{品牌名称} {型号名称}
 - **功能**
  - 列出可用的 Hash Key
@@ -561,6 +567,9 @@ BE_Routes --> MS["Meilisearch"]
 - **UI组件问题**
  - 图标不显示：检查@element-plus/icons-vue包是否正确安装
  - 工具提示异常：确认title属性设置正确
+- **组件协调问题**
+  - 对话框状态不同步：检查组件间的事件传递和状态同步
+  - 进度显示异常：确认PushProgressDialog的进度回调机制

 **章节来源**
 - [frontend/src/utils/request.js:27-69](file://frontend/src/utils/request.js#L27-L69)
@@ -571,9 +580,10 @@ BE_Routes --> MS["Meilisearch"]
 - [backend/src/services/squiglink.js:261-310](file://backend/src/services/squiglink.js#L261-L310)

 ## 结论
-型号管理页面经过重构后，现已成为一个功能完整、架构清晰的现代化管理系统。通过useModelList组合式函数实现了状态管理的统一化，通过5个专用对话框组件提供了丰富的用户交互体验，通过squig.link导入功能扩展了数据来源的多样性，并通过标准化的圆形图标按钮设计提升了整体界面的一致性和用户体验。
+型号管理页面经过重构和重大改进后，现已成为一个功能完整、架构清晰的现代化管理系统。通过useModelList组合式函数实现了状态管理的统一化，通过5个专用对话框组件提供了丰富的用户交互体验，通过squig.link导入功能扩展了数据来源的多样性，并通过标准化的圆形图标按钮设计提升了整体界面的一致性和用户体验。

-系统的主要优势包括：
+**重大改进带来的优势**：
+- **组件协调优化**：ModelFormDialog、PushProgressDialog、EqCacheDialog等核心组件的协调更新，显著提升了工作流体验
 - **模块化设计**：组合式函数和对话框组件的分离提高了代码的可维护性
 - **用户体验优化**：完整的进度跟踪和错误处理提升了用户满意度
 - **数据来源多样化**：支持本地文件上传和外部网站数据导入
@@ -585,6 +595,7 @@ BE_Routes --> MS["Meilisearch"]
 - 增强数据验证和错误恢复机制
 - 优化大数据量场景下的性能表现
 - 进一步丰富图标库的使用，提升界面美观度
+- 持续优化组件间的协调机制，提升整体稳定性

 ## 附录
 - **API 一览**
@@ -18,9 +18,10 @@

 ## 更新摘要
 **变更内容**
- 更新了搜索和重置按钮的交互设计，采用统一的圆形图标格式
- 改进了按钮的悬停状态和过渡效果，提升用户体验
- 使用Vue 3组合式API图标组件实现一致的视觉风格
+- 遵循新的设计系统指南进行了统一的UI改进，提升视觉一致性和用户体验
+- 优化了搜索和重置按钮的交互设计，采用现代化的圆形图标格式
+- 改进了按钮的悬停状态和过渡效果，增强用户操作反馈
+- 统一了组件的视觉风格，确保与Element Plus设计规范保持一致

 ## 目录
 1. [简介](#简介)
@@ -176,7 +177,7 @@ UserModel --> Database

 #### 更新的按钮交互设计

-**已更新** 搜索区域采用了现代化的圆形图标按钮设计：
+**已更新** 搜索区域采用了现代化的圆形图标按钮设计，遵循新的设计系统指南：

 ```mermaid
 flowchart TD
@@ -355,7 +356,7 @@ Deny --> Error[权限不足]
 ```

 **图表来源**
- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
+- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-88)
 - [backend/src/middleware/auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)

 **章节来源**
@@ -17,10 +17,10 @@

 ## 更新摘要
 **变更内容**
- 新增测量文件S3自动迁移功能，当更新型号的路径相关字段时自动迁移现有CSV文件
- 增强型号更新接口的智能文件处理逻辑
- 实现S3服务端文件复制与删除操作，确保数据一致性
- 优化型号管理流程，减少手动文件干预需求
+- 后端API层进行了小幅调整，优化了数据验证和错误处理逻辑
+- 数据建模层的重要修复，改进了字段约束和数据完整性检查
+- 增强了型号CRUD操作的健壮性和一致性保障
+- 完善了异常处理和日志记录机制

 ## 目录
 1. [简介](#简介)
@@ -34,18 +34,18 @@
 9. [结论](#结论)

 ## 简介
-本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。**最新更新**：新增squig.link外部数据源支持及测量文件S3自动迁移功能，显著提升型号数据管理的自动化程度和数据一致性保障。
+本文件为型号管理API的详细RESTful API文档，覆盖型号的CRUD操作、查询筛选与排序、数据验证规则，以及与OTA固件的一对多关联关系与级联操作。文档同时提供前端调用示例与后端实现细节，帮助开发者快速集成与维护。**最新更新**：基于后端API层的小幅调整和数据建模层的重要修复，进一步提升了系统的稳定性和数据一致性保障。

 ## 项目结构
 型号管理API位于后端Express应用中，采用模块化设计：
- 路由层：集中于 models.js，提供型号的增删改查、搜索推送、频响文件处理、**squig.link数据抓取**、**S3文件自动迁移**等接口
+- 路由层：集中于 models.js，提供型号的增删改查、搜索推送、频响文件处理、squig.link数据抓取、S3文件自动迁移等接口
 - 模型层：Model.js 定义数据库表结构
 - 验证层：model.js 使用Zod进行请求体验证
 - 工具层：response.js 统一响应格式
 - 中间件：auth.js 提供鉴权保护
- **服务层**：squiglink.js 提供squig.link外部数据源抓取服务，measurementStorage.js 提供S3存储与文件迁移服务
+- 服务层：squiglink.js 提供squig.link外部数据源抓取服务，measurementStorage.js 提供S3存储与文件迁移服务
 - 前端封装：frontend/src/api/model.js 提供HTTP调用封装
- **前端组件**：ModelFormDialog.vue 集成squig.link导入功能
+- 前端组件：ModelFormDialog.vue 集成squig.link导入功能

 ```mermaid
 graph TB
@@ -85,15 +85,15 @@ MS -. 存储 .-> S3["S3对象存储"]
 - [frontend/src/views/model/components/ModelFormDialog.vue:1-555](file://frontend/src/views/model/components/ModelFormDialog.vue#L1-L555)

 ## 核心组件
- 路由控制器：models.js 提供型号的列表查询、详情获取、创建、更新、删除、搜索推送、频响文件处理、**squig.link数据抓取**、**S3文件自动迁移**等接口
+- 路由控制器：models.js 提供型号的列表查询、详情获取、创建、更新、删除、搜索推送、频响文件处理、squig.link数据抓取、S3文件自动迁移等接口
 - 数据模型：Model.js 定义型号字段及约束
 - 请求验证：model.js 使用Zod Schema进行创建/更新的输入校验
 - 统一响应：response.js 提供统一的响应结构
 - 鉴权中间件：auth.js 实现Bearer Token鉴权
- **squig.link服务**：squiglink.js 提供外部数据源抓取功能
- **S3存储服务**：measurementStorage.js 提供文件上传、下载、迁移等存储服务
+- squig.link服务：squiglink.js 提供外部数据源抓取功能
+- S3存储服务：measurementStorage.js 提供文件上传、下载、迁移等存储服务
 - 前端封装：frontend/src/api/model.js 提供HTTP调用封装
- **前端组件**：ModelFormDialog.vue 集成squig.link导入功能
+- 前端组件：ModelFormDialog.vue 集成squig.link导入功能

 **章节来源**
 - [backend/src/routes/models.js:133-181](file://backend/src/routes/models.js#L133-L181)
@@ -107,7 +107,7 @@ MS -. 存储 .-> S3["S3对象存储"]
 - [frontend/src/views/model/components/ModelFormDialog.vue:158-464](file://frontend/src/views/model/components/ModelFormDialog.vue#L158-L464)

 ## 架构概览
-型号管理API采用分层架构，路由层负责HTTP协议与参数解析，模型层负责数据持久化，验证层确保输入合法性，工具层统一输出格式，中间件提供安全控制，**服务层提供外部数据源集成与S3存储管理**。
+型号管理API采用分层架构，路由层负责HTTP协议与参数解析，模型层负责数据持久化，验证层确保输入合法性，工具层统一输出格式，中间件提供安全控制，服务层提供外部数据源集成与S3存储管理。

 ```mermaid
 sequenceDiagram
@@ -225,18 +225,16 @@ datetime create_at
 - 内容类型：multipart/form-data
 - 表单字段：
  - measurement_file：频响文件（CSV/TXT/JSON），可选
-  - **squiglink_csv**：squig.link抓取的CSV内容，可选
+  - squiglink_csv：squig.link抓取的CSV内容，可选
  - brand_name、name、form、rig、source、eq_key
 - 文件处理：
-  - **优先级**：squiglink_csv > measurement_file > 无文件
+  - 优先级：squiglink_csv > measurement_file > 无文件
  - TXT文件自动转换为CSV
  - 仅允许.csv、.txt、.json
  - 上传至S3，键值包含source、form、brand_name、name
 - 成功响应：创建后的型号信息
 - 异常响应：重复、格式不支持、通用错误

-**更新** 新增squiglink_csv字段支持直接上传CSV内容
-
 **章节来源**
 - [backend/src/routes/models.js:371-437](file://backend/src/routes/models.js#L371-L437)
 - [backend/src/validators/model.js:3-10](file://backend/src/validators/model.js#L3-L10)
@@ -250,12 +248,10 @@ datetime create_at
 - 路径参数：model_id（整数）
 - 表单字段：同创建，支持部分字段更新（传入'null'表示保持原值）
 - 文件处理：同创建，若上传需提供source与form
- **智能文件迁移**：当未上传新文件且路径相关字段（source、form、brand_name、name）发生变更时，系统自动将现有CSV文件从旧路径迁移到新路径
+- 智能文件迁移：当未上传新文件且路径相关字段（source、form、brand_name、name）发生变更时，系统自动将现有CSV文件从旧路径迁移到新路径
 - 成功响应：更新后的型号信息
 - 异常响应：未找到、重复、格式不支持、通用错误

-**新增** 智能S3文件自动迁移功能，确保数据一致性与完整性
-
 **章节来源**
 - [backend/src/routes/models.js:439-535](file://backend/src/routes/models.js#L439-L535)
 - [backend/src/validators/model.js:12-19](file://backend/src/validators/model.js#L12-L19)
@@ -322,10 +318,10 @@ string model
  - 输出：推送成功数量、任务ID与推送数据

 **章节来源**
- [backend/src/routes/models.js:565-665](file://backend/src/routes/models.js#L565-L665)
+- [backend/src/routes/models.js:565-665](file://backend/src/routes/models.js#L565-665)

 ### 频响文件上传与查询
- 上传：POST /api/models/（multipart/form-data），支持TXT自动转换为CSV，**新增squiglink_csv字段**
+- 上传：POST /api/models/（multipart/form-data），支持TXT自动转换为CSV，新增squiglink_csv字段
 - 查询：GET /api/models/:model_id/measurement（仅Eafonyoung来源且存在form时可用）

 **章节来源**
@@ -349,30 +345,28 @@ string model
  - share_url：squig.link分享链接（必填）
  - selected_file：用户选择的特定文件名（可选）
 - 功能特性：
-  - **自动抓取**：根据share_url自动解析并抓取频响数据
-  - **候选选择**：当存在多个匹配文件时，返回候选列表供用户选择
-  - **直接下载**：当提供selected_file时，直接下载指定文件
-  - **佩戴方式检测**：从squigsites.json自动检测佩戴方式
+  - 自动抓取：根据share_url自动解析并抓取频响数据
+  - 候选选择：当存在多个匹配文件时，返回候选列表供用户选择
+  - 直接下载：当提供selected_file时，直接下载指定文件
+  - 佩戴方式检测：从squigsites.json自动检测佩戴方式
 - 响应格式：
  - 单个匹配：返回brand_name、model_name、form、csv_content、data_url
  - 多个匹配：返回matches候选列表
  - 错误：返回具体的抓取失败原因

 #### Squig.link服务功能
- **URL解析**：解析squig.link分享URL，提取baseURL和share参数
- **站点发现**：从https://squig.link/squigsites.json获取站点配置
- **文件匹配**：在phone_book.json中查找匹配的测量文件
- **数据下载**：支持多种文件后缀的频响数据下载
- **格式转换**：将TXT文件转换为CSV格式
- **缓存机制**：squigsites.json内存缓存（1小时TTL）
+- URL解析：解析squig.link分享URL，提取baseURL和share参数
+- 站点发现：从https://squig.link/squigsites.json获取站点配置
+- 文件匹配：在phone_book.json中查找匹配的测量文件
+- 数据下载：支持多种文件后缀的频响数据下载
+- 格式转换：将TXT文件转换为CSV格式
+- 缓存机制：squigsites.json内存缓存（1小时TTL）

 #### 前端集成
- **ModelFormDialog组件**：集成squig.link导入功能
- **自动填充**：抓取成功后自动填充品牌、型号、佩戴方式等字段
- **候选选择**：多文件匹配时提供选择对话框
- **实时预览**：显示数据URL便于验证
-
-**新增** 完整的squig.link外部数据源支持
+- ModelFormDialog组件：集成squig.link导入功能
+- 自动填充：抓取成功后自动填充品牌、型号、佩戴方式等字段
+- 候选选择：多文件匹配时提供选择对话框
+- 实时预览：显示数据URL便于验证

 **章节来源**
 - [backend/src/routes/models.js:307-369](file://backend/src/routes/models.js#L307-369)
@@ -382,17 +376,17 @@ string model
 ### S3文件自动迁移功能

 #### 智能文件迁移机制
- **触发条件**：更新型号时未上传新文件且路径相关字段发生变更
- **路径字段**：source（来源）、form（佩戴方式）、brand_name（品牌名）、name（型号名）
- **迁移策略**：服务端直接复制后删除，无需下载再上传
- **原子操作**：复制成功后才删除旧文件，确保数据完整性
+- 触发条件：更新型号时未上传新文件且路径相关字段发生变更
+- 路径字段：source（来源）、form（佩戴方式）、brand_name（品牌名）、name（型号名）
+- 迁移策略：服务端直接复制后删除，无需下载再上传
+- 原子操作：复制成功后才删除旧文件，确保数据完整性

 #### S3存储服务功能
- **文件路径构建**：autoeq/measurements/{source}/data/{form}/{brandFirstChar}/{brand model}.csv
- **上传服务**：uploadMeasurementToS3 - 支持CSV文件上传到S3
- **读取服务**：getMeasurementFromS3 - 从S3读取CSV文件内容
- **迁移服务**：moveMeasurementOnS3 - 实现S3文件的智能迁移
- **路径生成**：buildMeasurementKey - 根据参数生成标准S3 Key
+- 文件路径构建：autoeq/measurements/{source}/data/{form}/{brandFirstChar}/{brand model}.csv
+- 上传服务：uploadMeasurementToS3 - 支持CSV文件上传到S3
+- 读取服务：getMeasurementFromS3 - 从S3读取CSV文件内容
+- 迁移服务：moveMeasurementOnS3 - 实现S3文件的智能迁移
+- 路径生成：buildMeasurementKey - 根据参数生成标准S3 Key

 #### 迁移流程详解
 ```mermaid
@@ -414,26 +408,24 @@ K --> L
 ```

 **图表来源**
- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-L509)
+- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-509)
 - [backend/src/services/measurementStorage.js:116-157](file://backend/src/services/measurementStorage.js#L116-L157)

 #### 错误处理与日志记录
- **文件不存在**：跳过迁移并记录日志，不影响更新操作
- **网络异常**：抛出明确错误信息，便于问题排查
- **权限问题**：详细的错误描述，指导权限配置
- **路径冲突**：自动检测路径变化，避免不必要的操作
-
-**新增** 完整的S3文件自动迁移功能，提升数据管理自动化水平
+- 文件不存在：跳过迁移并记录日志，不影响更新操作
+- 网络异常：抛出明确错误信息，便于问题排查
+- 权限问题：详细的错误描述，指导权限配置
+- 路径冲突：自动检测路径变化，避免不必要的操作

 **章节来源**
- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-L509)
+- [backend/src/routes/models.js:502-509](file://backend/src/routes/models.js#L502-509)
 - [backend/src/services/measurementStorage.js:110-165](file://backend/src/services/measurementStorage.js#L110-L165)

 ## 依赖分析
- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互，**新增squiglink服务依赖与measurementStorage服务依赖**
+- 路由依赖：models.js 依赖Model模型、Zod验证器、响应工具、鉴权中间件，并与Meilisearch、S3服务交互，新增squiglink服务依赖与measurementStorage服务依赖
 - 模型依赖：Model.js 依赖Sequelize ORM
 - 前端依赖：frontend/src/api/model.js 依赖通用请求封装
- **服务依赖**：squiglink.js 依赖axios、logger，提供外部数据源抓取功能；measurementStorage.js 依赖AWS SDK、logger，提供S3存储服务
+- 服务依赖：squiglink.js 依赖axios、logger，提供外部数据源抓取功能；measurementStorage.js 依赖AWS SDK、logger，提供S3存储服务

 ```mermaid
 graph LR
@@ -466,10 +458,10 @@ MS -. 外部 .-> AWS["AWS SDK"]
 - Meilisearch超时：查询与删除文档设置超时，防止阻塞
 - 文件上传：内存存储multer，建议在高并发场景下优化为流式处理或外部对象存储直传
 - 验证前置：使用Zod在进入数据库操作前完成字段校验，减少无效请求
- **squig.link抓取超时**：设置15秒超时，避免外部服务影响系统性能
- **squigsites.json缓存**：1小时TTL减少对外部服务的频繁请求
- **S3迁移优化**：服务端直接复制，避免网络传输开销，提高迁移效率
- **路径变更检测**：智能判断是否需要迁移，避免不必要的S3操作
+- squig.link抓取超时：设置15秒超时，避免外部服务影响系统性能
+- squigsites.json缓存：1小时TTL减少对外部服务的频繁请求
+- S3迁移优化：服务端直接复制，避免网络传输开销，提高迁移效率
+- 路径变更检测：智能判断是否需要迁移，避免不必要的S3操作

 ## 故障排除指南
 - 401 未登录/无效凭证：检查Authorization头是否为Bearer Token且有效
@@ -478,10 +470,10 @@ MS -. 外部 .-> AWS["AWS SDK"]
 - 重复型号：创建/更新时如提示品牌+型号已存在，请调整参数
 - 文件格式不支持：仅允许.csv、.txt、.json，TXT会自动转换为CSV
 - Meilisearch异常：检查服务连通性与API密钥
- **squig.link抓取失败**：检查share_url格式、网络连通性、目标站点可用性
- **squig.link文件下载失败**：确认文件存在、权限正确、支持的文件后缀
- **S3迁移失败**：检查AWS凭证配置、S3 Bucket权限、网络连接状态
- **文件路径错误**：确认source、form、brand_name、name字段值符合规范
+- squig.link抓取失败：检查share_url格式、网络连通性、目标站点可用性
+- squig.link文件下载失败：确认文件存在、权限正确、支持的文件后缀
+- S3迁移失败：检查AWS凭证配置、S3 Bucket权限、网络连接状态
+- 文件路径错误：确认source、form、brand_name、name字段值符合规范

 **章节来源**
 - [backend/src/middleware/auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
@@ -492,4 +484,4 @@ MS -. 外部 .-> AWS["AWS SDK"]
 - [backend/src/services/measurementStorage.js:149-156](file://backend/src/services/measurementStorage.js#L149-L156)

 ## 结论
-型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。**最新更新**：新增squig.link外部数据源支持及测量文件S3自动迁移功能，显著提升了型号数据的获取效率和数据一致性保障。智能文件迁移机制确保了在更新型号路径相关字段时，现有CSV文件能够自动迁移到新路径，无需人工干预。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略、**squig.link抓取的超时与缓存策略**、**S3迁移的性能监控与错误处理**，并在删除型号前做好OTA关联清理。
+型号管理API提供了完善的CRUD能力、灵活的查询过滤与排序、严格的输入验证、以及与搜索与存储系统的集成。**最新更新**：基于后端API层的小幅调整和数据建模层的重要修复，进一步提升了系统的稳定性和数据一致性保障。智能文件迁移机制确保了在更新型号路径相关字段时，现有CSV文件能够自动迁移到新路径，无需人工干预。结合OTA模型的关联关系，可支撑从型号到固件升级的完整业务闭环。建议在生产环境中关注分页与超时配置、文件上传性能与安全策略、squig.link抓取的超时与缓存策略、S3迁移的性能监控与错误处理，并在删除型号前做好OTA关联清理。
@@ -25,11 +25,12 @@

 ## 更新摘要
 **变更内容**   
- 全面增强玻璃拟态主题系统，提升透明度与模糊效果质量
- 新增多层级阴影变量系统，优化视觉深度层次
+- 引入玻璃拟态设计系统支持，包含半透明背景、微妙边框和背景模糊效果
+- 主题系统扩展了44行新CSS代码，显著刷新视觉设计语言
+- 增强透明度控制系统，提供更细腻的视觉效果层次
+- 优化阴影层级系统，建立更清晰的视觉深度层次
 - 精炼色彩调色板，以青色强调色替代珊瑚粉色系
 - 重构表格样式系统，建立更清晰的视觉层级结构
- 扩展CSS变量体系，支持1272行完整的设计令牌定义

 ## 目录
 1. [简介](#简介)
				`@@ -1 +0,0 @@`
				`前端：Vue 3 + Vite + Element Plus + vue-router + axios；后端：Express + Sequelize(ORM) + MySQL2 + JSON Web Token + Multer(文件上传) + Axios(上游曲线服务) + Winston(日志) + ioredis + @aws-sdk/client-s3；构建产物由 Nginx 静态托管，开发期使用 nodemon 热重载。`
				`@@ -1 +0,0 @@`
				`基于 Vue3 + Element Plus 与 Express/Sequelize 的耳机品牌型号 OTA 管理平台，提供玻璃拟态暗色主题的管理后台。`
				`@@ -1 +0,0 @@`
				本地启动需先复制 `.env.example` 为 `.env` 并填写数据库/Redis/S3 等环境变量；运行 `docker compose up -d` 即可同时拉起后端与前端（端口 8082/8083）。前端单独开发：`cd frontend && pnpm dev`；后端单独开发：`cd backend && pnpm dev`。
				`@@ -0,0 +1 @@`
				`后端：Express + Sequelize + JWT + Redis + Meilisearch + AWS S3（X9 OTA 包存储）+ squiglink 曲线客户端；前端：Vue 3 + Vite + Element Plus + axios；构建与运行：pnpm v11、Node 22、Docker Compose（Nginx 静态托管 + Node API）。`
				`@@ -0,0 +1 @@`
				`基于 Node.js + Vue 3 的 Luxsin 音频设备与 OTA 升级管理后台，提供品牌/型号/黑名单/OTA/用户等管理能力。`
				`@@ -0,0 +1 @@`
				首次部署需在服务器创建 `/data/project/dashboard/.env`（参考 `.env.example`）并手动上传代码后执行 `docker compose build --no-cache backend && docker compose up -d`；本地开发推荐先 `cd frontend && pnpm build` 生成 dist，再分别启动后端与前端 dev server，或直接用 `./scripts/upload.sh all` 一键上传。