修改 wiki

2026-07-09 11:16:59 +08:00
parent b4926ba148
commit 6fab4a86d4
42 changed files with 625 additions and 234 deletions
@@ -0,0 +1,399 @@
+# 开发指南
+
+<cite>
+**本文引用的文件**
+- [README.md](file://README.md)
+- [DEPLOY.md](file://DEPLOY.md)
+- [docker-compose.yml](file://docker-compose.yml)
+- [backend/package.json](file://backend/package.json)
+- [frontend/package.json](file://frontend/package.json)
+- [backend/src/app.js](file://backend/src/app.js)
+- [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
+- [backend/src/config/env.js](file://backend/src/config/env.js)
+- [backend/src/routes/index.js](file://backend/src/routes/index.js)
+- [backend/src/middleware/auth.js](file://backend/src/middleware/auth.js)
+- [backend/src/services/userBootstrap.js](file://backend/src/services/userBootstrap.js)
+- [frontend/vite.config.js](file://frontend/vite.config.js)
+- [frontend/src/main.js](file://frontend/src/main.js)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js)
+- [scripts/upload.sh](file://scripts/upload.sh)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本开发指南面向参与“Audio Dashboard”项目的开发者，提供从环境搭建、代码规范、开发流程、测试策略到部署与运维的全流程指导。项目采用前后端分离架构：前端基于 Vue 3 + Vite，后端基于 Node.js + Express，通过 Docker Compose 进行编排，Nginx 提供静态资源与反向代理。
+
+## 项目结构
+项目采用多模块组织方式，根目录包含后端、前端、脚本与部署编排文件。关键目录与职责如下：
+- backend：后端 Node.js 应用，包含配置、中间件、模型、路由、服务、工具与验证器等。
+- frontend：前端 Vue 3 应用，包含 API 封装、组件、布局、路由、样式与视图。
+- scripts：部署与同步脚本，支持一键上传与预览模式。
+- docker-compose.yml：服务编排定义，包含后端 API 与前端 Nginx 服务。
+- DEPLOY.md：部署与运维指南，涵盖首次部署、更新部署、常见问题与本地开发。
+
+```mermaid
+graph TB
+subgraph "根目录"
+DC["docker-compose.yml"]
+DEP["DEPLOY.md"]
+SCR["scripts/upload.sh"]
+end
+subgraph "后端 backend"
+BPJ["backend/package.json"]
+APP["backend/src/app.js"]
+CFG["backend/src/config/"]
+MID["backend/src/middleware/"]
+MOD["backend/src/models/"]
+RT["backend/src/routes/"]
+SVC["backend/src/services/"]
+UTL["backend/src/utils/"]
+VAL["backend/src/validators/"]
+end
+subgraph "前端 frontend"
+FPJ["frontend/package.json"]
+VCFG["frontend/vite.config.js"]
+MAIN["frontend/src/main.js"]
+ROUTER["frontend/src/router/index.js"]
+API["frontend/src/api/"]
+CMP["frontend/src/components/"]
+LYT["frontend/src/layout/"]
+VIEWS["frontend/src/views/"]
+STY["frontend/src/styles/"]
+end
+DC --> APP
+DC --> VCFG
+APP --> RT
+APP --> CFG
+APP --> MID
+APP --> SVC
+RT --> MID
+RT --> MOD
+RT --> SVC
+RT --> VAL
+MAIN --> ROUTER
+MAIN --> API
+MAIN --> CMP
+MAIN --> LYT
+MAIN --> VIEWS
+MAIN --> STY
+```
+
+图表来源
+- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+
+章节来源
+- [README.md:1-94](file://README.md#L1-L94)
+- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
+- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
+
+## 核心组件
+- 后端入口与生命周期
+  - 应用入口负责加载环境、初始化日志、同步数据库表、引导超级管理员，并启动 HTTP 服务。
+  - 关键点：健康检查接口、根路径响应、统一 CORS 配置、请求体大小限制中间件。
+- 路由聚合
+  - 路由按功能模块拆分并在入口集中注册，便于扩展与维护。
+- 认证中间件
+  - 基于 Bearer Token 的鉴权，支持超级管理员权限校验。
+- 环境加载
+  - 统一从项目根目录加载 .env，支持本地开发与 Docker 环境差异。
+- 前端应用与路由
+  - 基于 Vue 3 + Element Plus，内置路由守卫实现登录态与权限控制。
+  - Vite 开发服务器配置了 /api 代理到后端端口。
+
+章节来源
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [backend/src/routes/index.js:1-13](file://backend/src/routes/index.js#L1-L13)
+- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
+- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
+
+## 架构总览
+系统采用前后端分离与容器化部署：
+- 前端：Nginx 静态托管，通过 /api 代理转发至后端。
+- 后端：Node.js + Express，提供 REST API，连接数据库、缓存与对象存储。
+- 编排：Docker Compose 统一管理服务生命周期与网络。
+- 部署：提供本地构建 + 上传脚本与一键部署流程。
+
+```mermaid
+graph TB
+Browser["浏览器"] --> Nginx["Nginx 前端服务<br/>端口 8082 → 80"]
+Nginx --> API["后端 API 服务<br/>端口 8083 → 8000"]
+subgraph "容器网络"
+Nginx
+API
+end
+API --> DB["MySQL 数据库"]
+API --> REDIS["Redis 缓存"]
+API --> S3["AWS S3 存储"]
+API --> MEILI["Meilisearch 搜索引擎"]
+```
+
+图表来源
+- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
+- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
+
+## 详细组件分析
+
+### 后端应用与启动流程
+- 加载环境变量：优先读取根目录 .env，确保开发与生产一致性。
+- 初始化日志、数据库与超级管理员引导。
+- 启动 HTTP 服务器，提供根路径与健康检查接口。
+
+```mermaid
+sequenceDiagram
+participant Entrypoint as "入口(app.js)"
+participant Env as "环境加载(loadEnv.js)"
+participant DB as "数据库(sequelize)"
+participant Boot as "引导(userBootstrap.js)"
+participant Server as "HTTP 服务器"
+Entrypoint->>Env : "加载根目录 .env"
+Entrypoint->>DB : "同步数据库表"
+Entrypoint->>Boot : "创建超级管理员"
+Entrypoint->>Server : "监听端口并启动"
+Server-->>Entrypoint : "返回运行状态"
+```
+
+图表来源
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
+- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
+
+章节来源
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
+- [backend/src/services/userBootstrap.js:1-28](file://backend/src/services/userBootstrap.js#L1-L28)
+
+### 认证与权限控制
+- 鉴权中间件：解析 Authorization 头，校验 Bearer Token 有效性与过期时间。
+- 超级管理员校验：对特定路由进行权限拦截。
+- 前端路由守卫：根据登录态与角色重定向或拒绝访问。
+
+```mermaid
+flowchart TD
+Start(["进入受保护路由"]) --> CheckAuth["检查是否需要登录"]
+CheckAuth --> |否| Allow["放行"]
+CheckAuth --> |是| HasToken{"是否存在有效 Token"}
+HasToken --> |否| RedirectLogin["重定向到登录页"]
+HasToken --> |是| NeedSA{"是否需要超级管理员"}
+NeedSA --> |否| Allow
+NeedSA --> |是| IsSA{"是否为超级管理员"}
+IsSA --> |否| ToHome["重定向到首页"]
+IsSA --> |是| Allow
+Allow --> End(["继续导航"])
+RedirectLogin --> End
+ToHome --> End
+```
+
+图表来源
+- [frontend/src/router/index.js:64-88](file://frontend/src/router/index.js#L64-L88)
+- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+
+章节来源
+- [backend/src/middleware/auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
+- [frontend/src/router/index.js:1-91](file://frontend/src/router/index.js#L1-L91)
+
+### 前端应用与开发体验
+- 应用入口：注册 Element Plus、路由、主题样式，完成首屏渲染控制。
+- 开发服务器：Vite 提供热更新与 /api 代理，便于联调后端。
+- 路由设计：菜单驱动的权限路由，支持超级管理员专属页面。
+
+```mermaid
+sequenceDiagram
+participant Browser as "浏览器"
+participant Vite as "Vite 开发服务器"
+participant Proxy as "代理(/api)"
+participant Backend as "后端 API"
+Browser->>Vite : "访问 /"
+Vite-->>Browser : "返回首页"
+Browser->>Vite : "访问 /api/*"
+Vite->>Proxy : "转发到 http : //localhost : 8083"
+Proxy->>Backend : "请求后端接口"
+Backend-->>Proxy : "返回数据"
+Proxy-->>Vite : "透传响应"
+Vite-->>Browser : "渲染页面"
+```
+
+图表来源
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
+
+章节来源
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [frontend/vite.config.js:1-27](file://frontend/vite.config.js#L1-L27)
+
+### 部署与上传脚本
+- 支持按模块选择性上传：前端、后端、编排文件。
+- 支持虚拟执行预览同步结果，避免误操作。
+- 默认上传到服务器指定根目录，支持自定义 SSH 密钥与远端路径。
+
+```mermaid
+flowchart TD
+CLI["命令行参数"] --> Resolve["解析预设/路径"]
+Resolve --> BuildList["生成待同步列表"]
+BuildList --> DryRun{"是否预览模式"}
+DryRun --> |是| Preview["打印预览信息"]
+DryRun --> |否| Sync["rsync 同步"]
+Preview --> Done["完成"]
+Sync --> Done
+```
+
+图表来源
+- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
+
+章节来源
+- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
+
+## 依赖分析
+- 后端依赖
+  - Web 框架与工具：Express、CORS、Sequelize、MySQL2、Axios、Dotenv、Zod、Winston、IORedis。
+  - 包管理：pnpm，锁定版本以保证一致性。
+- 前端依赖
+  - 框架与 UI：Vue 3、Element Plus、Vue Router。
+  - 构建与开发：Vite、@vitejs/plugin-vue。
+- 运行时与编排
+  - Docker Compose 管理服务、网络与卷，Nginx 提供静态资源与代理。
+
+```mermaid
+graph LR
+subgraph "后端"
+BE_PKG["backend/package.json"]
+BE_EXP["Express"]
+BE_DB["Sequelize/MySQL2"]
+BE_LOG["Winston 日志"]
+BE_CACHE["IORedis"]
+BE_S3["@aws-sdk/client-s3"]
+end
+subgraph "前端"
+FE_PKG["frontend/package.json"]
+FE_VUE["Vue 3"]
+FE_ROUTER["Vue Router"]
+FE_ELE["Element Plus"]
+FE_VITE["Vite"]
+end
+BE_PKG --> BE_EXP
+BE_PKG --> BE_DB
+BE_PKG --> BE_LOG
+BE_PKG --> BE_CACHE
+BE_PKG --> BE_S3
+FE_PKG --> FE_VUE
+FE_PKG --> FE_ROUTER
+FE_PKG --> FE_ELE
+FE_PKG --> FE_VITE
+```
+
+图表来源
+- [backend/package.json:1-29](file://backend/package.json#L1-L29)
+- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
+
+章节来源
+- [backend/package.json:1-29](file://backend/package.json#L1-L29)
+- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
+
+## 性能考虑
+- 服务端
+  - 合理设置数据库连接池与查询索引，避免慢查询。
+  - 使用缓存层（Redis）降低热点数据读取压力。
+  - 控制日志级别与输出频率，避免 I/O 抖动。
+- 客户端
+  - 按需加载组件与路由，减少首屏体积。
+  - 图片与静态资源启用压缩与缓存策略。
+- 编排与部署
+  - 使用只读挂载静态资源，避免不必要的写入。
+  - 合理设置容器日志轮转，控制磁盘占用。
+
+## 故障排查指南
+- 前端页面空白
+  - 检查前端构建产物是否上传成功、Nginx 配置是否正确。
+  - 查看前端容器日志定位问题。
+- API 请求失败
+  - 确认后端服务状态、数据库/缓存/搜索引擎连接情况。
+  - 核对 Nginx 代理目标与端口映射。
+- 后端构建失败（pnpm/Node 版本）
+  - 确认上传了 package.json 与 pnpm-lock.yaml。
+  - 检查后端镜像基础版本与 Node 版本匹配。
+- 修改 .env 后不生效
+  - 强制重建后端容器以重新注入环境变量。
+- 停止与重启
+  - 使用 Compose 停止或重启相关服务。
+
+章节来源
+- [DEPLOY.md:226-256](file://DEPLOY.md#L226-L256)
+
+## 结论
+本指南提供了从开发到部署的全链路实践建议。建议团队在日常工作中遵循统一的代码规范、版本与分支策略，并结合自动化测试与日志监控提升交付质量与稳定性。
+
+## 附录
+
+### 开发环境配置
+- 本地开发
+  - 后端：根目录配置 .env，安装依赖后启动服务。
+  - 前端：安装依赖后启动开发服务器，自动代理 /api 到后端端口。
+- Docker 开发
+  - 使用 Compose 启动服务，注意端口映射与容器内端口一致性。
+
+章节来源
+- [DEPLOY.md:259-269](file://DEPLOY.md#L259-L269)
+- [frontend/vite.config.js:17-25](file://frontend/vite.config.js#L17-L25)
+- [backend/src/app.js:40-56](file://backend/src/app.js#L40-L56)
+
+### Git 工作流与分支策略
+- 建议采用 Git Flow 或 GitHub Flow，主分支受保护，特性分支从 develop 拉取并合并回 develop，发布前打标签并合并到 main。
+- 合并请求（MR）必须通过代码审查与 CI 检查。
+
+### 代码规范与命名约定
+- 文件与目录
+  - 后端按功能分层（config/middleware/models/routes/services/utils/validators），统一小写与下划线。
+  - 前端按功能域组织（api/components/layout/router/utils/views/styles），组件与页面使用 PascalCase。
+- 命名
+  - 变量与函数使用驼峰命名；常量使用大写下划线；类与构造函数使用帕斯卡命名。
+- 文档
+  - README 保持简洁，贡献者指南与变更日志独立维护。
+
+### 测试策略
+- 单元测试
+  - 后端：针对工具函数、验证器与服务层进行单元测试。
+  - 前端：针对工具函数与组件逻辑进行单元测试。
+- 集成测试
+  - 后端：集成数据库、缓存与外部服务的端到端接口测试。
+- 端到端测试
+  - 使用自动化测试框架（如 Playwright/Cypress）覆盖关键用户路径。
+
+### 依赖管理与版本控制
+- 包管理
+  - 使用 pnpm 并锁定版本，确保团队一致性。
+- 版本发布
+  - 语义化版本管理，变更记录与发布说明同步更新。
+
+### 发布流程
+- 本地构建前端产物，使用上传脚本同步到服务器，随后在服务器执行 Compose 构建与启动。
+- 仅更新前端或后端时，可选择性上传并重启对应服务。
+
+章节来源
+- [scripts/upload.sh:1-191](file://scripts/upload.sh#L1-L191)
+- [DEPLOY.md:122-154](file://DEPLOY.md#L122-L154)
+
+### 团队协作与文档维护
+- 代码审查
+  - 至少一名合作者审查并通过 CI 检查后方可合并。
+- 文档
+  - 重要变更同步更新 README、DEPLOY.md 与内部 Wiki。
+- 沟通
+  - 使用问题跟踪与每日站会保持进度透明。
@@ -0,0 +1,325 @@
+# 设计系统
+
+<cite>
+**本文引用的文件**   
+- [backend/src/app.js](file://backend/src/app.js)
+- [backend/src/routes/index.js](file://backend/src/routes/index.js)
+- [backend/src/routes/auth.js](file://backend/src/routes/auth.js)
+- [backend/src/models/index.js](file://backend/src/models/index.js)
+- [backend/src/models/Brand.js](file://backend/src/models/Brand.js)
+- [backend/src/models/Model.js](file://backend/src/models/Model.js)
+- [backend/src/config/database.js](file://backend/src/config/database.js)
+- [backend/package.json](file://backend/package.json)
+- [frontend/src/main.js](file://frontend/src/main.js)
+- [frontend/src/App.vue](file://frontend/src/App.vue)
+- [frontend/src/router/index.js](file://frontend/src/router/index.js)
+- [frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
+- [frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
+- [frontend/package.json](file://frontend/package.json)
+- [docker-compose.yml](file://docker-compose.yml)
+- [DEPLOY.md](file://DEPLOY.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能与可扩展性](#性能与可扩展性)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本项目是一个面向耳机品牌与型号管理的后台管理系统，包含前后端分离的完整实现：前端基于 Vue 3 + Element Plus，后端基于 Express + Sequelize（MySQL），通过 Docker Compose 进行容器化部署。系统提供品牌管理、型号管理、OTA 升级包管理、黑名单管理、定向升级、分享码日志以及用户认证等能力。
+
+## 项目结构
+仓库采用前后端分层组织方式：
+- backend：Express 应用入口、路由、模型、配置、中间件、服务与工具模块
+- frontend：Vue 3 应用入口、路由、布局、视图、API 封装、样式与工具
+- docker-compose.yml：编排前端 Nginx 与后端 Node 服务
+- DEPLOY.md：部署与环境说明
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_main["frontend/src/main.js"]
+FE_app["frontend/src/App.vue"]
+FE_router["frontend/src/router/index.js"]
+FE_layout["frontend/src/layout/index.vue"]
+FE_home["frontend/src/views/home/index.vue"]
+end
+subgraph "后端"
+BE_app["backend/src/app.js"]
+BE_routes["backend/src/routes/index.js"]
+BE_auth["backend/src/routes/auth.js"]
+BE_models["backend/src/models/index.js"]
+BE_brand["backend/src/models/Brand.js"]
+BE_model["backend/src/models/Model.js"]
+BE_db["backend/src/config/database.js"]
+end
+FE_main --> FE_app
+FE_app --> FE_router
+FE_router --> FE_layout
+FE_layout --> FE_home
+FE_main --> |"HTTP 请求 /api/*"| BE_app
+BE_app --> BE_routes
+BE_routes --> BE_auth
+BE_auth --> BE_models
+BE_models --> BE_brand
+BE_models --> BE_model
+BE_app --> BE_db
+```
+
+**图表来源** 
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [frontend/src/App.vue:1-30](file://frontend/src/App.vue#L1-L30)
+- [frontend/src/router/index.js:1-103](file://frontend/src/router/index.js#L1-L103)
+- [frontend/src/layout/index.vue:1-348](file://frontend/src/layout/index.vue#L1-L348)
+- [frontend/src/views/home/index.vue:1-327](file://frontend/src/views/home/index.vue#L1-L327)
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [backend/src/routes/index.js:1-15](file://backend/src/routes/index.js#L1-L15)
+- [backend/src/routes/auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
+- [backend/src/models/index.js:1-10](file://backend/src/models/index.js#L1-L10)
+- [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-L53)
+- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
+
+**章节来源**
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
+- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
+
+## 核心组件
+- 应用入口
+  - 后端：Express 应用初始化、全局中间件、健康检查、路由挂载、数据库同步与启动监听
+  - 前端：Vue 应用创建、Element Plus 注册、路由挂载、加载遮罩处理
+- 路由层
+  - 后端：按功能域拆分路由并统一汇总挂载
+  - 前端：基于 vue-router 的页面路由与导航守卫（鉴权、超级管理员控制）
+- 数据模型
+  - 使用 Sequelize 定义实体（如 Brand、Model），集中导出供路由与服务使用
+- 配置与基础设施
+  - 数据库连接、环境变量加载、日志、Redis 等（部分在配置目录中）
+
+**章节来源**
+- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
+- [backend/src/routes/index.js:1-15](file://backend/src/routes/index.js#L1-L15)
+- [frontend/src/main.js:1-26](file://frontend/src/main.js#L1-L26)
+- [frontend/src/router/index.js:1-103](file://frontend/src/router/index.js#L1-L103)
+- [backend/src/models/index.js:1-10](file://backend/src/models/index.js#L1-L10)
+- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
+
+## 架构总览
+系统采用经典的前后端分离架构，前端静态资源由 Nginx 托管并通过反向代理将 /api 转发到后端；后端以 Express 提供服务，使用 Sequelize 访问 MySQL。
+
+```mermaid
+graph TB
+Client["浏览器客户端"]
+Nginx["Nginx(前端容器)"]
+API["Express(后端容器)"]
+DB["MySQL"]
+Redis["Redis(可选)"]
+Client --> Nginx
+Nginx --> |"/api/*" 代理| API
+API --> DB
+API --> Redis
+```
+
+**图表来源** 
+- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
+- [DEPLOY.md:1-269](file://DEPLOY.md#L1-L269)
+
+## 详细组件分析
+
+### 认证流程（登录与鉴权）
+该流程涵盖前端导航守卫、后端登录接口、JWT 签发与受保护接口的鉴权中间件。
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant FE as "前端路由守卫"
+participant API as "后端认证路由"
+participant DB as "数据库"
+participant JWT as "JWT工具"
+U->>FE : 访问受保护页面
+FE->>FE : 检查本地令牌是否过期
+alt 无令牌或已过期
+FE-->>U : 重定向至登录页
+else 有有效令牌
+FE->>API : GET /api/auth/me
+API->>DB : 查询当前用户
+DB-->>API : 返回用户信息
+API-->>FE : 返回用户信息
+FE-->>U : 放行并渲染页面
+end
+U->>API : POST /api/auth/login
+API->>DB : 校验用户名/状态
+DB-->>API : 返回用户记录
+API->>API : 校验密码哈希
+API->>JWT : 生成访问令牌
+JWT-->>API : 返回令牌
+API-->>U : 返回令牌与用户信息
+```
+
+**图表来源** 
+- [frontend/src/router/index.js:76-100](file://frontend/src/router/index.js#L76-L100)
+- [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
+- [backend/src/routes/auth.js:66-77](file://backend/src/routes/auth.js#L66-L77)
+
+**章节来源**
+- [frontend/src/router/index.js:76-100](file://frontend/src/router/index.js#L76-L100)
+- [backend/src/routes/auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
+- [backend/src/routes/auth.js:66-77](file://backend/src/routes/auth.js#L66-L77)
+
+### 首页“今日新增”数据流
+首页展示当日新增的型号与 OTA 记录，调用仪表盘统计接口获取数据。
+
+```mermaid
+sequenceDiagram
+participant V as "Home 视图"
+participant API as "Dashboard API"
+participant S as "后端路由/服务"
+participant DB as "数据库"
+V->>API : 请求今日统计数据
+API->>S : 进入业务逻辑
+S->>DB : 聚合当日新增型号/OTA
+DB-->>S : 返回统计结果
+S-->>API : 组装响应
+API-->>V : 返回 models/otas 列表
+V->>V : 渲染卡片与列表
+```
+
+**图表来源** 
+- [frontend/src/views/home/index.vue:127-148](file://frontend/src/views/home/index.vue#L127-L148)
+
+**章节来源**
+- [frontend/src/views/home/index.vue:127-148](file://frontend/src/views/home/index.vue#L127-L148)
+
+### 数据模型与关系（简化）
+以下模型用于品牌与型号管理，字段注释清晰，便于理解数据结构。
+
+```mermaid
+erDiagram
+BRAND {
+int id PK
+string name UK
+}
+MODEL {
+int id PK
+string brand_name
+string name
+string form
+string rig
+string source
+string eq_key
+datetime create_at
+}
+BRAND ||--o{ MODEL : "brand_name 关联"
+```
+
+**图表来源** 
+- [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-53)
+
+**章节来源**
+- [backend/src/models/Brand.js:1-23](file://backend/src/models/Brand.js#L1-L23)
+- [backend/src/models/Model.js:1-53](file://backend/src/models/Model.js#L1-53)
+
+### 布局与导航
+侧边栏支持折叠/展开、面包屑与用户菜单，结合路由元信息进行权限控制与高亮。
+
+```mermaid
+flowchart TD
+Start(["进入 Layout"]) --> ResolveMenu["根据当前路径计算展开菜单"]
+ResolveMenu --> Breadcrumb["解析面包屑标题与分组"]
+Breadcrumb --> UserMenu{"用户菜单操作"}
+UserMenu --> |退出| Logout["清除本地认证并重定向登录"]
+UserMenu --> |账号管理| ToUsers["跳转系统用户管理"]
+UserMenu --> |修改密码| OpenDialog["打开修改密码弹窗"]
+Logout --> End(["结束"])
+ToUsers --> End
+OpenDialog --> End
+```
+
+**图表来源** 
+- [frontend/src/layout/index.vue:174-231](file://frontend/src/layout/index.vue#L174-L231)
+
+**章节来源**
+- [frontend/src/layout/index.vue:174-231](file://frontend/src/layout/index.vue#L174-L231)
+
+## 依赖关系分析
+- 后端依赖
+  - Express、Sequelize、MySQL、JSON Web Token、Multer、Axios、Zod、Winston、ioredis、AWS SDK（S3）等
+- 前端依赖
+  - Vue 3、Element Plus、Vue Router、Axios、JSON Pretty 等
+- 运行时编排
+  - Docker Compose 编排前端 Nginx 与后端 Node 服务，端口映射与网络互通
+
+```mermaid
+graph LR
+FE_pkg["frontend/package.json"]
+BE_pkg["backend/package.json"]
+Compose["docker-compose.yml"]
+FE_pkg --> |"构建产物 dist"| Compose
+BE_pkg --> |"镜像构建/运行"| Compose
+Compose --> |"Nginx 8082 -> 80"| FE_static["前端静态资源"]
+Compose --> |"Node 8083 -> 8000"| BE_api["后端 API"]
+```
+
+**图表来源** 
+- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
+- [backend/package.json:1-29](file://backend/package.json#L1-L29)
+- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
+
+**章节来源**
+- [frontend/package.json:1-24](file://frontend/package.json#L1-L24)
+- [backend/package.json:1-29](file://backend/package.json#L1-L29)
+- [docker-compose.yml:1-48](file://docker-compose.yml#L1-L48)
+
+## 性能与可扩展性
+- 数据库连接
+  - 使用 Sequelize 连接 MySQL，建议在生产环境启用连接池与慢查询日志，合理设置超时与重试策略
+- 静态资源
+  - 前端通过 Nginx 缓存静态资源，开启 Gzip/Brotli 压缩可提升首屏加载速度
+- 鉴权与限流
+  - 建议在网关层增加速率限制与请求体大小限制（后端已有 bodyLimit 中间件）
+- 扩展点
+  - 可按功能域继续拆分路由与服务，引入缓存层（Redis）与消息队列以提升吞吐
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 前端空白
+  - 确认 dist 已上传且 Nginx 配置正确，查看浏览器控制台是否有 404 或跨域错误
+- API 请求失败
+  - 检查后端容器状态与健康检查接口，查看后端日志定位数据库/Redis 连接问题
+- 后端构建失败
+  - 确认镜像基础版本与 pnpm 版本一致，确保上传了 package.json 与锁文件
+- 环境变量未生效
+  - 重新创建容器使 .env 生效
+
+**章节来源**
+- [DEPLOY.md:226-269](file://DEPLOY.md#L226-L269)
+
+## 结论
+本设计系统以清晰的模块化与容器化部署为基础，提供了完整的品牌与型号管理能力，并在认证、路由、模型与部署方面形成了稳定的工程实践。后续可在缓存、监控与可观测性方面进一步增强，以满足更大规模的生产需求。
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+- 关键入口与脚本
+  - 后端入口：[backend/src/app.js](file://backend/src/app.js)
+  - 前端入口：[frontend/src/main.js](file://frontend/src/main.js)
+  - 路由汇总：[backend/src/routes/index.js](file://backend/src/routes/index.js)
+  - 认证路由：[backend/src/routes/auth.js](file://backend/src/routes/auth.js)
+  - 模型索引：[backend/src/models/index.js](file://backend/src/models/index.js)
+  - 数据库配置：[backend/src/config/database.js](file://backend/src/config/database.js)
+  - 前端路由：[frontend/src/router/index.js](file://frontend/src/router/index.js)
+  - 布局组件：[frontend/src/layout/index.vue](file://frontend/src/layout/index.vue)
+  - 首页视图：[frontend/src/views/home/index.vue](file://frontend/src/views/home/index.vue)
+  - 部署文档：[DEPLOY.md](file://DEPLOY.md)
+  - 编排文件：[docker-compose.yml](file://docker-compose.yml)