sms-server/README.md

# 学生管理系统 (Student Management System)

基于Spring Boot 3.3.3 + Spring Security + MyBatis Plus的学生管理系统，支持专业、班级、学生、教师的完整管理功能。

## 📋 项目概述

这是一个现代化的学生信息管理系统，提供了完整的教育机构信息化解决方案。系统采用微服务架构设计，模块化开发，支持批量导入导出、权限管理等企业级功能。

### 核心功能模块

- **专业管理**: 支持专业的增删改查，批量导入导出
- **班级管理**: 基于专业的班级管理，支持代码关联
- **学生管理**: 完整的学生信息管理，支持账号自动创建
- **教师管理**: 教师信息管理，支持账号自动创建
- **用户权限**: 基于角色的权限控制系统

## 🛠️ 技术栈

### 后端技术
- **Spring Boot 3.3.3** - 主框架
- **Spring Security** - 安全认证与授权
- **MyBatis Plus 3.5.7** - 数据库ORM框架
- **MySQL 8.0** - 数据库
- **Redis** - 缓存
- **EasyExcel 4.0.3** - Excel导入导出
- **JWT** - Token认证
- **Lombok** - 简化开发
- **HikariCP** - 数据库连接池

### 开发工具
- **Maven 3.x** - 项目构建
- **Java 17** - 开发语言
- **IntelliJ IDEA** - IDE（推荐）

## 🏗️ 项目结构

```
yuxingshi-sms/
├── yuxingshi-sms-common/           # 公共模块
│   ├── yuxingshi-sms-core/        # 核心工具类
│   ├── yuxingshi-sms-redis/       # Redis配置
│   ├── yuxingshi-sms-mybatisplus/ # MyBatis Plus配置
│   ├── yuxingshi-sms-security/    # 安全模块
│   └── yuxingshi-sms-intercepter/ # 拦截器
├── yuxingshi-sms-server/          # 主服务模块
│   ├── src/main/java/
│   │   └── yuxingshi/sms/server/
│   │       ├── controller/         # 控制器层
│   │       ├── service/           # 服务层
│   │       ├── mapper/            # 数据访问层
│   │       └── domain/            # 实体和DTO
│   └── src/main/resources/
│       └── application.yaml       # 配置文件
└── deploy/                       # 部署配置
    └── dev/                      # 开发环境配置
```

## 🚀 快速开始

### 环境要求

- JDK 17+
- Maven 3.x
- MySQL 8.0+
- Redis 6.0+

### 本地开发部署

1. **克隆项目**
```bash
git clone <repository-url>
cd yuxingshi-ssm
```

2. **数据库配置**
```yaml
# application.yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/yxs_sms?useSSL=false&serverTimezone=GMT%2B8
    username: your_username
    password: your_password
```

3. **Redis配置**
```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: your_redis_password
```

4. **编译和运行**
```bash
# 编译项目
mvn clean compile

# 启动服务
mvn spring-boot:run -pl yuxingshi-sms-server
```

5. **访问应用**
- 服务地址: http://localhost:8080
- API文档: http://localhost:8080/swagger-ui.html

## 📊 数据库设计

### 核心表结构

| 表名 | 说明 | 关键字段 |
|------|------|----------|
| `user` | 用户表 | id, username, password, role, status |
| `major` | 专业表 | id, major_code, major_name, description |
| `classes` | 班级表 | id, class_code, major_id, description |
| `student` | 学生表 | id, user_id, class_id, student_no, real_name |
| `teacher` | 教师表 | id, user_id, teacher_no, real_name, department |

### ER关系
- 一个专业可以有多个班级
- 一个班级可以有多个学生
- 每个学生和教师都有对应的用户账号

## 🎯 核心功能

### 1. 批量导入功能

系统支持Excel批量导入，具有以下特性：

#### 专业导入
- 支持专业代码、专业名称、描述信息
- 自动去重校验
- 批量导入高性能处理

