修改 wiki

2026-07-09 11:16:59 +08:00
parent b4926ba148
commit 6fab4a86d4
42 changed files with 625 additions and 234 deletions
@@ -1,3 +1,20 @@
+---
+kind: build_system
+name: Docker Compose 编排与 rsync 增量部署
+category: build_system
+scope:
+    - '**'
+source_files:
+    - docker-compose.yml
+    - backend/Dockerfile
+    - frontend/Dockerfile
+    - frontend/nginx.conf
+    - scripts/upload.sh
+    - DEPLOY.md
+    - backend/package.json
+    - frontend/package.json
+---
+
 ## 1. 构建系统与工具链
 项目采用 **Docker Compose** 作为核心编排工具，结合 **pnpm** 进行依赖管理。整体架构分为前端（Vue 3 + Vite）和后端（Node.js + Express）两个独立服务。

@@ -1,15 +0,0 @@
-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: []
@@ -3,11 +3,11 @@ schema_version: 1
 locale: zh-CN
 branch: main
 nodes_managed: true
-exported_at: "2026-07-01T09:22:46Z"
+exported_at: "2026-07-09T02:41:34Z"
 modules:
    "":
-        dir_name: 音频设备管理全栈平台
-        title: 音频设备管理全栈平台
+        dir_name: 耳机品牌与 OTA 升级管理平台（前后端编排）
+        title: 耳机品牌与 OTA 升级管理平台（前后端编排）
        scope:
            - .gitignore
            - README.md
@@ -23,8 +23,8 @@ modules:
        depends_on: []
        related_to: []
    backend:
-        dir_name: 音频设备管理后端 API
-        title: 音频设备管理后端 API
+        dir_name: 耳机品牌与型号管理后端 API
+        title: 耳机品牌与型号管理后端 API
        scope:
            - backend/
        source_files: []
@@ -32,66 +32,6 @@ modules:
        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: 耳机品牌与 OTA 升级管理前端
        title: 耳机品牌与 OTA 升级管理前端
@@ -102,28 +42,3 @@ modules:
        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: []
@@ -1,13 +0,0 @@
-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: []
@@ -1,3 +1,18 @@
+---
+kind: error_handling
+name: 全栈错误处理与响应规范
+category: error_handling
+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
+---
+
 ### 1. 核心策略：统一响应结构与业务码
 该仓库采用**基于 HTTP 200 的业务状态码**模式，而非依赖 HTTP 协议层的状态码来区分业务逻辑的成功与失败。

@@ -1,11 +0,0 @@
-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: []
@@ -1,3 +1,16 @@
+---
+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/database.js
+---
+
 ## 1. 核心框架与配置
 - **框架**: 使用 `winston` 作为后端 Node.js 应用的统一日志框架。
 - **配置文件**: `backend/src/config/logger.js` 负责初始化 logger 实例。
@@ -1,14 +0,0 @@
-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: []
@@ -1,3 +1,19 @@
+---
+kind: dependency_management
+name: 基于 pnpm 与 Docker 的前后端依赖管理
+category: dependency_management
+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
+---
+
 ## 1. 核心系统与工具
 该项目采用 **pnpm** 作为前后端统一的 JavaScript/TypeScript 包管理器，并通过 **Docker Compose** 进行容器化编排。项目明确指定了 `packageManager` 字段（`pnpm@11.5.2`），利用 Corepack 机制确保开发环境与生产环境使用完全一致的包管理版本。

