eafonyang
325 lines
13 KiB
Markdown
325 lines
13 KiB
Markdown
# 设计系统
|
||
|
||
<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) |