#### 班级导入
- 支持班级代码、专业代码关联
- 自动通过专业代码查询专业ID
- 数据完整性校验

#### 学生导入
- 支持学号、姓名、性别、手机号、班级代码
- 自动创建用户账号（用户名=学号，密码=学号）
- 批量处理User和Student表，保证事务一致性
- 自动关联班级信息

#### 教师导入
- 支持工号、姓名、部门、手机号
- 自动创建用户账号（用户名=工号，密码=工号）
- 批量处理User和Teacher表，保证事务一致性

### 2. 权限管理

- **学生角色**: 查看个人信息
- **教师角色**: 教学相关功能
- **管理员角色**: 完整的管理功能

### 3. 状态管理

使用枚举统一管理所有实体的状态：
- `EntityStatus.ACTIVE` (启用) = 1
- `EntityStatus.DISABLED` (禁用) = 0

## 🔧 API接口

### 认证接口
```http
POST /api/users/login      # 用户登录
GET  /api/users/detail     # 获取用户信息
```

### 专业管理
```http
GET    /api/majors         # 查询专业列表
POST   /api/majors         # 创建专业
PUT    /api/majors/{id}    # 更新专业
DELETE /api/majors/{id}    # 删除专业
POST   /api/majors/import  # 批量导入专业
```

### 班级管理
```http
GET    /api/classes        # 查询班级列表
POST   /api/classes        # 创建班级
PUT    /api/classes/{id}   # 更新班级
DELETE /api/classes/{id}   # 删除班级
POST   /api/classes/import # 批量导入班级
```

### 学生管理
```http
GET    /api/students       # 查询学生列表
POST   /api/students       # 创建学生
PUT    /api/students/{id}  # 更新学生
DELETE /api/students/{id}  # 删除学生
POST   /api/students/import # 批量导入学生
```

### 教师管理
```http
GET    /api/teachers       # 查询教师列表
POST   /api/teachers       # 创建教师
PUT    /api/teachers/{id}  # 更新教师
DELETE /api/teachers/{id}  # 删除教师
POST   /api/teachers/import # 批量导入教师
```

## 🔐 安全特性

- **JWT认证**: 无状态Token认证
- **密码加密**: BCrypt加密存储
- **权限控制**: 基于角色的访问控制
- **参数校验**: Spring Validation框架
- **SQL注入防护**: MyBatis Plus预编译

## 📈 性能优化

- **批量操作**: Excel导入使用批量插入，提升性能
- **数据库连接池**: HikariCP连接池优化
- **缓存策略**: Redis缓存热点数据
- **分页查询**: MyBatis Plus分页插件
- **索引优化**: 关键字段建立索引

## 🐛 错误处理

系统完善的错误处理机制：

1. **数据校验**: 必填字段校验、格式校验
2. **重复检查**: Excel内重复、数据库重复检查
3. **关联验证**: 专业代码、班级代码存在性验证
4. **事务回滚**: 批量操作失败时完整回滚
5. **友好提示**: 详细的错误信息返回

## 🔧 配置说明

### 批量导入配置
```yaml
app:
  import:
    # 批量插入大小，避免内存溢出
    major:
      batch-insert-size: 100
    class:
      batch-insert-size: 100
    student:
      batch-insert-size: 500
    teacher:
      batch-insert-size: 500
```

### 文件上传配置
```yaml
spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 20MB
```

## 📝 更新日志

### v1.0.0 (2024-11-21)
- ✨ 完整的CRUD功能
- 🚀 Excel批量导入导出
- 🔐 JWT权限认证
- 📊 多条件分页查询
- 🎯 批量操作事务优化
- 🏷️ 状态管理枚举化

## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系方式

- 项目维护者: yuxingshi
- 邮箱: [your-email@example.com]
- 项目地址: [repository-url]

---

**注意**: 这是一个演示项目，实际生产环境使用前请进行充分测试。