# srs

**Repository Path**: arbog/srs

## Basic Information

- **Project Name**: srs
- **Description**: 教务管理系统 
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教务管理系统 (EMS)

基于 **Laravel 13** + **Vue 3** + **Element Plus** + **MySQL 8.0** 的 Web 教务管理系统。

> 最后更新：2026-05-27

---

## 目录

1. [功能模块](#功能模块)
2. [技术栈](#技术栈)
3. [环境要求](#环境要求)
4. [快速启动](#快速启动)
5. [环境配置说明](#环境配置说明)
6. [数据库初始化](#数据库初始化)
7. [测试账号](#测试账号)
8. [项目结构](#项目结构)
9. [生产环境部署](#生产环境部署)
10. [常见问题](#常见问题)
11. [API 路由一览](#api-路由一览)
12. [常用命令速查](#常用命令速查)

---

## 功能模块

- **学生管理** — 学生信息 CRUD、状态流转（在读/休学/退学/毕业/开除）及审计日志
- **班级管理** — 班级信息管理，关联院系和班主任
- **院系管理** — 院系基础数据维护
- **考勤管理** — 每日考勤记录、考勤统计
- **请假管理** — 请假申请与审批流程
- **考试管理** — 考试安排、考生注册
- **成绩管理** — 成绩录入与查询

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端框架 | Laravel 13.x |
| 前端框架 | Vue 3.4+ (Composition API + `<script setup>`) |
| UI 组件 | Element Plus |
| 构建工具 | Vite |
| 状态管理 | Pinia |
| 数据库 | MySQL 8.0+ (InnoDB, utf8mb4_unicode_ci) |
| 认证 | Laravel Sanctum (Token 模式) |
| 权限 | Spatie laravel-permission (RBAC) |
| API 格式 | RESTful + JsonResource |

---

## 环境要求

### 最低版本

| 组件 | 版本 | 说明 |
|------|------|------|
| PHP | >= 8.3 | 推荐 8.4+，需启用 `pdo_mysql`、`curl`、`mbstring`、`fileinfo` 等扩展 |
| MySQL | >= 8.0 | 需 InnoDB 引擎，字符集 `utf8mb4_unicode_ci` |
| Composer | >= 2.5 | PHP 依赖管理 |
| Node.js | >= 20 | 前端构建 |
| npm | >= 10 | 前端依赖管理 |

### 必需 PHP 扩展

```bash
php -m | grep -E "pdo_mysql|curl|mbstring|fileinfo|bcmath|xml|zip|openssl|gd"
```

- `pdo_mysql` — 数据库连接
- `curl` — HTTP 请求
- `mbstring` — 多字节字符串
- `fileinfo` — 文件类型检测
- `bcmath` — 精确数学运算
- `xml` / `xmlwriter` — XML 解析
- `zip` — 归档处理
- `openssl` — 加密
- `gd` — 图片处理（扩展需求）

---

## 快速启动

```bash
# 1. 安装 PHP 依赖
composer install --no-interaction

# 2. 配置环境变量
copy .env.example .env
php artisan key:generate

# 3. 编辑 .env，配置数据库连接（见下方说明）

# 4. 初始化数据库
php artisan migrate --seed

# 5. 安装前端依赖 & 构建
npm install
npm run build

# 6. 启动开发服务
php artisan serve --port=8000
# 访问 http://localhost:8000
```

### 前端热更新（开发模式）

```bash
# 终端 1 - Laravel 后端
php artisan serve --port=8000

# 终端 2 - Vite 前端热更新
npm run dev   # 访问 http://localhost:5173
```

> Vite 启动时，Vue 页面自动热重载，API 请求自动代理到 `localhost:8000`。

---

## 环境配置说明

### 核心 `.env` 配置项

| 配置项 | 说明 | 开发环境示例 |
|--------|------|-------------|
| `APP_NAME` | 应用名称 | `EMS` |
| `APP_ENV` | 运行环境 | `local` / `production` |
| `APP_DEBUG` | 调试模式 | `true` / `false` |
| `APP_URL` | 应用地址 | `http://localhost:8000` |
| `DB_CONNECTION` | 数据库类型 | `mysql` |
| `DB_HOST` | 数据库地址 | `127.0.0.1` |
| `DB_PORT` | 数据库端口 | `3306` |
| `DB_DATABASE` | 数据库名称 | `ems` |
| `DB_USERNAME` | 数据库用户 | `root` |
| `DB_PASSWORD` | 数据库密码 | 你的 MySQL 密码 |

### 完整 `.env` 参考

```env
APP_NAME=EMS
APP_ENV=local
APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ems
DB_USERNAME=root
DB_PASSWORD=your_password_here

SESSION_DRIVER=database
SESSION_LIFETIME=120

CACHE_STORE=database
QUEUE_CONNECTION=database

FILESYSTEM_DISK=local
```

### Vue 前端配置

| 文件 | 作用 |
|------|------|
| `resources/js/api/request.js` | Axios 实例，配置拦截器和基础 URL |
| `resources/js/api/*.js` | 各模块 API 封装 |
| `resources/js/router/index.js` | Vue Router 路由及鉴权守卫 |
| `resources/js/stores/auth.js` | Pinia 认证状态管理 |

---

## 数据库初始化

### 创建数据库

```sql
CREATE DATABASE IF NOT EXISTS ems
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;
```

或通过命令行：

```bash
mysql -u root -p -e "CREATE DATABASE ems CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

### 运行迁移

```bash
php artisan migrate:fresh --seed --force
```

### 迁移文件清单

以下 17 张表按顺序创建：

| 序号 | 迁移文件 | 表名 | 说明 |
|------|---------|------|------|
| 1 | `0001_01_01_000000_create_users_table` | `users` | 用户（含 user_type, softDeletes） |
| 2 | `0001_01_01_000001_create_cache_table` | `cache` / `cache_locks` | 缓存 |
| 3 | `0001_01_01_000002_create_jobs_table` | `jobs` / `job_batches` / `failed_jobs` | 队列 |
| 4 | `062355_create_permission_tables` | `permissions` / `roles` / `model_has_*` | Spatie RBAC |
| 5 | `062357_create_personal_access_tokens_table` | `personal_access_tokens` | Sanctum API 令牌 |
| 6 | `062430_create_departments_table` | `departments` | 院系 |
| 7 | `062431_create_classes_table` | `classes` | 班级（softDeletes） |
| 8 | `062431_create_student_status_definitions_table` | `student_status_definitions` | 学生状态定义 |
| 9 | `062432_create_students_table` | `students` | 学生（softDeletes） |
| 10 | `062432_create_teacher_profiles_table` | `teacher_profiles` | 教师档案（softDeletes） |
| 11 | `062433_create_attendance_records_table` | `attendance_records` | 考勤记录 |
| 12 | `062433_create_head_teacher_bindings_table` | `head_teacher_bindings` | 班主任绑定 |
| 13 | `062433_create_leave_requests_table` | `leave_requests` | 请假申请 |
| 14 | `062434_create_exams_table` | `exams` | 考试安排 |
| 15 | `062438_create_student_status_logs_table` | `student_status_logs` | 学生状态变更日志 |
| 16 | `062439_create_exam_students_table` | `exam_students` | 考试学生关联 |
| 17 | `062440_create_scores_table` | `scores` | 成绩记录 |

### 种子数据

运行 `php artisan db:seed` 后预置：

- **学生状态**：5 种（在读/休学/退学/毕业/开除）
- **院系**：4 个（计算机科学与技术学院、数学与统计学院、外国语学院、经济管理学院）
- **测试用户**：3 个账号（见下方）

---

## 测试账号

| 角色 | 邮箱 | 密码 | 说明 |
|------|------|------|------|
| 管理员 | `admin@edu.com` | `password` | 系统管理权限 |
| 教师 | `teacher@edu.com` | `password` | 教师角色 |
| 学生 | `student@edu.com` | `password` | 学生角色 |

---

## 项目结构

```
D:\code\student\
├── app/
│   ├── Enums/                     # PHP 8.1+ Enums
│   │   ├── AttendanceType.php
│   │   ├── EligibilityStatus.php
│   │   ├── ExamType.php
│   │   ├── LeaveStatus.php
│   │   ├── StudentStatus.php
│   │   └── UserType.php
│   ├── Http/
│   │   ├── Controllers/Api/       # API 控制器
│   │   │   ├── AuthController.php
│   │   │   ├── StudentController.php
│   │   │   ├── ClassController.php
│   │   │   ├── DepartmentController.php
│   │   │   ├── AttendanceController.php
│   │   │   ├── LeaveRequestController.php
│   │   │   ├── ExamController.php
│   │   │   └── ScoreController.php
│   │   ├── Requests/              # 表单验证
│   │   │   ├── StoreStudentRequest.php
│   │   │   └── UpdateStudentRequest.php
│   │   └── Resources/             # API 资源响应
│   │       ├── StudentResource.php
│   │       ├── ClassResource.php
│   │       ├── DepartmentResource.php
│   │       ├── AttendanceResource.php
│   │       ├── ExamResource.php
│   │       ├── ExamStudentResource.php
│   │       ├── LeaveRequestResource.php
│   │       ├── ScoreResource.php
│   │       └── StudentStatusLogResource.php
│   ├── Models/                    # Eloquent 模型（共 13 个）
│   │   ├── User.php
│   │   ├── Student.php
│   │   ├── Classes.php
│   │   ├── Department.php
│   │   └── ...
│   └── Services/                  # 业务逻辑层
│       ├── StudentService.php
│       ├── AttendanceService.php
│       ├── ExamService.php
│       └── ScoreService.php
├── bootstrap/app.php              # Laravel 应用配置
├── config/
│   ├── permission.php             # Spatie RBAC 配置
│   └── sanctum.php                # Sanctum 认证配置
├── database/
│   ├── migrations/                # 17 个迁移文件
│   └── seeders/                   # 种子文件
├── resources/
│   ├── css/app.css                # 全局样式
│   ├── js/                        # Vue 3 前端源码
│   │   ├── api/                   # Axios API 模块
│   │   ├── layouts/               # 布局组件
│   │   ├── router/                # Vue Router
│   │   ├── stores/                # Pinia 状态管理
│   │   └── views/                 # 页面组件
│   │       ├── auth/Login.vue
│   │       ├── dashboard/Index.vue
│   │       ├── students/Index.vue
│   │       ├── classes/Index.vue
│   │       ├── departments/Index.vue
│   │       ├── attendance/Index.vue
│   │       ├── leaves/Index.vue
│   │       ├── exams/Index.vue
│   │       └── scores/Index.vue
│   └── views/welcome.blade.php    # SPA 入口 Blade
├── routes/
│   ├── api.php                    # API 路由
│   └── web.php                    # Web 路由（Vue SPA 入口）
├── public/
│   └── build/                     # Vite 构建产物
├── PROJECT_SPEC.md                # 技术规格说明书
├── composer.json
├── package.json
└── vite.config.js
```

---

## 生产环境部署

### 准备环境

```bash
APP_ENV=production
APP_DEBUG=false

php artisan key:generate
composer install --optimize-autoloader --no-dev
```

### 前端构建

```bash
npm ci
npm run build
```

### Laravel 优化

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache
```

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name ems.example.com;
    root D:/code/student/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }

    location /build/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

### IIS 配置示例（Windows Server）

在 `public/web.config` 中：

```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="SPA Routes" stopProcessing="true">
                    <match url=".*" />
                    <conditions logicalGrouping="MatchAll">
                        <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
                        <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
                        <add input="{REQUEST_URI}" pattern="^/(api)" negate="true" />
                    </conditions>
                    <action type="Rewrite" url="/index.php" />
                </rule>
            </rules>
        </rewrite>
        <staticContent>
            <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="365.00:00:00" />
        </staticContent>
    </system.webServer>
</configuration>
```

### 调度器配置（定时任务）

```bash
# Linux (crontab)
* * * * * cd /path/to/student && php artisan schedule:run >> /dev/null 2>&1

# Windows (任务计划程序)
# 每分钟触发：D:\phpEnv\php\php-8.4\php.exe D:\code\student\artisan schedule:run
```

### 队列配置

```env
QUEUE_CONNECTION=redis

# 启动队列 Worker
php artisan queue:work --tries=3 --timeout=90
```

---

## 常见问题

### 数据库连接失败

```
SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost'
```

确认 `.env` 中的 `DB_PASSWORD` 与 MySQL root 密码一致。

### 白页 / 500 错误

```bash
cat storage/logs/laravel.log
php artisan storage:link
```

### API 返回 401

未携带有效的 Sanctum Token。先登录获取 token：

```bash
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@edu.com","password":"password"}'

# 后续请求携带 token
curl -H "Authorization: Bearer {token}" http://localhost:8000/api/students
```

### 前端页面空白 / 路由错误

Vue Router History 模式需要后端 fallback。确认 `routes/web.php` 包含：

```php
Route::get('/{any?}', function () {
    return view('welcome');
})->where('any', '.*');
```

### 迁移顺序冲突

如遇外键约束错误（`Failed to open the referenced table`），确认迁移时间戳顺序：

```bash
departments → classes → students → student_status_logs
exams → exam_students → scores
```

### MySQL 唯一索引名过长

MySQL 限制标识符最多 64 字符：

```php
// 错误（自动生成名称超长）
$table->unique(['user_id', 'class_id', 'academic_year', 'semester']);

// 正确（指定短名称）
$table->unique(['user_id', 'class_id', 'academic_year', 'semester'], 'htb_unique');
```

### 前端构建文件过大

Element Plus 全量引入导致 vendor 包约 1.2MB。建议按需引入：

```js
import {
  ElButton, ElTable, ElForm, ElDialog, ElMenu, ElTag,
  ElInput, ElSelect, ElDatePicker, ElPagination, ElMessage
} from 'element-plus';
```

---

## API 路由一览

| 方法 | 路径 | 控制器方法 | 说明 |
|------|------|-----------|------|
| POST | `/api/login` | AuthController@login | 登录 |
| POST | `/api/logout` | AuthController@logout | 登出 |
| GET | `/api/me` | AuthController@me | 当前用户信息 |
| GET/POST | `/api/students` | StudentController@index/store | 学生列表/创建 |
| GET/PUT/DELETE | `/api/students/{id}` | StudentController@show/update/destroy | 学生详情/更新/删除 |
| PATCH | `/api/students/{id}/status` | StudentController@changeStatus | 变更学生状态 |
| GET/POST | `/api/classes` | ClassController@index/store | 班级列表/创建 |
| GET/PUT/DELETE | `/api/classes/{id}` | ClassController@show/update/destroy | 班级详情/更新/删除 |
| GET/POST | `/api/departments` | DepartmentController@index/store | 院系列表/创建 |
| GET/PUT/DELETE | `/api/departments/{id}` | DepartmentController@show/update/destroy | 院系详情/更新/删除 |
| GET/POST | `/api/attendance` | AttendanceController@index/store | 考勤列表/创建 |
| GET | `/api/attendance/stats` | AttendanceController@stats | 考勤统计 |
| GET/POST | `/api/leave-requests` | LeaveRequestController@index/store | 请假列表/提交 |
| PATCH | `/api/leave-requests/{id}/approve` | LeaveRequestController@approve | 批准请假 |
| PATCH | `/api/leave-requests/{id}/reject` | LeaveRequestController@reject | 拒绝请假 |
| GET/POST | `/api/exams` | ExamController@index/store | 考试列表/创建 |
| POST | `/api/exams/{id}/register-students` | ExamController@registerStudents | 注册考生 |
| GET/POST | `/api/scores` | ScoreController@index/store | 成绩列表/录入 |

---

## 常用命令速查

```bash
# 查看全部 API 路由
php artisan route:list --path=api

# 重置数据库
php artisan migrate:fresh --seed

# 创建新迁移
php artisan make:migration create_xxx_table

# 构建前端
npm run build

# 查看日志
tail -f storage/logs/laravel.log

# 清除缓存
php artisan optimize:clear
```