16 KiB
16 KiB
校园新闻管理系统 - 完整技术文档
项目概述
校园新闻管理系统是一个基于 Vue 3 + TypeScript 的现代化前端应用，实现了基于角色和权限的动态路由、三层导航架构以及状态持久化功能。
目录
快速开始
环境要求
- Node.js 16+
- npm 或 yarn
安装和运行
# 安装依赖
yarn install
# 开发环境
yarn serve
# 生产构建
yarn build
# 代码检查
yarn lint
项目结构
src/
├── apis/ # API 接口
├── assets/ # 静态资源
├── components/ # 公共组件
│ ├── TopNavigation.vue # 顶部导航栏
│ ├── MenuNav.vue # 侧边栏菜单
│ ├── MenuItem.vue # 菜单项
│ ├── Breadcrumb.vue # 面包屑
│ └── UserDropdown.vue # 用户下拉菜单
├── directives/ # 自定义指令
├── layouts/ # 布局组件
│ ├── NavigationLayout.vue # 导航布局
│ ├── BasicLayout.vue # 基础布局
│ ├── BlankLayout.vue # 空白布局
│ └── PageLayout.vue # 页面布局
├── router/ # 路由配置
├── store/ # Vuex 状态管理
├── types/ # TypeScript 类型定义
├── utils/ # 工具函数
└── views/ # 页面组件
系统架构
核心设计理念
系统采用三层导航架构，通过 MenuType 枚举实现灵活的菜单显示控制：
export enum MenuType {
SIDEBAR = 0, // 侧边栏菜单
NAVIGATION = 1, // 顶部导航菜单
BUTTON = 2, // 按钮（不生成路由）
PAGE = 3 // 独立页面（不使用 NavigationLayout）
}
布局判断逻辑
系统根据路由的 meta.menuType 自动决定布局：
// App.vue
const useNavigationLayout = computed(() => {
const menuType = route.meta?.menuType;
return menuType !== MenuType.PAGE; // 只有 PAGE 类型不使用布局
});
规则：
- ✅
menuType !== 3 (PAGE)→ 使用 NavigationLayout（有顶部导航栏） - ❌
menuType === 3 (PAGE)→ 不使用布局（独立页面，如登录页）
页面渲染流程
用户访问页面
↓
App.vue 检查 route.meta.menuType
↓
┌─────────────────────┬──────────────────────┐
│ menuType === 3 │ menuType !== 3 │
│ (PAGE) │ (其他类型) │
└─────────────────────┴──────────────────────┘
↓ ↓
独立渲染页面 使用 NavigationLayout
(无导航栏) (有导航栏)
↓ ↓
router-view TopNavigation
↓
根据 menuType 显示:
- NAVIGATION → 顶部导航项
- SIDEBAR → 左侧边栏
↓
router-view
状态管理
认证状态持久化
// 从 localStorage 恢复状态
function getStoredState(): Partial<AuthState> {
try {
const token = localStorage.getItem('token');
const loginDomainStr = localStorage.getItem('loginDomain');
const menusStr = localStorage.getItem('menus');
const permissionsStr = localStorage.getItem('permissions');
return {
token: token || null,
loginDomain: loginDomainStr ? JSON.parse(loginDomainStr) : null,
menus: menusStr ? JSON.parse(menusStr) : [],
permissions: permissionsStr ? JSON.parse(permissionsStr) : [],
routesLoaded: false,
};
} catch (error) {
console.error('从localStorage恢复状态失败:', error);
return {};
}
}
状态恢复机制
async restoreAuth({ state, commit, dispatch }) {
try {
if (!state.token) return false;
if (state.loginDomain && state.menus.length > 0) {
console.log('从localStorage恢复登录状态');
await dispatch('generateRoutes');
return true;
}
return true;
} catch (error) {
console.error('恢复登录状态失败:', error);
commit('CLEAR_AUTH');
return false;
}
}
导航系统
三层导航架构
第一层：顶部导航栏（MenuType.NAVIGATION）
- 显示在所有页面的顶部
- 作为主要的一级导航
- 支持下拉菜单
第二层：下拉菜单 / 侧边栏
- 下拉菜单：如果子菜单类型是
MenuType.NAVIGATION，则作为顶部导航的下拉选项 - 侧边栏：如果子菜单类型是
MenuType.SIDEBAR，则显示在页面左侧作为侧边栏
第三层及更深：侧边栏子菜单
- 在侧边栏中显示
- 支持多层嵌套
菜单结构示例
示例 1：新闻管理（带侧边栏）
{
"menuID": "news",
"name": "新闻管理",
"url": "/news",
"type": 1, // NAVIGATION - 显示在顶部导航栏
"component": "NavigationLayout",
"children": [
{
"menuID": "news-article",
"name": "文章管理",
"url": "/news/article",
"type": 0, // SIDEBAR - 显示在左侧边栏
"component": "manage/news/ArticleManage.vue",
"children": [
{
"menuID": "news-article-list",
"name": "文章列表",
"url": "/news/article/list",
"type": 0, // SIDEBAR - 侧边栏子菜单
"component": "manage/news/ArticleList.vue"
},
{
"menuID": "news-article-create",
"name": "创建文章",
"url": "/news/article/create",
"type": 0, // SIDEBAR
"component": "manage/news/ArticleCreate.vue"
}
]
},
{
"menuID": "news-category",
"name": "分类管理",
"url": "/news/category",
"type": 0, // SIDEBAR - 显示在左侧边栏
"component": "manage/news/CategoryManage.vue"
}
]
}
效果：
- "新闻管理" 显示在顶部导航栏
- 左侧侧边栏显示：
- 文章管理
- 文章列表
- 创建文章
- 分类管理
- 文章管理
示例 2：系统管理（带下拉菜单）
{
"menuID": "system",
"name": "系统管理",
"url": "/system",
"type": 1, // NAVIGATION - 显示在顶部导航栏
"component": "NavigationLayout",
"children": [
{
"menuID": "system-user",
"name": "用户管理",
"url": "/system/user",
"type": 1, // NAVIGATION - 作为下拉菜单
"component": "manage/system/UserManage.vue"
},
{
"menuID": "system-role",
"name": "角色管理",
"url": "/system/role",
"type": 1, // NAVIGATION - 作为下拉菜单
"component": "manage/system/RoleManage.vue"
}
]
}
效果：
- "系统管理" 显示在顶部导航栏，鼠标悬停显示下拉菜单
- 下拉菜单包含：用户管理、角色管理
- 没有侧边栏
路由生成流程
后端返回菜单数据
↓
Vuex Store 保存到 state.auth.menus
↓
持久化到 localStorage
↓
generateRoutes() 函数处理
↓
根据 type 和层级决定使用的布局
↓
生成 Vue Router 路由配置
↓
router.addRoute() 动态添加路由
↓
设置 routesLoaded = true
静态路由与动态路由合并
buildMenuTree 流程
function buildMenuTree(menus: SysMenu[]) {
// 1. 将静态路由转换为菜单项
const staticMenus = convertRoutesToMenus(routes);
// 2. 合并静态菜单和动态菜单
const allMenus = [...staticMenus, ...menus];
// 3. 构建树结构并排序（按 orderNum）
return sortMenus(rootMenus);
}
避免路由重复
function convertRoutesToMenus(routes: RouteRecordRaw[]) {
routes.forEach(route => {
if (route.meta?.menuType !== undefined) {
const menu: SysMenu = {
// ...
component: '__STATIC_ROUTE__', // 特殊标记
};
menus.push(menu);
}
});
}
function generateRouteFromMenu(menu: SysMenu) {
// 跳过按钮类型
if (menu.type === MenuType.BUTTON) {
return null;
}
// 跳过静态路由（避免重复添加）
if (menu.component === '__STATIC_ROUTE__') {
return null; // ✅ 不生成路由
}
// 正常生成动态路由
return route;
}
权限控制
权限指令使用
v-permission 指令
<!-- 单个权限 -->
<el-button v-permission="'user:create'">新增用户</el-button>
<!-- 多个权限（任意一个） -->
<el-button v-permission="['user:create', 'user:edit']">操作</el-button>
<!-- 多个权限（必须全部拥有） -->
<el-button v-permission.all="['user:create', 'user:edit']">操作</el-button>
v-role 指令
<!-- 单个角色 -->
<div v-role="'admin'">管理员内容</div>
<!-- 多个角色 -->
<div v-role="['admin', 'moderator']">管理内容</div>
Composition API 使用
<script setup>
import { usePermission } from '@/directives/permission';
const { hasPermission, hasAnyPermission, hasRole } = usePermission();
// 检查权限
if (hasPermission('user:create')) {
// 有权限的逻辑
}
// 检查角色
if (hasRole('admin')) {
// 管理员逻辑
}
</script>
路由守卫
系统自动设置了路由守卫：
async function handleRouteGuard(
to: RouteLocationNormalized,
from: RouteLocationNormalized,
next: NavigationGuardNext,
store: Store<any>
) {
const authState: AuthState = store.state.auth;
const isAuthenticated = store.getters['auth/isAuthenticated'];
if (isInWhiteList(to.path)) {
return next();
}
if (authState.token && !isAuthenticated) {
try {
const restored = await store.dispatch('auth/restoreAuth');
if (restored) {
return next({ ...to, replace: true });
} else {
return next({ path: '/login', query: { redirect: to.fullPath } });
}
} catch (error) {
return next({ path: '/login', query: { redirect: to.fullPath } });
}
}
if (!isAuthenticated) {
return next({ path: '/login', query: { redirect: to.fullPath } });
}
if (!authState.routesLoaded) {
try {
await store.dispatch('auth/generateRoutes');
return next({ ...to, replace: true });
} catch (error) {
store.commit('auth/CLEAR_AUTH');
return next('/login');
}
}
const hasPermission = await checkPagePermission(to, store);
if (!hasPermission) {
return next('/403');
}
next();
}
开发指南
组件说明
TopNavigation.vue
顶部导航栏组件，功能包括：
- 显示 Logo
- 显示一级 NAVIGATION 菜单
- 支持下拉菜单（二级 NAVIGATION 菜单）
- 显示用户信息和登出功能
NavigationLayout.vue
导航布局组件，功能包括：
- 包含 TopNavigation
- 根据当前路由动态显示侧边栏（SIDEBAR 类型的子菜单）
- 支持侧边栏折叠
- 显示面包屑导航
MenuNav.vue
菜单导航组件，用于渲染侧边栏菜单树
开发建议
- 第一层菜单：使用
MenuType.NAVIGATION，这是顶部导航 - 第二层菜单：
- 如果是简单的操作页面（如用户管理、角色管理），使用
MenuType.NAVIGATION作为下拉菜单 - 如果需要更复杂的子菜单结构，使用
MenuType.SIDEBAR显示侧边栏
- 如果是简单的操作页面（如用户管理、角色管理），使用
- 第三层及更深：使用
MenuType.SIDEBAR，在侧边栏中嵌套显示 - 按钮：不需要路由的权限按钮使用
MenuType.BUTTON
菜单配置规则
-
第一层菜单：
- 必须使用
type: 1（NAVIGATION） - 会显示在顶部导航栏
- 必须使用
-
第二层菜单：
type: 1（NAVIGATION）→ 显示为下拉菜单选项type: 0（SIDEBAR）→ 显示在侧边栏
-
第三层及更深：
- 通常使用
type: 0（SIDEBAR） - 在侧边栏中嵌套显示
- 通常使用
配置示例
静态路由配置（src/router/index.ts）
export const routes = [
// PAGE 类型 - 不使用布局
{
path: "/login",
meta: { menuType: 3 }
},
{
path: "/404",
meta: { menuType: 3 }
},
// NAVIGATION 类型 - 使用布局，显示在导航栏
{
path: "/home",
meta: { menuType: 1, orderNum: -1 }
},
];
动态路由数据（后端返回）
[
{
"menuID": "dashboard",
"name": "工作台",
"type": 1,
"url": "/dashboard/workplace",
"orderNum": 0
},
{
"menuID": "news",
"name": "新闻管理",
"type": 1,
"url": "/news",
"orderNum": 1,
"children": [
{
"menuID": "news-article",
"name": "文章管理",
"type": 0,
"url": "/news/article"
}
]
}
]
数据库字段说明
CREATE TABLE sys_menu (
menu_id VARCHAR(50) PRIMARY KEY COMMENT '菜单ID',
parent_id VARCHAR(50) COMMENT '父菜单ID',
name VARCHAR(50) NOT NULL COMMENT '菜单名称',
description VARCHAR(200) COMMENT '菜单描述',
url VARCHAR(200) COMMENT '菜单URL',
component VARCHAR(200) COMMENT '组件路径',
icon VARCHAR(50) COMMENT '菜单图标',
order_num INT DEFAULT 0 COMMENT '排序号',
type TINYINT NOT NULL DEFAULT 0 COMMENT '菜单类型：0-侧边栏 1-导航栏 2-按钮 3-独立页面',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
creator VARCHAR(50) COMMENT '创建人',
updater VARCHAR(50) COMMENT '更新人'
);
常见问题
Q1: 顶部导航没有显示
- 检查菜单数据是否正确加载到 Vuex store
- 检查第一层菜单的
type是否为1（NAVIGATION） - 打开浏览器控制台，执行：
console.log($store.getters['auth/menuTree'])
Q2: 侧边栏没有显示
- 检查第二层菜单的
type是否为0（SIDEBAR） - 如果第二层都是
type: 1（NAVIGATION），则不会显示侧边栏（这是预期行为）
Q3: 点击菜单没有跳转
- 检查菜单的
url字段是否正确 - 检查对应的组件
component字段是否存在 - 检查组件文件是否真实存在
Q4: 页面刷新后侧边栏消失
- 检查 localStorage 中是否保存了菜单数据
- 检查路由守卫是否正确恢复了登录状态
- 打开控制台查看是否有错误信息
Q5: 路由生成失败
- 检查菜单数据结构是否正确
- 检查
component字段指向的组件文件是否存在 - 查看控制台的错误信息
Q6: 如何隐藏某个页面的侧边栏？
A: 将该菜单及其兄弟菜单都设置为 MenuType.NAVIGATION 类型。
Q7: 如何让某个菜单在顶部和侧边栏都显示？
A: 在第二层使用 MenuType.NAVIGATION（显示在下拉菜单），然后它的子菜单使用 MenuType.SIDEBAR（显示在侧边栏）。
Q8: 可以有多少层菜单？
A: 理论上无限制，但建议不超过4层以保持良好的用户体验。
Q9: 按钮类型的菜单有什么用？
A: MenuType.BUTTON 类型的菜单不会生成路由，主要用于页面内的操作按钮权限控制，例如"删除"、"编辑"等按钮。
技术栈
- Vue 3：Composition API +
<script setup> - TypeScript：类型安全
- Vue Router 4：动态路由
- Vuex：状态管理
- SCSS：样式预处理
- Element Plus：UI 组件库
性能优化
- 组件懒加载：所有页面组件都使用动态导入
- 状态缓存：登录信息缓存到 localStorage，减少重复请求
- 路由缓存：动态路由只在必要时重新生成
- CSS 优化：使用 scoped 样式，避免全局污染
浏览器兼容性
- ✅ Chrome 90+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Edge 90+
版本历史
v1.0.0 (2025-10-08)
- ✅ 初始版本发布
- ✅ 实现三层导航架构
- ✅ 支持动态路由生成
- ✅ 支持状态持久化
- ✅ 完整的文档和示例
许可证
请根据项目实际情况添加许可证信息。
祝使用愉快！如有问题，请参考文档或联系开发团队。