507 lines
10 KiB
Markdown
507 lines
10 KiB
Markdown
# Nova Admin 整体架构文档
|
|
|
|
## 概述
|
|
|
|
Nova Admin 是一个基于 Vue 3 + TypeScript + Naive UI 的现代化后台管理系统，采用模块化架构设计，集成了完整的认证、权限、路由管理体系。
|
|
|
|
## 🏗️ 系统架构
|
|
|
|
###[权限管理系统文档.md](%E6%9D%83%E9%99%90%E7%AE%A1%E7%90%86%E7%B3%BB%E7%BB%9F%E6%96%87%E6%A1%A3.md) 核心架构图
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "前端应用层"
|
|
A[用户界面] --> B[页面组件]
|
|
B --> C[业务逻辑]
|
|
end
|
|
|
|
subgraph "状态管理层"
|
|
D[AuthStore<br/>认证状态] --> E[RouteStore<br/>路由状态]
|
|
E --> F[TabStore<br/>标签状态]
|
|
D --> G[AppStore<br/>应用状态]
|
|
end
|
|
|
|
subgraph "路由控制层"
|
|
H[路由守卫] --> I[权限验证]
|
|
I --> J[路由初始化]
|
|
J --> K[菜单生成]
|
|
end
|
|
|
|
subgraph "服务层"
|
|
L[HTTP请求] --> M[API接口]
|
|
M --> N[数据转换]
|
|
end
|
|
|
|
subgraph "持久化层"
|
|
O[localStorage] --> P[用户信息]
|
|
P --> Q[Token管理]
|
|
Q --> R[路由缓存]
|
|
end
|
|
|
|
A --> D
|
|
C --> L
|
|
H --> D
|
|
D --> O
|
|
E --> H
|
|
K --> B
|
|
```
|
|
|
|
### 技术栈
|
|
|
|
| 层级 | 技术选型 | 版本 | 说明 |
|
|
|------|----------|------|------|
|
|
| 框架 | Vue 3 | 3.x | 渐进式前端框架 |
|
|
| 语言 | TypeScript | 5.x | 类型安全的 JavaScript |
|
|
| 构建工具 | Vite | 4.x | 现代前端构建工具 |
|
|
| UI组件库 | Naive UI | 2.x | Vue 3 组件库 |
|
|
| 状态管理 | Pinia | 2.x | Vue 3 官方状态管理 |
|
|
| 路由管理 | Vue Router | 4.x | Vue 3 官方路由 |
|
|
| CSS预处理 | SCSS | - | CSS 扩展语言 |
|
|
| 图标库 | Iconify | - | 统一图标解决方案 |
|
|
|
|
## 🔄 系统交互流程
|
|
|
|
### 1. 应用启动流程
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as 用户
|
|
participant App as 应用
|
|
participant Auth as AuthStore
|
|
participant Route as RouteStore
|
|
participant Guard as 路由守卫
|
|
participant API as 后端API
|
|
|
|
U->>App: 访问应用
|
|
App->>Auth: 检查本地Token
|
|
|
|
alt Token存在
|
|
Auth->>Guard: 已登录状态
|
|
Guard->>Route: 初始化路由
|
|
Route->>API: 获取用户路由
|
|
API-->>Route: 返回路由数据
|
|
Route->>Route: 生成菜单和路由
|
|
Route->>App: 渲染应用界面
|
|
else Token不存在
|
|
Auth->>Guard: 未登录状态
|
|
Guard->>App: 重定向到登录页
|
|
end
|
|
```
|
|
|
|
### 2. 用户登录流程
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant U as 用户
|
|
participant L as 登录页
|
|
participant Auth as AuthStore
|
|
participant API as 后端API
|
|
participant Route as RouteStore
|
|
participant Guard as 路由守卫
|
|
|
|
U->>L: 提交登录信息
|
|
L->>Auth: 调用login方法
|
|
Auth->>API: 发送登录请求
|
|
API-->>Auth: 返回用户信息和Token
|
|
Auth->>Auth: 保存到localStorage
|
|
Auth->>Route: 初始化用户路由
|
|
Route->>Route: 生成菜单和路由
|
|
Auth->>Guard: 触发路由跳转
|
|
Guard->>U: 重定向到首页
|
|
```
|
|
|
|
### 3. 权限验证流程
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[用户访问] --> B{需要认证?}
|
|
B -->|否| H[允许访问]
|
|
B -->|是| C{用户已登录?}
|
|
C -->|否| D[重定向登录页]
|
|
C -->|是| E{角色权限匹配?}
|
|
E -->|否| F[显示403错误]
|
|
E -->|是| G{路由权限匹配?}
|
|
G -->|否| F
|
|
G -->|是| H
|
|
H --> I[渲染页面]
|
|
I --> J{组件权限检查}
|
|
J -->|通过| K[显示组件]
|
|
J -->|拒绝| L[隐藏组件]
|
|
```
|
|
|
|
## 📦 模块架构
|
|
|
|
### 1. 认证模块 (Authentication)
|
|
|
|
**职责**: 用户身份验证和会话管理
|
|
|
|
```typescript
|
|
// 核心组件
|
|
AuthStore // 认证状态管理
|
|
LoginAPI // 登录API接口
|
|
TokenManager // Token管理工具
|
|
LoginGuard // 登录路由守卫
|
|
```
|
|
|
|
**数据流向**:
|
|
```
|
|
用户输入 → 登录验证 → Token生成 → 状态更新 → 路由跳转
|
|
```
|
|
|
|
### 2. 权限模块 (Authorization)
|
|
|
|
**职责**: 基于角色的访问控制
|
|
|
|
```typescript
|
|
// 核心组件
|
|
usePermission // 权限验证Hook
|
|
PermissionDirective // 权限指令
|
|
RoleFilter // 角色过滤器
|
|
MenuGenerator // 菜单生成器
|
|
```
|
|
|
|
**数据流向**:
|
|
```
|
|
用户角色 → 权限计算 → 路由过滤 → 菜单生成 → 组件控制
|
|
```
|
|
|
|
### 3. 路由模块 (Routing)
|
|
|
|
**职责**: 路由管理和页面导航
|
|
|
|
```typescript
|
|
// 核心组件
|
|
RouteStore // 路由状态管理
|
|
RouteGuard // 路由守卫
|
|
RouteHelper // 路由处理工具
|
|
TabManager // 标签页管理
|
|
```
|
|
|
|
**数据流向**:
|
|
```
|
|
路由配置 → 权限过滤 → 动态注册 → 菜单生成 → 页面渲染
|
|
```
|
|
|
|
## 🎯 核心设计模式
|
|
|
|
### 1. 状态管理模式
|
|
|
|
采用 Pinia 实现响应式状态管理：
|
|
|
|
```typescript
|
|
// 状态分离
|
|
AuthStore // 认证相关状态
|
|
RouteStore // 路由相关状态
|
|
TabStore // 标签页状态
|
|
AppStore // 全局应用状态
|
|
```
|
|
|
|
### 2. 守卫模式
|
|
|
|
通过路由守卫实现横切关注点：
|
|
|
|
```typescript
|
|
// 守卫链
|
|
beforeEach // 认证检查、权限验证
|
|
beforeResolve // 路由数据准备
|
|
afterEach // 状态更新、页面标题设置
|
|
```
|
|
|
|
### 3. 工厂模式
|
|
|
|
动态创建路由和菜单：
|
|
|
|
```typescript
|
|
createRoutes() // 路由工厂
|
|
createMenus() // 菜单工厂
|
|
```
|
|
|
|
### 4. 策略模式
|
|
|
|
支持多种路由加载策略：
|
|
|
|
```typescript
|
|
// 路由加载策略
|
|
static // 静态路由模式
|
|
dynamic // 动态路由模式
|
|
```
|
|
|
|
## 🔧 配置管理
|
|
|
|
### 环境变量配置
|
|
|
|
```bash
|
|
# 应用配置
|
|
VITE_APP_NAME=Nova Admin
|
|
VITE_APP_DESC=Vue3 Admin Template
|
|
|
|
# 路由配置
|
|
VITE_ROUTE_LOAD_MODE=static
|
|
VITE_HOME_PATH=/dashboard/monitor
|
|
VITE_ROUTE_MODE=hash
|
|
|
|
# API配置
|
|
VITE_SERVICE_ENV=dev
|
|
VITE_HTTP_PROXY=Y
|
|
```
|
|
|
|
### 运行时配置
|
|
|
|
```typescript
|
|
// 路由配置
|
|
const routeConfig = {
|
|
loadMode: 'static', // 路由加载模式
|
|
homePath: '/dashboard/monitor', // 默认首页
|
|
cacheEnabled: true, // 路由缓存
|
|
}
|
|
|
|
// 权限配置
|
|
const permissionConfig = {
|
|
superRole: 'super', // 超级管理员角色
|
|
defaultRole: 'user', // 默认角色
|
|
strictMode: true, // 严格模式
|
|
}
|
|
```
|
|
|
|
## 🛡️ 安全架构
|
|
|
|
### 1. 认证安全
|
|
|
|
- **JWT Token**: 无状态认证机制
|
|
- **双Token机制**: AccessToken + RefreshToken
|
|
- **Token过期处理**: 自动刷新机制
|
|
- **本地存储**: 安全的localStorage使用
|
|
|
|
### 2. 权限安全
|
|
|
|
- **RBAC模型**: 基于角色的访问控制
|
|
- **多层权限验证**: 路由级 + 组件级 + API级
|
|
- **权限缓存**: 避免重复计算
|
|
- **权限指令**: 细粒度控制
|
|
|
|
### 3. 路由安全
|
|
|
|
- **路由守卫**: 统一的访问控制
|
|
- **重定向保护**: 防止无限重定向
|
|
- **动态路由**: 按需加载和权限过滤
|
|
- **404处理**: 友好的错误页面
|
|
|
|
## 📈 性能优化
|
|
|
|
### 1. 代码分割
|
|
|
|
```typescript
|
|
// 路由懒加载
|
|
const modules = import.meta.glob('@/views/**/*.vue')
|
|
|
|
// 组件异步加载
|
|
component: () => import('@/views/dashboard/index.vue')
|
|
```
|
|
|
|
### 2. 缓存机制
|
|
|
|
```typescript
|
|
// 路由缓存
|
|
keepAlive: true
|
|
|
|
// 组件缓存
|
|
<router-view v-slot="{ Component }">
|
|
<keep-alive :include="cacheRoutes">
|
|
<component :is="Component" />
|
|
</keep-alive>
|
|
</router-view>
|
|
```
|
|
|
|
### 3. 状态优化
|
|
|
|
```typescript
|
|
// 计算属性缓存
|
|
const isLogin = computed(() => Boolean(authStore.token))
|
|
|
|
// 响应式数据最小化
|
|
const userInfo = readonly(authStore.userInfo)
|
|
```
|
|
|
|
## 🔄 数据流管理
|
|
|
|
### 1. 单向数据流
|
|
|
|
```
|
|
用户操作 → Action → State → View → 用户界面
|
|
```
|
|
|
|
### 2. 状态同步
|
|
|
|
```typescript
|
|
// 状态持久化
|
|
localStorage ↔ Pinia Store ↔ 组件状态
|
|
```
|
|
|
|
### 3. 异步处理
|
|
|
|
```typescript
|
|
// 异步状态管理
|
|
async initAuthRoute() {
|
|
this.loading = true
|
|
try {
|
|
const routes = await fetchUserRoutes()
|
|
this.routes = routes
|
|
} finally {
|
|
this.loading = false
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🧪 测试策略
|
|
|
|
### 1. 单元测试
|
|
|
|
- 工具函数测试
|
|
- Store 逻辑测试
|
|
- 组件单元测试
|
|
|
|
### 2. 集成测试
|
|
|
|
- 路由跳转测试
|
|
- 权限控制测试
|
|
- 用户流程测试
|
|
|
|
### 3. E2E测试
|
|
|
|
- 完整用户场景
|
|
- 跨页面交互
|
|
- 权限边界测试
|
|
|
|
## 🚀 部署架构
|
|
|
|
### 1. 构建流程
|
|
|
|
```bash
|
|
# 开发环境
|
|
npm run dev
|
|
|
|
# 构建生产版本
|
|
npm run build
|
|
|
|
# 预览生产版本
|
|
npm run preview
|
|
```
|
|
|
|
### 2. 部署选项
|
|
|
|
- **静态托管**: Vercel, Netlify
|
|
- **CDN部署**: 阿里云OSS, 腾讯云COS
|
|
- **容器化**: Docker + Nginx
|
|
- **传统服务器**: Apache, Nginx
|
|
|
|
## 📊 监控体系
|
|
|
|
### 1. 性能监控
|
|
|
|
- 页面加载时间
|
|
- 路由切换性能
|
|
- 组件渲染时间
|
|
- 内存使用情况
|
|
|
|
### 2. 错误监控
|
|
|
|
- JavaScript错误
|
|
- 网络请求错误
|
|
- 路由错误
|
|
- 用户行为异常
|
|
|
|
### 3. 用户体验监控
|
|
|
|
- 页面访问统计
|
|
- 用户操作路径
|
|
- 功能使用频率
|
|
- 错误率统计
|
|
|
|
## 🔮 扩展性设计
|
|
|
|
### 1. 插件系统
|
|
|
|
```typescript
|
|
// 插件接口
|
|
interface Plugin {
|
|
install(app: App): void
|
|
beforeMount?(): void
|
|
afterMount?(): void
|
|
}
|
|
```
|
|
|
|
### 2. 主题系统
|
|
|
|
```typescript
|
|
// 主题配置
|
|
interface ThemeConfig {
|
|
primary: string
|
|
secondary: string
|
|
background: string
|
|
text: string
|
|
}
|
|
```
|
|
|
|
### 3. 国际化
|
|
|
|
```typescript
|
|
// 多语言支持
|
|
const messages = {
|
|
'zh-CN': zhCN,
|
|
'en-US': enUS,
|
|
}
|
|
```
|
|
|
|
## 🎯 最佳实践
|
|
|
|
### 1. 代码规范
|
|
|
|
- **ESLint**: 代码质量检查
|
|
- **Prettier**: 代码格式化
|
|
- **TypeScript**: 类型安全
|
|
- **命名约定**: 统一的命名规则
|
|
|
|
### 2. 项目结构
|
|
|
|
```
|
|
src/
|
|
├── components/ # 通用组件
|
|
├── views/ # 页面组件
|
|
├── store/ # 状态管理
|
|
├── router/ # 路由配置
|
|
├── hooks/ # 组合式函数
|
|
├── utils/ # 工具函数
|
|
├── types/ # 类型定义
|
|
└── assets/ # 静态资源
|
|
```
|
|
|
|
### 3. 开发流程
|
|
|
|
1. **需求分析**: 明确功能需求
|
|
2. **设计评审**: 技术方案评估
|
|
3. **编码实现**: 遵循代码规范
|
|
4. **测试验证**: 单元测试和集成测试
|
|
5. **代码审查**: 团队代码评审
|
|
6. **部署发布**: 自动化部署流程
|
|
|
|
## 📚 相关文档
|
|
|
|
- [登录鉴权系统文档](./登录鉴权系统文档)
|
|
- [权限管理系统文档](./权限管理系统文档)
|
|
- [路由管理系统文档](./路由管理系统文档)
|
|
- [Vue 3 官方文档](https://vuejs.org/)
|
|
- [Naive UI 组件库](https://www.naiveui.com/)
|
|
- [Pinia 状态管理](https://pinia.vuejs.org/)
|
|
|
|
## 🤝 贡献指南
|
|
|
|
1. Fork 项目仓库
|
|
2. 创建功能分支
|
|
3. 提交代码变更
|
|
4. 发起 Pull Request
|
|
5. 代码审查和合并
|
|
|
|
---
|
|
|
|
*本文档最后更新时间: 2024年7月*
|