添加 uipro，更新 wiki

2026-07-10 11:25:45 +08:00
parent 6bb39e9172
commit f88ff46427
163 changed files with 30244 additions and 151 deletions
@@ -3,23 +3,14 @@ schema_version: 1
 locale: zh-CN
 branch: main
 nodes_managed: true
-exported_at: "2026-07-09T02:41:34Z"
+exported_at: "2026-07-10T03:11:01Z"
 modules:
    "":
-        dir_name: 耳机品牌与 OTA 升级管理平台（前后端编排）
-        title: 耳机品牌与 OTA 升级管理平台（前后端编排）
-        scope:
-            - .gitignore
-            - README.md
-            - DEPLOY.md
-            - docker-compose.yml
-            - scripts/
-            - .env
-            - .env.example
+        dir_name: 音频设备管理仪表盘（前后端单体仓库）
+        title: 音频设备管理仪表盘（前后端单体仓库）
+        scope: []
        source_files: []
-        children:
-            - backend
-            - frontend
+        children: []
        depends_on: []
        related_to: []
    backend:
@@ -0,0 +1,41 @@
+---
+kind: dependency_management
+name: pnpm 多包依赖管理（前后端双 package.json）
+category: dependency_management
+scope:
+    - '**'
+source_files:
+    - backend/package.json
+    - backend/pnpm-lock.yaml
+    - frontend/package.json
+    - frontend/pnpm-workspace.yaml
+    - frontend/pnpm-lock.yaml
+    - frontend/package-lock.json
+---
+
+本仓库采用 pnpm 作为统一的 Node.js 包管理器，前后端各自维护独立的 package.json，通过 lockfile 锁定依赖版本，未启用 monorepo workspace 模式。
+
+1. 使用的系统/工具
+- 包管理器：pnpm v11.5.2，在 backend/package.json 与 frontend/package.json 中均通过 packageManager 字段声明，确保团队成员使用一致版本。
+- Lockfile：后端使用 pnpm-lock.yaml（lockfileVersion 9.0），前端同时存在 pnpm-lock.yaml 与 package-lock.json（后者为历史遗留）。
+- 构建工具：前端基于 Vite（vite.config.js），后端无构建步骤，直接运行 src/app.js。
+
+2. 关键文件
+- backend/package.json — 后端依赖声明（Express、Sequelize、MySQL2、AWS S3 SDK、Redis、Zod 等）
+- backend/pnpm-lock.yaml — 后端精确锁定的依赖树
+- frontend/package.json — 前端依赖声明（Vue3、Element Plus、Axios、Vite 等）
+- frontend/pnpm-workspace.yaml — 仅开启 allowBuilds.esbuild: true，未定义任何 workspace 包
+- frontend/pnpm-lock.yaml / frontend/package-lock.json — 前端锁文件（二者并存）
+
+3. 架构与约定
+- 双包结构：前后端各自独立，不存在共享的 packages/ 或 workspace: 引用；pnpm-workspace.yaml 为空配置，说明当前不是 monorepo。
+- 版本策略：所有依赖均采用 ^ 语义化版本范围（如 express: ^4.21、vue: ^3.3.4），实际安装版本由 lockfile 固定。
+- 私有源/代理：未发现 .npmrc、.pnpmrc 或 registry 相关配置，默认使用 npm 官方源；也未见 @scope 私有包引用。
+- 缓存：根目录存在 .pnpm-store/v11/，表明 pnpm 全局存储已启用。
+
+4. 开发者应遵循的规则
+- 统一使用 pnpm 安装/更新依赖，避免混用 npm/yarn，以免生成冲突的 lockfile。
+- 新增依赖时只修改对应子目录的 package.json，提交后让 CI 重新生成 lockfile。
+- 不要手动编辑 lockfile；如需升级，使用 pnpm up <pkg> 或 pnpm update。
+- 清理前端的 package-lock.json，统一以 pnpm-lock.yaml 为准，消除双锁文件带来的歧义。
+- 若未来引入共享包，应在 pnpm-workspace.yaml 中显式声明 workspace，并迁移到 monorepo 模式。
@@ -0,0 +1,32 @@
+---
+kind: error_handling
+name: 前后端统一错误响应与拦截机制
+category: error_handling
+scope:
+    - '**'
+source_files:
+    - backend/src/utils/response.js
+    - backend/src/middleware/auth.js
+    - backend/src/app.js
+    - frontend/src/utils/request.js
+---
+
+本仓库采用「后端统一响应体 + 前端 Axios 拦截器」的轻量级错误处理方案，未引入专门的错误类型库或全局异常中间件。
+
+**后端（Express）**
+- 统一响应封装：`backend/src/utils/response.js` 提供 `ApiResponse.success / error / noData` 三个工厂方法，约定 `code=1` 成功、`code=0` 业务错误、`code=2` 无数据；`PageData` 用于分页结构。
+- 路由层自行 try/catch：各 `routes/*.js` 在控制器内捕获异常，记录 `logger.error(e.message)` 后返回 `ApiResponse.error(...)`，错误消息多为硬编码中文提示，未使用 HTTP 状态码区分语义。
+- 认证中间件 `middleware/auth.js` 单独处理鉴权错误：401 返回 `{ detail: '...' }`，403 返回权限不足信息，与业务错误体结构不同。
+- 服务层 `services/*.js` 直接 `throw new Error(...)` 向上抛出具体错误（如 Redis/S3/曲线接口失败），由调用方路由捕获。
+- 应用入口 `app.js` 仅在启动阶段同步数据库时 try/catch，未注册全局 Express 错误处理中间件（`app.use((err, req, res, next) => ...)`）。
+
+**前端（Vue3 + Axios）**
+- `frontend/src/utils/request.js` 通过 Axios 拦截器集中处理：
+  - 请求拦截：自动注入 `Authorization: Bearer <token>`，跳过 `/auth/login`。
+  - 响应拦截：当 `res.code === 0` 时，若 `config.skipErrorToast` 未设置则弹出 `ElMessage.error`，并将 `responseData` 挂载到抛出的 Error 对象上供上层消费。
+  - HTTP 错误：401 清除本地 token、跳转登录页并携带 redirect；403 显示警告；其他网络错误统一 `ElMessage.error`。
+- 业务 API 模块（`frontend/src/api/*.js`）基于此 request 实例发起请求，依赖 Promise reject 分支处理业务错误。
+
+**设计决策与不足**
+- 优点：前后端对 `code/msg/data` 协议一致，前端拦截器屏蔽了重复的错误提示逻辑。
+- 不足：缺少统一的错误码枚举、HTTP 状态码未与业务错误解耦、未定义全局错误中间件导致未捕获异常可能返回默认 HTML 500 页面。
@@ -0,0 +1,47 @@
+---
+kind: logging_system
+name: 基于 Winston 的日志系统
+category: logging_system
+scope:
+    - '**'
+source_files:
+    - backend/src/config/logger.js
+    - backend/src/app.js
+    - backend/src/config/database.js
+    - backend/package.json
+---
+
+## 1. 使用的系统与框架
+- 后端采用 **Winston v3** 作为统一日志框架，通过 `backend/src/config/logger.js` 集中创建并导出单例 logger。
+- 前端（Vue3）未发现专用日志库，未在前端代码中引入结构化日志输出。
+- Sequelize 在开发环境将 SQL 查询直接 `console.log` 到控制台，生产环境关闭 SQL 日志。
+
+## 2. 核心文件与包
+- `backend/src/config/logger.js` — Winston 实例定义、格式与传输配置
+- `backend/src/app.js` — 应用启动时记录数据库同步、服务监听等关键事件
+- `backend/package.json` — 依赖声明 `winston: ^3.14`
+- `backend/logs/app.log` — 默认文件日志输出路径
+- `backend/src/config/database.js` — Sequelize 的 `logging` 开关逻辑
+
+## 3. 架构与约定
+- **单例导出**：`logger.js` 使用 `winston.createLogger()` 创建全局 logger，并通过 `module.exports = logger` 供各模块 `require('../config/logger')` 复用。
+- **日志级别**：全局默认 level 为 `info`；业务代码中使用 `logger.info / warn / error` 三个级别，未见 `debug` 调用。
+- **输出格式**：时间戳 + 级别 + 消息 + 可选 JSON meta 字段，形如：
+  ```
+  2026-06-09 12:34:56 - info - User admin logged in {}
+  ```
+- **双通道输出**：同时写入 Console 和文件 `backend/logs/app.log`，编码 UTF-8。
+- **无按级别/日期分片**：当前仅一个 `app.log` 文件，未启用 `FileTransport` 的 `maxsize`、`maxFiles`、`filename` 模板等滚动策略。
+- **Sequelize SQL 日志**：仅在 `isDevelopment` 时开启，输出到 `console.log`，不经过 Winston。
+- **中间件层**：未集成 Express 请求日志中间件（如 `morgan`），HTTP 访问日志未统一采集。
+
+## 4. 开发者应遵循的规则
+- **统一入口**：所有日志必须通过 `const logger = require('../config/logger')` 获取，禁止直接使用 `console.log` 输出业务日志。
+- **级别选择**：
+  - `info`：正常业务流程事件（登录成功、密码修改、数据操作完成等）
+  - `warn`：可恢复异常或潜在问题（登录失败、参数校验警告等）
+  - `error`：不可恢复错误（数据库异常、外部服务调用失败等）
+- **结构化字段**：通过第三个参数传入对象以附加上下文，例如 `logger.warn({ username, ip }, 'Login failed')`，该对象会被序列化为 JSON 追加到消息末尾。
+- **敏感信息**：避免在日志中记录明文密码、完整 token 等敏感内容。
+- **SQL 调试**：如需查看底层 SQL，确保环境变量处于开发模式以使 Sequelize logging 生效；生产环境应保持关闭以避免性能损耗。
+- **日志轮转**：当前未配置自动轮转，部署时应配合外部工具（如 `logrotate`、Docker log driver）管理 `backend/logs/app.log` 大小。
@@ -0,0 +1,89 @@
+---
+kind: build_system
+name: 构建与部署体系（Docker Compose + pnpm + Vite）
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/vite.config.js
+    - scripts/upload.sh
+    - DEPLOY.md
+    - backend/package.json
+    - frontend/package.json
+---
+
+## 1. 使用的系统与方法
+
+- **包管理器**：pnpm@11.5.2，前后端均通过 `packageManager` 字段锁定版本。
+- **前端构建**：Vite 6 + Vue 3，开发端口 3000，生产构建产物输出到 `frontend/dist/`，并通过 Rollup `manualChunks` 将 vue、element-plus 等拆分为独立 chunk。
+- **后端运行**：Express + Sequelize，入口 `backend/src/app.js`，默认监听 8000（容器内），本地开发可通过 `.env` 的 `PORT=8083` 覆盖。
+- **容器编排**：Docker Compose 定义两个服务——`backend`（node:22-alpine）和 `frontend`（nginx:alpine），共享自定义 bridge 网络 `audio-network`。
+- **发布脚本**：`scripts/upload.sh` 基于 rsync+ssh 将前端 dist、后端源码、compose 文件同步至远程服务器 `/data/project/dashboard/`。
+
+## 2. 关键文件与位置
+
+| 类别 | 文件 | 作用 |
+|------|------|------|
+| 编排 | `docker-compose.yml` | 定义 backend/frontend 服务、端口映射、日志轮转、数据卷挂载 |
+| 后端镜像 | `backend/Dockerfile` | node:22-alpine，仅安装 prod 依赖，CMD 启动 `src/app.js` |
+| 前端镜像 | `frontend/Dockerfile` | 多阶段构建：node:18-alpine 构建 → nginx:alpine 托管静态资源 |
+| 前端构建配置 | `frontend/vite.config.js` | 开发代理 `/api→localhost:8083`、chunk 拆分、别名 `@` |
+| 上传脚本 | `scripts/upload.sh` | rsync 推送 frontend/backend/compose 三套预设目标 |
+| 部署文档 | `DEPLOY.md` | 完整的首次部署、增量更新、环境变量说明、目录结构约定 |
+| 后端脚本 | `backend/start.sh / stop.sh / restart.sh` | 非 Docker 场景下的进程启停辅助 |
+
+## 3. 架构与约定
+
+### 3.1 构建流水线
+
+```
+本地开发
+  ├─ frontend/pnpm dev (vite, :3000) → 代理 /api → localhost:8083
+  └─ backend/pnpm start (node src/app.js, :8000 或 .env PORT)
+
+本地构建
+  ├─ pnpm --dir frontend build → frontend/dist/
+  └─ scripts/upload.sh [frontend|backend|compose|all]
+
+服务器部署
+  ├─ docker compose build --no-cache backend   # 首次或依赖变更
+  ├─ docker compose up -d                      # 启动全部服务
+  └─ docker compose restart frontend           # 仅前端热更
+```
+
+- 前端采用**多阶段 Docker 构建**，最终镜像仅包含 nginx + 静态文件，体积最小化。
+- 后端镜像使用 `--frozen-lockfile --prod` 安装，确保构建可重复且不携带 devDependencies。
+- 宿主机通过 volume 挂载 `/data/projects/source` 给后端容器，用于 X9 OTA 升级包本地存储；前端 `dist/` 与 `nginx.conf` 也通过 volume 挂载，避免重建镜像。
+
+### 3.2 端口与环境变量约定
+
+| 组件 | 容器内端口 | 宿主机映射 | 备注 |
+|------|-----------|-----------|------|
+| frontend (nginx) | 80 | 8082 | 反向代理 `/api` 到 `http://backend:8000` |
+| backend (Node) | 8000 | 8083 | 由 Compose 强制覆盖 `PORT=8000` |
+| 本地开发 (vite) | 3000 | — | 通过 proxy 转发 `/api` 到 8083 |
+
+- 所有环境变量统一放在根目录 `.env`，Compose 通过 `env_file` 注入，不再各自维护 `.env`。
+- 敏感信息（JWT_SECRET、数据库密码等）不随 `upload.sh` 上传，需在服务器单独维护。
+
+### 3.3 上传策略
+
+`scripts/upload.sh` 定义了三个预设集合：
+- `frontend`：仅 `frontend/dist/`
+- `backend`：`backend/src/` + `package.json` + `pnpm-lock.yaml`（不含 Dockerfile）
+- `compose`：`docker-compose.yml`
+
+支持 `-n` dry-run 预览、任意路径透传、自动创建远端目录。
+
+## 4. 开发者应遵循的规则
+
+1. **新增依赖**：在对应子模块执行 `pnpm add ...`，确保 `pnpm-lock.yaml` 提交到 Git，以便 `--frozen-lockfile` 构建成功。
+2. **修改前端路由/样式**：直接 `pnpm dev` 本地调试，无需重新构建镜像；生产发布前执行 `pnpm build` 并 `./scripts/upload.sh frontend`。
+3. **修改后端接口**：`./scripts/upload.sh backend` 后在服务器执行 `docker compose build --no-cache backend && docker compose up -d backend`。
+4. **修改 Compose 配置**：`./scripts/upload.sh compose` 后 `docker compose up -d` 即可生效。
+5. **不要**在代码中硬编码端口或路径，一律通过 `.env` 或 Compose `environment` 注入。
+6. **OTA 包存放**：仅通过 volume 挂载的 `/data/projects/source` 写入，不要改动 Dockerfile 中的 COPY 范围。
+7. **本地非 Docker 开发**：先 `cd backend && pnpm start`，再 `cd frontend && pnpm dev`，确保根目录 `.env` 中 `PORT=8083`。
@@ -0,0 +1,47 @@
+---
+kind: configuration_system
+name: 环境变量与配置加载体系
+category: configuration_system
+scope:
+    - '**'
+source_files:
+    - backend/src/app.js
+    - backend/src/config/loadEnv.js
+    - backend/src/config/env.js
+    - backend/src/config/database.js
+    - backend/src/config/redis.js
+    - .env.example
+    - docker-compose.yml
+---
+
+## 系统概览
+本仓库采用「进程级 .env 文件 + 环境变量」的轻量配置方案，由后端在启动时统一加载，未引入第三方配置中心或 YAML/JSON 配置文件。所有运行时参数通过 `process.env` 注入，开发环境与生产环境通过 `APP_ENV` 区分。
+
+## 核心机制
+- **统一入口加载**：`backend/src/app.js` 首行 `require('./config/loadEnv')`，确保应用启动前完成 `.env` 解析。
+- **dotenv 加载策略**：`loadEnv.js` 固定从仓库根目录读取 `.env`（`path.resolve(__dirname, '../../../.env')`），仅在文件存在时调用 `dotenv.config()`；Docker 部署时通过 `docker-compose.yml` 的 `env_file` 注入，容器内无 `.env` 也不会覆盖已存在的环境变量。
+- **环境判断工具**：`config/env.js` 暴露 `APP_ENV`、`isDevelopment`、`isProduction`，供各模块按环境切换行为（如数据库日志开关）。
+
+## 配置项分类与约定
+| 类别 | 关键变量 | 默认值 / 说明 |
+|---|---|---|
+| 数据库 | `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USER`, `DATABASE_PASSWORD` | MySQL，Sequelize 直连，`dialectOptions.charset='utf8mb4'`，开发模式打印 SQL |
+| 应用 | `APP_NAME`, `APP_ENV`, `PORT` | `APP_ENV=development|production`；本地默认 8083，Docker 内 8000 |
+| 认证 | `JWT_SECRET`, `DASHBOARD_ADMIN_USERNAME`, `DASHBOARD_ADMIN_PASSWORD` | 首次启动自动创建超级管理员 |
+| S3 存储 | `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_OTA_BUCKET`, `AWS_S3_MEASUREMENT_BUCKET` | 正式环境可通过 IAM 角色免 AK/SK 访问 |
+| OTA 地址 | `OTA_X8_PUBLIC_BASE`, `OTA_X9_URL_BASE`, `OTA_UPLOAD_DIR` | X8/X9 升级包基 URL；上传目录仅生产环境需显式配置 |
+| Redis 缓存 | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_EQ_DB` | ioredis 单例，连接失败记录错误日志 |
+| 外部服务 | `MEILISEARCH_*`, `CURVE_API_BASE_URL` | 搜索与曲线 API 基础地址 |
+
+## 架构与约定
+- **单一来源**：`.env.example` 是配置清单，实际 `.env` 不应提交到版本库（已在 `.gitignore` 中忽略）。
+- **分层组织**：`backend/src/config/` 下每个子模块只负责自身依赖的配置读取（database、redis、logger），不互相耦合。
+- **环境变量优先**：所有配置均从 `process.env` 读取，并带合理默认值，保证本地可零配置运行。
+- **Docker 集成**：`docker-compose.yml` 通过 `env_file: [.env]` 和 `environment:` 覆盖端口与环境变量，实现同一份 `.env` 同时驱动本地与容器。
+
+## 开发者规则
+1. 新增配置项先在 `.env.example` 中添加注释与默认值，再在对应 `config/*.js` 中读取。
+2. 敏感信息（密码、密钥）一律走环境变量，禁止硬编码或写入代码。
+3. 使用 `APP_ENV` 做环境分支逻辑，不要直接检查主机名或路径。
+4. Docker 部署时通过 compose 的 `environment` 覆盖必要变量，保持 `.env` 最小化。
+5. 若某配置有默认值且允许空值，务必在读取处提供 fallback，避免启动期崩溃。
@@ -0,0 +1,7 @@
+schema_version: 1
+module_path: ""
+title: 音频设备管理仪表盘（前后端单体仓库）
+scope: []
+source_files: []
+depends_on: []
+related_to: []
@@ -0,0 +1 @@
+后端：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 静态托管）。
@@ -0,0 +1,5 @@
+仓库采用前后端分离的单体结构：
+- `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 服务，无跨包反向引用。
@@ -0,0 +1 @@
+基于 Vue3 + Express/Sequelize 的耳机品牌、型号、OTA 与用户管理后台，提供曲线上传、S3 存储与 Element Plus 驱动的 Web 界面。
@@ -0,0 +1 @@
+开发：`pnpm install` 后分别进入 `backend` 和 `frontend` 执行 `pnpm dev`；生产：`cd frontend && pnpm build` 生成 `dist/`，再 `docker compose up -d --build` 启动双容器，需提前准备 `.env`（参考 `.env.example`）并挂载 `/data/projects/source` 供 S3 本地模拟访问。
@@ -0,0 +1,5 @@
+- 后端路由以独立文件暴露 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 @@`
				`后端：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 静态托管）。`
				`@@ -0,0 +1 @@`
				`基于 Vue3 + Express/Sequelize 的耳机品牌、型号、OTA 与用户管理后台，提供曲线上传、S3 存储与 Element Plus 驱动的 Web 界面。`
				`@@ -0,0 +1 @@`
				开发：`pnpm install` 后分别进入 `backend` 和 `frontend` 执行 `pnpm dev`；生产：`cd frontend && pnpm build` 生成 `dist/`，再 `docker compose up -d --build` 启动双容器，需提前准备 `.env`（参考 `.env.example`）并挂载 `/data/projects/source` 供 S3 本地模拟访问。