新增项目文档

2026-06-30 14:46:52 +08:00
parent cac5bef5a7
commit 08da279275
79 changed files with 20860 additions and 0 deletions
@@ -0,0 +1,15 @@
+schema_version: 1
+module_path: build_system
+title: Docker Compose 编排与 rsync 增量部署
+scope: []
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/nginx.conf
+    - scripts/upload.sh
+    - DEPLOY.md
+    - backend/package.json
+    - frontend/package.json
+depends_on: []
+related_to: []
@@ -0,0 +1,35 @@
+## 1. 构建系统与工具链
+项目采用 **Docker Compose** 作为核心编排工具，结合 **pnpm** 进行依赖管理。整体架构分为前端（Vue 3 + Vite）和后端（Node.js + Express）两个独立服务。
+
+- **包管理器**：前后端均使用 `pnpm`，并在 `package.json` 中通过 `packageManager` 字段锁定版本（`pnpm@11.5.2`），确保环境一致性。
+- **前端构建**：使用 `Vite` 进行编译打包，产物输出至 `frontend/dist`。
+- **后端运行**：基于 `node:22-alpine` 镜像，直接运行 `src/app.js`。
+
+## 2. 容器化策略
+### 后端 (backend/Dockerfile)
+- **基础镜像**：`node:22-alpine`。
+- **构建逻辑**：采用单层结构，先安装生产依赖（`pnpm install --prod`），再拷贝源码。
+- **端口**：容器内固定监听 `8000` 端口。
+
+### 前端 (frontend/Dockerfile & docker-compose.yml)
+- **混合模式**：虽然提供了多阶段构建的 `Dockerfile`（Builder -> Nginx），但在生产环境的 `docker-compose.yml` 中，前端服务直接使用官方 `nginx:alpine` 镜像。
+- **挂载部署**：通过 Volume 将宿主机的 `frontend/dist` 和 `nginx.conf` 挂载到容器中。这种方式避免了每次前端更新都重新构建 Docker 镜像，提升了部署效率。
+- **反向代理**：Nginx 配置了 `/api` 路径的反向代理，将请求转发至 `http://backend:8000`，解决了跨域问题并统一了入口。
+
+## 3. 部署流程与自动化
+项目实现了一套基于 **rsync** 的半自动化部署方案，核心脚本为 `scripts/upload.sh`。
+
+### 部署步骤
+1. **本地构建**：在本地执行 `pnpm build` 生成前端静态资源。
+2. **代码同步**：运行 `./scripts/upload.sh all`，通过 SSH/rsync 将前端产物、后端源码及 `docker-compose.yml` 同步至远程服务器（默认路径 `/data/project/dashboard`）。
+3. **远程启动**：在服务器上执行 `docker compose build --no-cache backend` 和 `docker compose up -d` 完成服务重启。
+
+### 关键约定
+- **环境变量**：所有配置统一由根目录的 `.env` 文件管理，并通过 `env_file` 注入后端容器。`.env` 文件不随脚本上传，需在服务器手动维护。
+- **日志管理**：Compose 文件中定义了 `json-file` 驱动，限制日志最大大小为 10MB，保留 5 个文件，防止磁盘爆满。
+- **OTA 存储**：通过 Volume 将宿主机的 `/data/projects/source` 映射到后端容器，用于存储大型 OTA 升级包。
+
+## 4. 开发者规范
+- **端口映射**：本地开发时后端默认使用 `8083`，而容器内固定为 `8000`。开发者需注意 `PORT` 环境变量在不同环境下的覆盖逻辑。
+- **依赖更新**：若修改了 `package.json`，必须同步更新 `pnpm-lock.yaml` 并重新上传后端相关文件，否则 Docker 构建可能失败或使用旧依赖。
+- **前端更新**：仅更新前端时，只需重新构建并同步 `dist` 目录，然后重启 `frontend` 容器即可，无需重建镜像。
@@ -0,0 +1,129 @@
+# 知识卡导出索引文件
+schema_version: 1
+locale: zh-CN
+branch: main
+nodes_managed: true
+exported_at: "2026-06-30T06:40:47Z"
+modules:
+    "":
+        dir_name: 音频设备管理全栈平台
+        title: 音频设备管理全栈平台
+        scope:
+            - .gitignore
+            - README.md
+            - DEPLOY.md
+            - docker-compose.yml
+            - scripts/
+            - .env
+            - .env.example
+        source_files: []
+        children:
+            - backend
+            - frontend
+        depends_on: []
+        related_to: []
+    backend:
+        dir_name: 音频设备管理后端 API
+        title: 音频设备管理后端 API
+        scope:
+            - backend/
+        source_files: []
+        children: []
+        depends_on: []
+        related_to:
+            - path: frontend
+    build_system:
+        dir_name: Docker Compose 编排与 rsync 增量部署
+        title: Docker Compose 编排与 rsync 增量部署
+        scope: []
+        source_files:
+            - docker-compose.yml
+            - backend/Dockerfile
+            - frontend/Dockerfile
+            - frontend/nginx.conf
+            - scripts/upload.sh
+            - DEPLOY.md
+            - backend/package.json
+            - frontend/package.json
+        children: []
+        depends_on: []
+        related_to: []
+    configuration_system:
+        dir_name: 基于环境变量与 Docker Compose 的分层配置体系
+        title: 基于环境变量与 Docker Compose 的分层配置体系
+        scope: []
+        source_files:
+            - .env.example
+            - backend/src/config/loadEnv.js
+            - backend/src/config/env.js
+            - backend/src/config/database.js
+            - backend/src/config/redis.js
+            - docker-compose.yml
+            - frontend/vite.config.js
+        children: []
+        depends_on: []
+        related_to: []
+    dependency_management:
+        dir_name: 基于 pnpm 与 Docker 的前后端依赖管理
+        title: 基于 pnpm 与 Docker 的前后端依赖管理
+        scope: []
+        source_files:
+            - backend/package.json
+            - frontend/package.json
+            - backend/pnpm-lock.yaml
+            - frontend/pnpm-lock.yaml
+            - backend/Dockerfile
+            - frontend/Dockerfile
+            - frontend/pnpm-workspace.yaml
+        children: []
+        depends_on: []
+        related_to: []
+    error_handling:
+        dir_name: 全栈错误处理与响应规范
+        title: 全栈错误处理与响应规范
+        scope: []
+        source_files:
+            - backend/src/utils/response.js
+            - backend/src/app.js
+            - backend/src/middleware/auth.js
+            - backend/src/routes/models.js
+            - backend/src/routes/auth.js
+            - frontend/src/utils/request.js
+        children: []
+        depends_on: []
+        related_to: []
+    frontend:
+        dir_name: 音频设备管理后台前端
+        title: 音频设备管理后台前端
+        scope:
+            - frontend/
+        source_files: []
+        children: []
+        depends_on: []
+        related_to:
+            - path: backend
+    frontend_style:
+        dir_name: 深色玻璃拟态主题系统 (Lux Theme)
+        title: 深色玻璃拟态主题系统 (Lux Theme)
+        scope: []
+        source_files:
+            - frontend/src/styles/lux-theme.css
+            - frontend/src/layout/index.vue
+            - frontend/src/main.js
+            - frontend/src/App.vue
+            - frontend/package.json
+        children: []
+        depends_on: []
+        related_to: []
+    logging_system:
+        dir_name: 后端日志系统 (Winston)
+        title: 后端日志系统 (Winston)
+        scope: []
+        source_files:
+            - backend/src/config/logger.js
+            - backend/src/app.js
+            - backend/src/routes/auth.js
+            - backend/src/config/database.js
+        children: []
+        depends_on: []
+        related_to: []
@@ -0,0 +1,13 @@
+schema_version: 1
+module_path: error_handling
+title: 全栈错误处理与响应规范
+scope: []
+source_files:
+    - backend/src/utils/response.js
+    - backend/src/app.js
+    - backend/src/middleware/auth.js
+    - backend/src/routes/models.js
+    - backend/src/routes/auth.js
+    - frontend/src/utils/request.js
+depends_on: []
+related_to: []
@@ -0,0 +1,38 @@
+### 1. 核心策略：统一响应结构与业务码
+该仓库采用**基于 HTTP 200 的业务状态码**模式，而非依赖 HTTP 协议层的状态码来区分业务逻辑的成功与失败。
+
+- **后端 (Node.js/Express)**：
+  - 所有接口（除认证中间件外）均返回 `HTTP 200`。
+  - 通过 `ApiResponse` 工具类封装响应体，包含 `code`、`msg` 和 `data` 字段。
+  - **成功**：`code: 1`。
+  - **失败**：`code: 0`（通用错误）或 `code: 2`（无数据）。
+  - **异常捕获**：在路由层使用 `try...catch` 包裹异步逻辑，捕获异常后记录日志并返回 `ApiResponse.error()`。
+
+- **前端 (Vue 3/Axios)**：
+  - 在 `request.js` 中配置响应拦截器。
+  - 当检测到 `res.code === 0` 时，自动触发 `ElMessage.error` 提示用户，并将 Promise 标记为 `reject`。
+  - 支持 `skipErrorToast` 配置项，允许特定请求（如进度轮询）静默处理错误。
+
+### 2. 关键文件与实现细节
+
+#### 后端：响应工具与中间件
+- **`backend/src/utils/response.js`**：定义了全局统一的响应格式。`ApiResponse.success`、`ApiResponse.error` 和 `ApiResponse.noData` 是后端返回数据的唯一出口。
+- **`backend/src/middleware/auth.js`**：**例外情况**。认证中间件直接操作 `res.status(401)` 或 `res.status(403)`。这是为了在前端拦截器中能准确识别身份失效并执行重定向逻辑。
+- **`backend/src/routes/*.js`**：各业务路由文件（如 `models.js`, `auth.js`）遵循“捕获即返回”原则。例如在 `models.js` 中，数据库查询或 S3 上传失败均被捕获并转换为友好的中文错误提示。
+
+#### 前端：拦截器与权限联动
+- **`frontend/src/utils/request.js`**：
+  - **401 处理**：自动清除本地 Token (`clearAuth`) 并重定向至登录页。
+  - **403 处理**：弹出“无权限”警告。
+  - **网络错误**：捕获非业务逻辑的网络层异常（如超时、断网），统一提示“网络错误”。
+
+### 3. 架构约定与开发规则
+1. **禁止直接抛出未捕获异常**：后端路由处理器必须包含 `try...catch` 块，确保任何内部错误（DB、S3、Meilisearch）都不会导致进程崩溃或返回原始堆栈信息。
+  
+2. **敏感信息脱敏**：在 `catch` 块中返回给前端的 `msg` 应为通用提示（如“error”或“登录失败”），具体错误详情仅通过 `logger.error` 记录在服务器日志中。
+
+3. **前端错误消费**：
+   - 默认情况下，前端无需在每个 API 调用处编写 `catch` 逻辑来处理 UI 提示，拦截器已自动完成。
+   - 若需自定义错误处理（如表单校验反馈），应在 API 调用处捕获 `Promise.reject` 并阻止默认弹窗。
+
+4. **认证优先原则**：涉及权限的接口，先由中间件进行 Token 校验。若校验失败，直接中断请求链路并返回标准 HTTP 401/403，不进入业务逻辑层的 `try...catch`。
@@ -0,0 +1,11 @@
+schema_version: 1
+module_path: logging_system
+title: 后端日志系统 (Winston)
+scope: []
+source_files:
+    - backend/src/config/logger.js
+    - backend/src/app.js
+    - backend/src/routes/auth.js
+    - backend/src/config/database.js
+depends_on: []
+related_to: []
@@ -0,0 +1,26 @@
+## 1. 核心框架与配置
+- **框架**: 使用 `winston` 作为后端 Node.js 应用的统一日志框架。
+- **配置文件**: `backend/src/config/logger.js` 负责初始化 logger 实例。
+- **日志级别**: 默认设置为 `info`，涵盖 info, warn, error 等级别。
+- **输出格式**: 
+  - 采用自定义的文本格式：`${timestamp} - ${level} - ${message} ${JSON.stringify(meta)}`。
+  - 时间戳格式为 `YYYY-MM-DD HH:mm:ss`。
+  - 额外元数据（meta）会被序列化为 JSON 字符串附加在消息后。
+
+## 2. 日志输出目标 (Transports)
+- **控制台 (Console)**: 所有级别的日志都会输出到标准输出，便于本地开发和容器日志采集。
+- **文件 (File)**: 所有日志同时写入 `backend/logs/app.log` 文件。
+  - 目录 `logs/` 若不存在会在初始化时自动创建。
+  - 目前未配置日志轮转（Log Rotation），长期运行需注意文件大小。
+
+## 3. 使用规范与模式
+- **引入方式**: 在各业务模块中通过 `require('../config/logger')` 获取单例 logger。
+- **记录模式**:
+  - **信息类**: `logger.info('描述性消息')`，如服务启动、用户登录成功、数据库同步完成。
+  - **警告类**: `logger.warn('异常但可恢复的情况')`，如登录失败、资源未找到。
+  - **错误类**: `logger.error('错误详情')`，通常在 catch 块中记录异常信息 `e.message`。
+- **上下文记录**: 建议在 message 中包含关键业务 ID 或参数，例如 `User ${username} logged in` 或 `id=${brandId}`。
+
+## 4. 特殊场景处理
+- **数据库日志**: 在 `backend/src/config/database.js` 中，Sequelize 的 SQL 日志仅在开发环境 (`APP_ENV === 'development'`) 下通过 `console.log` 输出，生产环境关闭以避免性能损耗和日志污染。
+- **前端日志**: 前端项目 (`frontend/`) 目前未发现统一的日志封装，主要依赖浏览器控制台默认的 `console` 输出。
@@ -0,0 +1,14 @@
+schema_version: 1
+module_path: dependency_management
+title: 基于 pnpm 与 Docker 的前后端依赖管理
+scope: []
+source_files:
+    - backend/package.json
+    - frontend/package.json
+    - backend/pnpm-lock.yaml
+    - frontend/pnpm-lock.yaml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/pnpm-workspace.yaml
+depends_on: []
+related_to: []
@@ -0,0 +1,27 @@
+## 1. 核心系统与工具
+该项目采用 **pnpm** 作为前后端统一的 JavaScript/TypeScript 包管理器，并通过 **Docker Compose** 进行容器化编排。项目明确指定了 `packageManager` 字段（`pnpm@11.5.2`），利用 Corepack 机制确保开发环境与生产环境使用完全一致的包管理版本。
+
+- **包管理器**: pnpm (v11.5.2)
+- **锁定文件**: `pnpm-lock.yaml`
+- **运行时**: Node.js (Backend: v22-alpine, Frontend Builder: v18-alpine)
+- **部署编排**: Docker Compose
+
+## 2. 关键文件与配置
+- **`backend/package.json` / `frontend/package.json`**: 分别定义了后端 API 和前端 Vue 应用的依赖清单。后端依赖包括 `express`, `sequelize`, `mysql2`, `ioredis` 等；前端依赖包括 `vue`, `element-plus`, `axios` 等。
+- **`pnpm-lock.yaml`**: 存在于 `backend/` 和 `frontend/` 目录下，用于精确锁定依赖树，确保构建的可重复性。
+- **`frontend/pnpm-workspace.yaml`**: 虽然目前仅包含 `allowBuilds` 配置，但表明前端目录具备向 pnpm Workspace 演进的潜力或已预留相关配置入口。
+- **`Dockerfile`**: 
+  - 后端：通过 `corepack enable pnpm` 启用 pnpm，并使用 `--frozen-lockfile` 参数安装生产依赖。
+  - 前端：采用多阶段构建，在 `builder` 阶段安装依赖并打包，最终产物由 `nginx:alpine` 托管。
+
+## 3. 架构与约定
+- **依赖隔离**: 前后端拥有独立的 `node_modules` 和锁定文件，互不干扰。
+- **生产环境优化**: 
+  - 后端 Docker 镜像仅安装 `dependencies` (`--prod`)，排除 `devDependencies`（如 `nodemon`），减小镜像体积。
+  - 前端通过多阶段构建，最终镜像不包含 `node_modules` 或构建工具，仅保留静态资源。
+- **版本一致性**: 通过在 `package.json` 中声明 `packageManager` 字段，配合 CI/CD 或本地开发时的 Corepack 支持，强制统一工具链版本。
+
+## 4. 开发者规范
+- **安装依赖**: 必须使用 `pnpm install`，禁止使用 `npm install` 或 `yarn`，以避免锁定文件冲突。
+- **更新依赖**: 修改 `package.json` 后，需重新运行 `pnpm install` 并同步提交更新后的 `pnpm-lock.yaml`。
+- **容器化构建**: 生产环境部署应优先使用 `docker-compose up --build`，确保依赖安装过程遵循 Dockerfile 中定义的 `--frozen-lockfile` 约束，防止意外引入未锁定的新版本。
@@ -0,0 +1,14 @@
+schema_version: 1
+module_path: configuration_system
+title: 基于环境变量与 Docker Compose 的分层配置体系
+scope: []
+source_files:
+    - .env.example
+    - backend/src/config/loadEnv.js
+    - backend/src/config/env.js
+    - backend/src/config/database.js
+    - backend/src/config/redis.js
+    - docker-compose.yml
+    - frontend/vite.config.js
+depends_on: []
+related_to: []
@@ -0,0 +1,48 @@
+## 1. 核心系统与工具
+该项目采用 **环境变量（Environment Variables）** 作为唯一的配置来源，结合 **`dotenv`** 库进行本地开发时的文件加载，并通过 **Docker Compose** 在部署时注入环境变量。这种模式遵循了 [12-Factor App](https://12factor.net/zh-cn/config) 的配置原则，实现了配置与代码的分离。
+
+- **后端 (Node.js/Express)**: 使用 `dotenv` 加载根目录 `.env` 文件。
+- **前端 (Vue 3/Vite)**: 依赖 Vite 的默认行为，通过 `vite.config.js` 中的代理配置处理开发环境 API 路由，生产环境配置通常由构建产物或 Nginx 静态配置决定。
+- **编排工具**: 使用 `docker-compose.yml` 统一管理多服务的环境变量注入和端口映射。
+
+## 2. 关键文件与职责
+
+| 文件路径 | 职责描述 |
+| :--- | :--- |
+| `/.env` & `/.env.example` | **全局配置模板**。定义了数据库、Redis、S3、JWT 密钥等所有服务的运行时参数。 |
+| `/backend/src/config/loadEnv.js` | **环境加载入口**。在后端应用启动初期，自动检测并加载项目根目录的 `.env` 文件。 |
+| `/backend/src/config/env.js` | **环境状态管理**。统一导出 `APP_ENV`、`isDevelopment`、`isProduction` 标志，供其他模块判断运行模式。 |
+| `/backend/src/config/database.js` | **数据库配置**。从环境变量读取 MySQL 连接信息，并根据环境标志决定是否开启 SQL 日志。 |
+| `/backend/src/config/redis.js` | **缓存配置**。从环境变量读取 Redis 连接信息，实现单例模式的客户端初始化。 |
+| `/docker-compose.yml` | **部署配置**。通过 `env_file` 将 `.env` 注入后端容器，并强制覆盖部分变量（如容器内端口）。 |
+| `/frontend/vite.config.js` | **前端开发配置**。定义了开发服务器的端口及指向后端的 API 代理规则。 |
+
+## 3. 架构设计与分层逻辑
+
+### 3.1 配置加载流程
+1. **初始化阶段**: `backend/src/app.js` 第一行即调用 `require('./config/loadEnv')`，确保后续所有模块能访问到 `process.env`。
+2. **本地开发**: `loadEnv.js` 检查根目录是否存在 `.env`，若存在则通过 `dotenv.config()` 将其载入内存。
+3. **容器部署**: Docker Compose 通过 `env_file: - .env` 将变量注入容器。此时容器内可能不存在 `.env` 文件，但环境变量已由 Docker 守护进程提供。
+
+### 3.2 环境隔离策略
+- **逻辑环境**: 通过 `APP_ENV` 变量区分 `development` 和 `production`。该变量控制日志输出级别、数据库同步行为等。
+- **物理环境**: 
+  - **本地**: 后端监听 `8083` 端口，前端通过 Vite Proxy 转发请求。
+  - **Docker**: 后端在容器内监听 `8000` 端口（由 Compose 强制指定），外部映射为 `8083`；前端由 Nginx 托管，映射为 `8082`。
+
+### 3.3 敏感信息管理
+- **示例文件**: 提供 `.env.example` 作为模板，避免敏感信息（如 `JWT_SECRET`, `AWS_ACCESS_KEY_ID`）直接提交到版本控制系统。
+- **默认值保护**: 在 `database.js` 和 `redis.js` 中为关键配置提供了硬编码的默认值（如 `root123`），防止因环境变量缺失导致应用崩溃，但在生产环境中应始终通过 `.env` 覆盖这些默认值。
+
+## 4. 开发者规范
+
+1. **新增配置项**: 
+   - 必须在 `.env.example` 中添加对应的键名和说明。
+   - 在 `backend/src/config/` 下创建或更新对应的配置模块，通过 `process.env.VAR_NAME` 获取值。
+2. **环境判断**: 
+   - 严禁在业务代码中直接读取 `process.env.APP_ENV`。
+   - 必须使用 `src/config/env.js` 导出的 `isDevelopment` 或 `isProduction` 布尔值，以保持逻辑一致性。
+3. **端口一致性**: 
+   - 修改后端端口时，需同步更新 `.env` 中的 `PORT`、`docker-compose.yml` 中的 `environment` 覆盖项以及 `ports` 映射。
+4. **前端代理**: 
+   - 若后端开发端口变更，需同步修改 `frontend/vite.config.js` 中的 `proxy.target`。
@@ -0,0 +1,12 @@
+schema_version: 1
+module_path: frontend_style
+title: 深色玻璃拟态主题系统 (Lux Theme)
+scope: []
+source_files:
+    - frontend/src/styles/lux-theme.css
+    - frontend/src/layout/index.vue
+    - frontend/src/main.js
+    - frontend/src/App.vue
+    - frontend/package.json
+depends_on: []
+related_to: []
@@ -0,0 +1,35 @@
+## 1. 核心系统与工具
+- **UI 框架**: Vue 3 + Element Plus。
+- **样式方案**: 原生 CSS + CSS Variables (CSS Custom Properties)。
+- **构建工具**: Vite。
+- **主题策略**: 基于 Element Plus 的 Dark Mode 基础，通过全局自定义 CSS (`lux-theme.css`) 进行深度覆盖和扩展，实现名为 "Lux" 的深色玻璃拟态（Glassmorphism）风格。
+
+## 2. 关键文件与结构
+- **`frontend/src/styles/lux-theme.css`**: 核心主题文件。定义了全站的设计令牌（Design Tokens）、背景动效、组件覆盖样式。
+- **`frontend/src/layout/index.vue`**: 布局容器。应用 `.lux-shell` 类名，承载侧边栏、顶栏和主内容区，并包含背景光球（Orbs）的 DOM 结构。
+- **`frontend/src/main.js`**: 入口文件。按顺序引入 Element Plus 基础样式、Dark Mode 变量以及自定义的 `lux-theme.css`。
+- **`frontend/src/App.vue`**: 根组件。设置全局字体栈（Inter, PingFang SC, Microsoft YaHei）及抗锯齿渲染。
+
+## 3. 架构与设计规范
+### 3.1 设计令牌 (Design Tokens)
+在 `:root` 中定义了一套语义化的 CSS 变量，用于保持视觉一致性：
+- **背景色**: `--lux-page-bg: #0a0e14` (深空黑), `--lux-card-bg: #1e293b` (深蓝灰)。
+- **主色调**: `--lux-cyan: #38bdf8` (青色), `--lux-indigo: #6366f1` (靛蓝), `--lux-violet: #7c3aed` (紫罗兰)。
+- **文本色**: `--lux-text-strong: #e2e8f0` (高亮文本), `--lux-text-muted: #94a3b8` (次要文本)。
+- **玻璃效果**: `--lux-glass-sidebar: rgba(15, 23, 42, 0.6)`，配合 `backdrop-filter: blur(18px)` 实现毛玻璃质感。
+
+### 3.2 视觉风格：深色宇宙与玻璃拟态
+- **背景动效**: 使用 `.lux-shell-bg` 容器包裹三个绝对定位的 `.lux-orb` (光球)，通过高斯模糊 (`blur(80px)`) 和低透明度营造深邃的宇宙氛围。
+- **卡片与容器**: 所有 `.el-card` 被强制设置为深色背景、圆角 (`16px`) 和微弱的边框光晕，以在深色背景上凸显层级。
+- **交互反馈**: 按钮和菜单项在 Hover 状态下使用半透明的白色或青色渐变背景，激活状态则带有内阴影 (`box-shadow inset`) 以增强立体感。
+
+### 3.3 布局约定
+- **Shell 模式**: 整个应用包裹在 `.lux-shell` 中，采用 `min-height: 100vh` 和 `overflow: hidden` 确保全屏沉浸式体验。
+- **侧边栏**: 采用玻璃拟态设计，支持折叠（64px）与展开（220px）动画过渡。折叠时显示图标导航栏（Rail），展开时显示完整菜单。
+- **顶栏**: 悬浮的玻璃态条状区域，包含面包屑和用户操作下拉菜单。
+
+## 4. 开发者指南
+- **类名约束**: 所有自定义样式应尽量限制在 `.lux-shell` 作用域下，避免污染全局或影响第三方组件的默认行为。
+- **组件覆盖**: 修改 Element Plus 组件样式时，优先使用 CSS 变量覆盖。若需强制覆盖，请使用 `.lux-shell .el-component` 的选择器优先级策略，并尽量保持 `!important` 的最小化使用（目前主题文件中存在部分 `!important` 以对抗组件库默认样式）。
+- **颜色使用**: 严禁硬编码颜色值。新增样式时应引用 `lux-theme.css` 中定义的 `--lux-*` 变量，以确保主题的统一性和后续的可维护性。
+- **响应式**: 目前布局主要面向桌面端管理后台，侧边栏采用固定宽度逻辑。若需适配移动端，需在 `.lux-shell` 媒体查询中增加侧边栏抽屉式交互的支持。
@@ -0,0 +1,14 @@
+schema_version: 1
+module_path: ""
+title: 音频设备管理全栈平台
+scope:
+    - .gitignore
+    - README.md
+    - DEPLOY.md
+    - docker-compose.yml
+    - scripts/
+    - .env
+    - .env.example
+source_files: []
+depends_on: []
+related_to: []
@@ -0,0 +1,4 @@
+- **服务编排**：使用 `docker-compose.yml` 定义 `backend` (Node.js) 和 `frontend` (Nginx) 服务，通过 `audio-network` 桥接网络实现内部通信。
+- **配置管理**：根目录 `.env` 作为唯一环境变量源，由 Compose 注入后端容器，前端通过 Nginx 反向代理 `/api` 至后端。
+- **部署流水线**：`scripts/upload.sh` 脚本基于 rsync/ssh 实现增量代码同步，配合 `DEPLOY.md` 规范了从本地构建到服务器重启的标准化运维路径。
+- **存储映射**：宿主机目录 `/data/projects/source` 挂载至后端容器，用于持久化存储 OTA 升级包。
@@ -0,0 +1 @@
+通过 Docker Compose 统一编排前后端服务，提供标准化的本地构建、远程同步及容器化部署流程。
@@ -0,0 +1,2 @@
+- **一键同步**：执行 `./scripts/upload.sh all` 将前端产物、后端源码及编排文件同步至远程服务器。
+- **服务启动**：在服务器端执行 `docker compose build --no-cache backend && docker compose up -d` 完成全量更新与启动。
@@ -0,0 +1,2 @@
+- 所有服务共享根目录 `.env` 进行环境配置，禁止在各子模块中维护独立的环境变量文件。
+- 前端静态资源通过 Nginx 托管并代理 API 请求，后端统一暴露于 8000 端口（容器内）并通过 Compose 映射至宿主机 8083。
@@ -0,0 +1,9 @@
+schema_version: 1
+module_path: frontend
+title: 音频设备管理后台前端
+scope:
+    - frontend/
+source_files: []
+depends_on: []
+related_to:
+    - path: backend
@@ -0,0 +1 @@
+Vue 3, Vite, Element Plus, Axios, Vue Router
@@ -0,0 +1,4 @@
+- **技术栈**: 采用 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` 中的工具函数进行持久化与管理。
@@ -0,0 +1 @@
+基于 Vue 3 和 Element Plus 构建的耳机品牌、型号及 OTA 升级管理的单页应用。
@@ -0,0 +1,3 @@
+- API 模块按业务领域拆分（如 auth.js, brand.js），统一导出异步方法并依赖 @/utils/request 实例。
+- 视图组件采用路径映射命名规范，每个业务模块在 views 下拥有独立文件夹及 index.vue 入口文件。
+- 认证逻辑集中在 utils/auth.js，提供 getToken, isSuperAdmin, clearAuth 等原子操作供路由守卫和组件调用。
@@ -0,0 +1,9 @@
+schema_version: 1
+module_path: backend
+title: 音频设备管理后端 API
+scope:
+    - backend/
+source_files: []
+depends_on: []
+related_to:
+    - path: frontend
@@ -0,0 +1,5 @@
+- **运行时与框架**：Node.js 22 (Alpine), Express.js v4。
+- **数据持久化**：MySQL (via `mysql2` and `sequelize` ORM)。
+- **缓存与搜索**：Redis (via `ioredis` for EQ cache), Meilisearch (via `axios` for model search)。
+- **文件存储**：AWS S3 (via `@aws-sdk/client-s3` for OTA packages and measurement files)。
+- **工具库**：`jsonwebtoken` (JWT), `zod` (Schema 验证), `multer` (文件上传), `winston` (日志)。
@@ -0,0 +1,5 @@
+- **分层架构**：采用经典的 MVC 模式，`routes/` 处理 HTTP 请求与响应，`models/` (Sequelize) 定义数据模型，`services/` 封装外部存储（S3, Redis）和业务逻辑。
+- **入口与初始化**：`src/app.js` 为应用入口，负责加载环境变量、同步数据库表结构 (`sequelize.sync()`) 并引导创建超级管理员 (`userBootstrap`)。
+- **路由组织**：`src/routes/index.js` 汇总所有业务路由（auth, brands, models, ota 等），通过 Express 中间件机制挂载。
+- **认证机制**：`middleware/auth.js` 实现基于 JWT 的身份验证，支持普通用户登录与超级管理员权限校验 (`requireSuperAdmin`)。
+- **外部集成**：通过 `services/` 目录下的模块与 AWS S3 (文件存储)、Redis (EQ 缓存)、Meilisearch (搜索索引) 及远程曲线服务进行交互。
@@ -0,0 +1 @@
+提供耳机品牌、型号、OTA 升级及用户管理的 RESTful API，集成 MySQL、Redis、S3 和 Meilisearch。
@@ -0,0 +1,3 @@
+- **依赖管理**：使用 `pnpm` 作为包管理器 (`packageManager: pnpm@11.5.2`)，安装命令为 `pnpm install --frozen-lockfile`。
+- **启动脚本**：提供 `start.sh`, `stop.sh`, `restart.sh` 用于进程管理；Docker 镜像基于 `node:22-alpine` 构建。
+- **环境引导**：首次启动时会自动执行 `ensureBootstrapSuperAdmin`，若数据库无用户则根据环境变量 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 创建初始超级管理员。
@@ -0,0 +1,4 @@
+- 统一响应格式：所有 API 均通过 `utils/response.js` 中的 `ApiResponse` 对象返回标准化 JSON，包含 `code` (1:成功, 0:错误, 2:无数据), `msg` 和 `data` 字段。
+- 集中式日志记录：使用 `winston` 配置的 `logger` 记录关键业务操作（如登录、创建/更新/删除资源）及错误信息，日志输出至 `logs/app.log`。
+- 路由级认证保护：受保护的路由组（如 brands, models, ota）在路由文件顶部通过 `router.use(authMiddleware)` 全局启用 JWT 验证，仅公开接口（如 `/health`, `/api/ota/latest/check`）例外。
+- 参数空值处理：在更新操作中，显式检查请求体字段是否为 `undefined` 或 `'null'` 字符串，以区分“未提供”与“设为空”，避免意外覆盖现有数据。
				`@@ -0,0 +1 @@`
				`通过 Docker Compose 统一编排前后端服务，提供标准化的本地构建、远程同步及容器化部署流程。`
				`@@ -0,0 +1 @@`
				`Vue 3, Vite, Element Plus, Axios, Vue Router`
				`@@ -0,0 +1 @@`
				`基于 Vue 3 和 Element Plus 构建的耳机品牌、型号及 OTA 升级管理的单页应用。`
				`@@ -0,0 +1 @@`
				`提供耳机品牌、型号、OTA 升级及用户管理的 RESTful API，集成 MySQL、Redis、S3 和 Meilisearch。`