新增项目文档

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/_module.yaml

@@ -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: []

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/架构设计.md

@@ -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 升级包。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/概述.md

@@ -0,0 +1 @@
+通过 Docker Compose 统一编排前后端服务，提供标准化的本地构建、远程同步及容器化部署流程。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/特殊配置与命令.md

@@ -0,0 +1,2 @@
+- **一键同步**：执行 `./scripts/upload.sh all` 将前端产物、后端源码及编排文件同步至远程服务器。
+- **服务启动**：在服务器端执行 `docker compose build --no-cache backend && docker compose up -d` 完成全量更新与启动。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/编码规范.md

@@ -0,0 +1,2 @@
+- 所有服务共享根目录 `.env` 进行环境配置，禁止在各子模块中维护独立的环境变量文件。
+- 前端静态资源通过 Nginx 托管并代理 API 请求，后端统一暴露于 8000 端口（容器内）并通过 Compose 映射至宿主机 8083。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后台前端/_module.yaml

@@ -0,0 +1,9 @@
+schema_version: 1
+module_path: frontend
+title: 音频设备管理后台前端
+scope:
+    - frontend/
+source_files: []
+depends_on: []
+related_to:
+    - path: backend

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后台前端/技术栈.md

@@ -0,0 +1 @@
+Vue 3, Vite, Element Plus, Axios, Vue Router

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后台前端/架构设计.md

@@ -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` 中的工具函数进行持久化与管理。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后台前端/概述.md

@@ -0,0 +1 @@
+基于 Vue 3 和 Element Plus 构建的耳机品牌、型号及 OTA 升级管理的单页应用。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后台前端/编码规范.md

@@ -0,0 +1,3 @@
+- API 模块按业务领域拆分（如 auth.js, brand.js），统一导出异步方法并依赖 @/utils/request 实例。
+- 视图组件采用路径映射命名规范，每个业务模块在 views 下拥有独立文件夹及 index.vue 入口文件。
+- 认证逻辑集中在 utils/auth.js，提供 getToken, isSuperAdmin, clearAuth 等原子操作供路由守卫和组件调用。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/_module.yaml

@@ -0,0 +1,9 @@
+schema_version: 1
+module_path: backend
+title: 音频设备管理后端 API
+scope:
+    - backend/
+source_files: []
+depends_on: []
+related_to:
+    - path: frontend

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/技术栈.md

@@ -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` (日志)。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/架构设计.md

@@ -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 (搜索索引) 及远程曲线服务进行交互。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/概述.md

@@ -0,0 +1 @@
+提供耳机品牌、型号、OTA 升级及用户管理的 RESTful API，集成 MySQL、Redis、S3 和 Meilisearch。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/特殊配置与命令.md

@@ -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` 创建初始超级管理员。

.qoder/repowiki/knowledge/zh/音频设备管理全栈平台/音频设备管理后端 API/编码规范.md

@@ -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'` 字符串，以区分“未提供”与“设为空”，避免意外覆盖现有数据。