@@ -1,14 +0,0 @@
-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: []
@@ -1,3 +1,19 @@
+---
+kind: configuration_system
+name: 基于环境变量与 Docker Compose 的分层配置体系
+category: configuration_system
+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
+---
+
 ## 1. 核心系统与工具
 该项目采用 **环境变量（Environment Variables）** 作为唯一的配置来源，结合 **`dotenv`** 库进行本地开发时的文件加载，并通过 **Docker Compose** 在部署时注入环境变量。这种模式遵循了 [12-Factor App](https://12factor.net/zh-cn/config) 的配置原则，实现了配置与代码的分离。

@@ -0,0 +1,30 @@
+---
+kind: design
+name: 按功能边界拆分 model/index.vue 为子组件与 composable
+source: session
+category: adr
+---
+
+# 按功能边界拆分 model/index.vue 为子组件与 composable
+
+_来源：e2577ff → b4926ba 提交周期内记录的编码计划——内容为规划时意图，实现可能滞后或有出入。_
+
+**状态：** accepted
+
+## 背景
+frontend/src/views/model/index.vue 文件膨胀至 1824 行，同时承载搜索列表、5 个对话框、大量状态管理与样式，导致可读性与可维护性下降。
+
+## 决策驱动
+- 单文件过大难以维护
+- 各对话框逻辑耦合在页面中
+- 列表/搜索/分页等通用逻辑需要复用
+
+## 备选方案
+- **保持 monolithic index.vue** _（已否决）_ — 优点：改动最小；缺点：文件持续膨胀，新需求只能继续往里堆代码
+- **拆分为 components + composables 目录结构** — 优点：每个对话框独立成组件；useModelList.js 抽取列表/搜索/分页/排序/复制等共享逻辑；index.vue 仅保留编排职责（~250 行）；缺点：引入更多文件，需维护 props/emits 契约
+
+## 决策
+将 model/index.vue 按功能边界拆分为：components/ModelFormDialog.vue、EqCacheDialog.vue、PushProgressDialog.vue、CsvViewerDialog.vue、PushViewDialog.vue 五个对话框组件，以及 composables/useModelList.js 提取列表核心逻辑；index.vue 仅保留搜索表单+表格+分页模板与操作按钮的编排逻辑。
+
+## 影响
+每个对话框可独立演进与测试，useModelList.js 可在其他页面复用列表能力；代价是新增跨组件通信需通过 props/emits/ref，且目录层级加深。
@@ -1,12 +0,0 @@
-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: []
@@ -1,3 +1,17 @@
+---
+kind: frontend_style
+name: 深色玻璃拟态主题系统 (Lux Theme)
+category: frontend_style
+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
+---
+
 ## 1. 核心系统与工具
 - **UI 框架**: Vue 3 + Element Plus。
 - **样式方案**: 原生 CSS + CSS Variables (CSS Custom Properties)。
@@ -1,6 +1,6 @@
 schema_version: 1
 module_path: ""
-title: 音频设备管理全栈平台
+title: 耳机品牌与 OTA 升级管理平台（前后端编排）
 scope:
    - .gitignore
    - README.md
@@ -0,0 +1,4 @@
+- **服务编排**：`docker-compose.yml` 定义 `backend`（Node.js + Sequelize）和 `frontend`（Nginx 静态托管）两个服务，共用 `audio-network` 桥接网络，前端通过 Nginx 反向代理 `/api` 至后端。
+- **配置边界**：根目录 `.env` 为唯一环境变量源，Compose 注入后端容器；`.env.example` 提供模板，禁止子模块各自维护环境文件。
+- **存储契约**：宿主机 `/data/projects/source` 挂载至后端容器，作为 OTA 升级包的持久化共享卷，前后端以此路径为约定进行文件交互。
+- **部署流水线**：`scripts/upload.sh` 基于 rsync/ssh 将前端构建产物、后端源码与编排文件增量推送至服务器，配合 `DEPLOY.md` 形成本地→远端的标准化运维路径。
@@ -0,0 +1 @@
+通过 Docker Compose 统一编排 Vue 3 前端与 Express 后端，并以标准化脚本驱动从本地到远程服务器的增量同步与容器化部署。
@@ -1,6 +1,6 @@
 schema_version: 1
 module_path: backend
-title: 音频设备管理后端 API
+title: 耳机品牌与型号管理后端 API
 scope:
    - backend/
 source_files: []
@@ -0,0 +1 @@
+Node.js 22 (Alpine) + Express v4；Sequelize v6 + mysql2 访问 MySQL；ioredis 连接 Redis 缓存 EQ；@aws-sdk/client-s3 上传 OTA 包与测量文件；axios 调用 Meilisearch 搜索索引；jsonwebtoken 签发/验证 JWT；zod 做参数校验；winston 输出到 `logs/app.log`。
@@ -0,0 +1,4 @@
+- 入口 `src/app.js` 加载 `.env`（`config/loadEnv.js` 从仓库根目录读取）、注册 CORS/JSON/bodyLimit 中间件、挂载路由数组并调用 `sequelize.sync()` 建表后执行 `ensureBootstrapSuperAdmin` 引导超级管理员。
+- 分层组织：`routes/` 按业务域拆分（auth, brands, models, ota, blacklist, otaTargetDevice, shareCodeLogs, users, dashboard），由 `routes/index.js` 汇总导出供 app 遍历挂载；`models/` 使用 Sequelize 定义实体并通过 `index.js` 统一导出；`services/` 封装外部依赖（S3、Redis、Meilisearch、曲线服务）；`middleware/` 提供认证与请求体大小限制；`utils/` 暴露 JWT、密码哈希、统一响应格式；`validators/` 以 zod schema 校验入参。
+- 认证边界：`middleware/auth.js` 解析 Bearer token 注入 `req.user`，受保护路由在各自文件中通过 `router.use(authMiddleware)` 全局启用，仅 `/health`、根路径等公开接口例外；`requireSuperAdmin` 用于超管专用端点。
+- 启动流程：`start.sh` → `node src/app.js` → `loadEnv` → `sequelize.sync()` → `userBootstrap.ensureBootstrapSuperAdmin()` → `app.listen(8083)`，异常时降级继续运行。
@@ -0,0 +1 @@
+基于 Express + Sequelize 的 RESTful 服务，提供耳机品牌、型号、OTA 升级、用户与黑名单管理的后端接口。
@@ -0,0 +1 @@
+包管理器锁定为 `pnpm@11.5.2`，安装需 `pnpm install --frozen-lockfile`；本地开发可用 `pnpm dev`（nodemon 热重载），生产通过 `start.sh`/`stop.sh`/`restart.sh` 或 Docker 镜像启动；首次启动若 `dashboard_user` 为空则根据 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 环境变量创建初始超级管理员。
@@ -0,0 +1,5 @@
+- 所有 API 返回统一 JSON 结构，包含 `code`（1:成功 / 0:错误 / 2:无数据）、`msg` 和 `data` 字段，由 `utils/response.js` 的 `ApiResponse` 生成。
+- 受保护路由在各自文件顶部通过 `router.use(authMiddleware)` 全局启用 JWT 校验，仅健康检查等公开接口例外。
+- 更新操作显式判断请求体字段是否为 `undefined` 或 `'null'` 字符串，区分“未提供”与“设为空”，避免覆盖现有值。
+- 关键业务动作（登录、CRUD、权限拒绝）通过 `logger.info/warn/error` 记录到 `logs/app.log`，错误堆栈附带上下文信息。
+- 环境变量集中通过 `config/loadEnv.js` 从仓库根目录 `.env` 加载，Docker 场景下由 compose env_file 注入而不覆盖已有变量。
@@ -1,4 +0,0 @@
- **服务编排**：使用 `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 升级包。
@@ -1 +0,0 @@
-通过 Docker Compose 统一编排前后端服务，结合标准化部署脚本实现从本地开发到远程服务器的自动化同步与容器化运维。
@@ -1,2 +0,0 @@
- **一键同步**：执行 `./scripts/upload.sh all` 将前端产物、后端源码及编排文件同步至远程服务器。
- **服务启动**：在服务器端执行 `docker compose build --no-cache backend && docker compose up -d` 完成全量更新与启动。
@@ -1,2 +0,0 @@
- 所有服务共享根目录 `.env` 进行环境配置，禁止在各子模块中维护独立的环境变量文件。
- 前端静态资源通过 Nginx 托管并代理 API 请求，后端统一暴露于 8000 端口（容器内）并通过 Compose 映射至宿主机 8083。
@@ -1,5 +0,0 @@
- **运行时与框架**：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` (日志)。
@@ -1,5 +0,0 @@
- **分层架构**：采用经典的 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 (搜索索引) 及远程曲线服务进行交互。
@@ -1 +0,0 @@
-提供耳机品牌、型号、OTA 升级及用户管理的 RESTful API，集成 MySQL、Redis、S3 和 Meilisearch。
@@ -1,3 +0,0 @@
- **依赖管理**：使用 `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` 创建初始超级管理员。
@@ -1,4 +0,0 @@
- 统一响应格式：所有 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 统一编排 Vue 3 前端与 Express 后端，并以标准化脚本驱动从本地到远程服务器的增量同步与容器化部署。`
				`@@ -0,0 +1 @@`
				Node.js 22 (Alpine) + Express v4；Sequelize v6 + mysql2 访问 MySQL；ioredis 连接 Redis 缓存 EQ；@aws-sdk/client-s3 上传 OTA 包与测量文件；axios 调用 Meilisearch 搜索索引；jsonwebtoken 签发/验证 JWT；zod 做参数校验；winston 输出到 `logs/app.log`。
				`@@ -0,0 +1 @@`
				`基于 Express + Sequelize 的 RESTful 服务，提供耳机品牌、型号、OTA 升级、用户与黑名单管理的后端接口。`
				`@@ -0,0 +1 @@`
				包管理器锁定为 `pnpm@11.5.2`，安装需 `pnpm install --frozen-lockfile`；本地开发可用 `pnpm dev`（nodemon 热重载），生产通过 `start.sh`/`stop.sh`/`restart.sh` 或 Docker 镜像启动；首次启动若 `dashboard_user` 为空则根据 `DASHBOARD_ADMIN_USERNAME/PASSWORD` 环境变量创建初始超级管理员。
				`@@ -1 +0,0 @@`
				`通过 Docker Compose 统一编排前后端服务，结合标准化部署脚本实现从本地开发到远程服务器的自动化同步与容器化运维。`
				`@@ -1 +0,0 @@`
				`提供耳机品牌、型号、OTA 升级及用户管理的 RESTful API，集成 MySQL、Redis、S3 和 Meilisearch。`