# SMS-frontend

**Repository Path**: dreiluo/sms-frontend

## Basic Information

- **Project Name**: SMS-frontend
- **Description**: 钟祥司徒实训结课前端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-15
- **Last Updated**: 2026-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学生管理系统 · 前端（stu-frontend）

基于 **Vue 3 + TypeScript + Vite + Element Plus** 的学生管理系统前端，按角色动态渲染菜单与路由，配合后端 JWT 鉴权实现教学秘书 / 教师 / 学生三端一体的单页应用。

> 配套后端仓库：[gitee.com/dreiluo/sms-backend](https://gitee.com/dreiluo/sms-backend)

---

## 目录

- [一、项目简介](#一项目简介)
- [二、技术栈](#二技术栈)
- [三、环境要求](#三环境要求)
- [四、快速开始](#四快速开始)
- [五、可用脚本](#五可用脚本)
- [六、环境变量](#六环境变量)
- [七、目录结构](#七目录结构)
- [八、路由与权限](#八路由与权限)
- [九、与后端的约定](#九与后端的约定)
- [十、构建与部署](#十构建与部署)
- [十一、常见问题](#十一常见问题)

---

## 一、项目简介

单页应用（SPA），登录后根据角色展示不同菜单，**同一套页面按角色隔离**，无权限的路径会被路由守卫拦回本角色首页。

| 角色 | 页面 |
| --- | --- |
| 教学秘书 `ADMIN` | 教职工管理、学生管理、课程管理、成绩审核、选课监控 |
| 教师 `TEACHER` | 我的课程（创建 / 编辑 / 发布）、成绩录入 |
| 学生 `STUDENT` | 学业总览、选课中心、我的课表、成绩查询 |

---

## 二、技术栈

| 分类 | 技术 | 版本 | 说明 |
| --- | --- | --- | --- |
| 框架 | Vue | 3.5.x | 全量使用 `<script setup>` 组合式 API |
| 路由 | Vue Router | 5.2.x | `createWebHistory` 模式，守卫使用**返回值**写法 |
| 状态管理 | Pinia | 4.0.x | 仅用户状态一个 store |
| UI 组件库 | Element Plus | 2.14.x | **全量引入**（非按需），样式在 `main.ts` 中统一引入 |
| HTTP | Axios | 1.20.x | 统一封装在 `util/request.ts` |
| 图表 | ECharts | 6.1.x | 学生端成绩趋势图 |
| 构建 | Vite | 8.1.x | 基于 Rolldown + Oxc，非 esbuild / Rollup |
| 语言 | TypeScript | ~6.0 | 严格模式 |
| 类型检查 | vue-tsc | 3.3.x | `.vue` 文件类型检查 |
| 格式化 | Prettier | 3.9.5 | — |
| 运行时 | Node.js | `^22.18.0 \|\| >=24.12.0` | 见 `package.json` 的 `engines` |

---

## 三、环境要求

| 组件 | 版本要求 | 检查命令 |
| --- | --- | --- |
| Node.js | `^22.18.0` 或 `>=24.12.0` | `node -v` |
| npm | 10 及以上 | `npm -v` |

> 后端需先启动（默认 `http://localhost:9090`），否则登录会失败。

---

## 四、快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 确认后端地址

开发环境后端地址配置在 `.env.development`：

```
VITE_API_BASE_URL=http://localhost:9090
```

如后端不在默认端口，改这里即可。

### 3. 启动开发服务器

```bash
npm run dev
```

浏览器打开 <http://localhost:5173>。

### 4. 登录

| 角色 | 账号 | 密码 |
| --- | --- | --- |
| 教学秘书 | `admin` | `123456` |
| 教师 | `t001` | `123456` |
| 学生 | `2024001` | `123456` |

---

## 五、可用脚本

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动开发服务器（热更新） |
| `npm run build` | **类型检查 + 生产构建**（并行执行 `type-check` 与 `build-only`） |
| `npm run build-only` | 仅生产构建，不做类型检查 |
| `npm run type-check` | 仅运行 `vue-tsc --build` 类型检查 |
| `npm run preview` | 本地预览 `dist` 产物 |
| `npm run format` | Prettier 格式化 `src` 与 `util` 目录 |

> ⚠️ `vite build` **不做类型检查**。若只跑 `build-only`，类型错误会被静默忽略，提交前请确保 `npm run build` 或 `npm run type-check` 通过。

---

## 六、环境变量

Vite 约定只有 `VITE_` 前缀的变量会暴露给客户端。

| 文件 | 变量 | 值 | 说明 |
| --- | --- | --- | --- |
| `.env.development` | `VITE_API_BASE_URL` | `http://localhost:9090` | 开发环境后端地址 |
| `.env.production` | `VITE_API_BASE_URL` | `http://localhost:9090` | **部署前必须改为真实域名** |

变量通过 `util/config.ts` 统一导出，业务代码不直接读 `import.meta.env`：

```ts
export const API_BASE_URL: string = import.meta.env.VITE_API_BASE_URL || 'http://localhost:9090'
```

---

## 七、目录结构

```
stu-frontend/
├── index.html
├── vite.config.ts                 # @ 别名指向 src，注册 vue / vueDevTools 插件
├── tsconfig*.json
├── .env.development               # 开发环境后端地址
├── .env.production                # 生产环境后端地址
├── public/
├── util/                          # 与 src 平级的通用工具（被 src 以相对路径引用）
│   ├── config.ts                  # API_BASE_URL
│   ├── request.ts                 # Axios 封装：注入 Token、统一错误处理、文件下载
│   └── confirm.ts                 # ElMessageBox 的 Promise 化封装
└── src/
    ├── main.ts                    # 应用入口：Pinia + Router + Element Plus
    ├── App.vue
    ├── types/index.ts             # 全局类型定义（与后端 VO 一一对应）
    ├── router/
    │   ├── routes.ts              # ★ 路由 / 菜单 / 角色首页的唯一数据源
    │   └── index.ts               # 路由实例 + 全局守卫
    ├── stores/user.ts             # 用户状态（Token / 角色 / 用户信息）
    ├── components/ScoreTrendChart.vue
    └── views/
        ├── LoginPage.vue
        ├── Layout.vue             # 侧边栏 + 顶栏布局，菜单由 routes.ts 派生
        ├── admin/                 # AccountManage / StudentManage / CourseManage / GradeAudit / CourseMonitor
        ├── teacher/               # MyCourses / GradeEntry
        └── student/               # StudentHome / CourseCenter / MyCourses / MyGrades
```

### 路径别名

`@` → `src`，在 `src` 内部统一使用 `@/types`、`@/stores/...` 形式引用；`util/` 位于 `src` 之外，使用相对路径（如 `../../../util/request`）。

---

## 八、路由与权限

### 8.1 唯一数据源

`src/router/routes.ts` 中的 `menuRoutes` 是**路由表、侧边栏菜单、角色首页映射三者的唯一来源**：

```ts
export const menuRoutes: MenuRoute[] = [
  { path: '/admin/account', title: '教职工管理', role: 'ADMIN',
    component: () => import('../views/admin/AccountManage.vue') },
  // ...
]
```

由它派生出三个产物：

| 产物 | 消费方 | 作用 |
| --- | --- | --- |
| `childRoutes` | `router/index.ts` | 注册为 `Layout` 的子路由 |
| `menusByRole` | `Layout.vue` | 按角色渲染侧边栏菜单 |
| `homeMap` | 路由守卫 | 登录后跳转到该角色的第一个菜单 |

**新增一个页面只需在 `menuRoutes` 里加一行**，路由、菜单、首页跳转会自动同步，不会出现「菜单有但路由没配」的不一致。

不在侧边栏中的页面（如从课程列表跳入的成绩录入页 `teacher/grade/:courseId`）直接追加到 `childRoutes`。

### 8.2 路由守卫

`router/index.ts` 的守卫使用 **返回值** 写法（而非已废弃的 `next()`）：

- 未登录访问任何页面 → 重定向 `/login`
- 已登录访问 `/login` → 重定向到本角色首页
- 访问的角色与 `route.meta.role` 不匹配 → 重定向到本角色首页
- 未匹配的任意路径（手输错地址、失效链接）→ 兜底重定向 `/login`，避免整页白屏

### 8.3 双层校验

前端守卫只负责**体验**（不让用户看到无权页面），真正的权限控制在后端：每个接口都会校验 JWT 与角色。任何绕过前端直接调接口的请求都会被后端拒绝。

---

## 九、与后端的约定

### 9.1 统一返回体

后端所有接口返回 `{ code, message, data }`，`code === 202` 表示成功。`util/request.ts` 已统一处理：

| code | 前端行为 |
| --- | --- |
| `202` | 直接返回响应体，业务代码只关心 `res.data` |
| `401` | 清除本地登录态并跳转登录页 |
| `403` | 提示「无权限：xxx」 |
| `505` | 提示「业务异常：xxx」 |
| 其他 / 网络异常 | 统一弹出错误提示 |

因此**业务代码里不需要再写错误提示**，只需处理成功分支：

```ts
const res = await request<PageResult<Student>>({
  method: 'POST',
  url: '/api/student/query',
  data: qc.value,
})
records.value = res.data.records
```

### 9.2 请求封装

`util/request.ts` 提供两个入口：

- `request<T>(config)` —— 泛型化普通请求，返回值类型即 `ApiResult<T>`
- `download(url, filename)` —— 文件下载（Excel 导出），并处理「后端返回 JSON 错误」的情况：若响应头是 `application/json`，会解析出业务错误信息并提示，而不是把错误 JSON 存成损坏的 xlsx

请求拦截器自动从 `localStorage` 读取 Token 并注入 `Authorization: Bearer <token>`，业务代码无需手动传。

### 9.3 跨域说明

项目**没有配置 Vite 代理**，前端直接跨域请求后端地址。因此后端 `WebConfig` 开启了 CORS（`app.cors.allowed-origins`）。若希望改用同源代理，可在 `vite.config.ts` 中自行添加 `server.proxy`。

### 9.4 类型定义

所有与后端交互的类型集中在 `src/types/index.ts`，与后端 VO 字段一一对应（如 `CourseVO`、`StudentCourseVO`、`GradeVO`）。**新增字段时前后端要同步修改**，避免出现 `undefined`。

---

## 十、构建与部署

### 构建

```bash
npm run build
```

产物输出到 `dist/`。

### 部署注意事项

1. **必须配置 history 模式回退**：路由使用 `createWebHistory`，刷新 `/admin/student` 这类子路径时服务器需回退到 `index.html`，否则 404。

   Nginx 示例：

   ```nginx
   location / {
       root   /usr/share/nginx/html;
       index  index.html;
       try_files $uri $uri/ /index.html;
   }
   ```

2. **修改后端地址**：构建前把 `.env.production` 中的 `VITE_API_BASE_URL` 改成真实域名。

3. **确保后端允许该来源跨域**：将后端 `CORS_ALLOWED_ORIGINS` 设置为前端实际域名（不要保留 `*`）。

### 本地预览产物

```bash
npm run preview
```

---

## 十一、常见问题

**Q1：登录提示「登录已失效」或一直跳回登录页**

后端未启动或地址不对。检查 `.env.development` 的 `VITE_API_BASE_URL` 是否与后端端口一致，并确认后端已在运行。

**Q2：请求被浏览器 CORS 拦截**

后端 `app.cors.allowed-origins` 未包含前端来源。开发环境默认为 `*`，若已改为白名单，记得把 `http://localhost:5173` 加进去。

**Q3：`npm run build-only` 能过，但代码里有类型错误**

`vite build` 只做转译不做类型检查。请使用 `npm run build`（含 `type-check`）或单独运行 `npm run type-check`。

**Q4：`npm run dev` 报 Node 版本不兼容**

`package.json` 要求 Node `^22.18.0 || >=24.12.0`，升级 Node 后重试。

**Q5：修改了 `routes.ts` 但菜单没变化**

检查是否只加了 `menuRoutes` 项而未重启开发服务器；正常情况下路由与菜单会自动同步，若页面报「找不到组件」则核对 `component` 的导入路径。

**Q6：导出的 Excel 打不开**

若后端返回的是错误 JSON，`download()` 会识别并提示业务错误而不是生成文件。若确实生成了损坏文件，检查后端导出接口是否抛出了未捕获异常。

---

*本文档随代码同步维护，若页面或配置有调整请一并更新。*