# 学生实训考勤管理系统

**Repository Path**: two_u/attendance

## Basic Information

- **Project Name**: 学生实训考勤管理系统
- **Description**: 要通过递交请假申请让班主任批准方能生效。这种模式在目前高校管理中暴露了不可避免的弊端：
1. 学生请假不方便；
2. 学生请假对任课老师不透明；
3. 学生不清楚自己的考勤情况
4. 老师对学生整体出勤情况不方便统计

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: test
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2021-06-07
- **Last Updated**: 2025-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

> 本文档描述了实训考勤系统的工程架构以及代码规约，后续开发请尽量遵守该文档所描述的相关约束。

# 环境准备

- JDK8
- IDEA Ultimate / Community
- IDEA Plugin：MybatisX、Lombok
# 快速开始


- 使用IDEA打开该项目
> open -> select this project roor dictionary -> This/New Window

- 等待Maven构建完成
- 运行application模块中xyz/second/training_manage_system/TrainingManageSystemApplication.java的main函数。
- 访问http://localhost:5000
# 项目架构
> 业务模块如有遗漏需求，请重新拆分或新增业务模块

## 总工程结构
> 本工程为多模块的Web工程，除通用模块外，子模块基本按需求模块中的功能需求拆分

> 功能需求按业务进行拆分，对于不同的角色，可能能使用模块中部分或全部功能

> 本工程的模块结构如下所示

- training_manage_system
    - application 应用主模块，全局的拦截器、应用配置在该模块配置，也是应用启动模块
    - common 通用模块，包含所有模块通用工具类和其他配置类
    - database 数据库模块，包含数据库实体定义和通用的mapper定义
    - ask_for_leave_manage_module 请假管理模块，老师/管理员查询审批请假，学生申请请假等
    - attendance_manage_module 考勤管理模块，老师/管理员管理考勤，学生考勤记录等
    - auth_module 认证模块，用户登录/登出。
    - course_manage_module 课程管理模块，管理员用
    - homework_manage_module 作业管理模块，老师/管理员管理、发布作业，学生提交作业等
    - personal_info_module 个人信息模块，个人信息管理，修改密码
    - project_course_table_manage_module 项目课程表管理模块，管理员用
    - project_group_manage_module 项目组管理模块，管理员用
    - scoring_module 综合打分模块
    - user_info_manage_module 用户信息管理模块，包含教师和学生信息管理，管理员用
> 其中以module结尾的模块，属于业务模块，所有的业务模块都依赖于common和database模块

> application模块依赖其他所有模块，作为应用入口

## 单服务模块工程结构
### application模块
> application模块中，TrainingManageSystem.java是应用入口，用于应用启动。

> 该模块中，包前缀为xyz.second.training_manage_sytem，该包下的其他子包自定义。

> 通常，filter下为全局过滤器，config下为应用配置类（依赖注入的一些配置）。

> resources文件夹下，application.yml为应用配置文件。

> resources/static下为打包好的vue应用。

### common模块
> common模块中，包前缀为xyz.second.common，子包无固定结构

### database模块
> database模块中，包前缀为xyz.second.database

> 包含entity和mapper子包。

> entity中是与数据库表映射的实体，mapper是dao层，提供数据库访问

> resources/mapper文件夹下为Mybatis的SQL映射文件

### 业务(module)模块
> 以module结尾的业务模块的工程结构，参考ask_for_leave_module和auth_module模块

> 包前缀为xyz.second.module_name，其中module_name为该模块的名称

> 子包的结构如下：
> - config 包含应用的配置类，注意不要与其他模块的配置类类名相同
> - controller 接口Controller类，可以按业务功能+角色进行Controller拆分
> - dto 接口body参数类定义
> - mapper 数据库访问mapper类，与database模块中不同，这里通常是与业务本身相关需要自定义sql的
    >    - result 供SQL映射xml文件需要的查询resultMap使用的类
> - service 服务接口定义
    >    - impl 服务实现
> - utils 工具类包
> - vo 返回给前端的数据类结构定义
>
resources/mapper文件夹下为Mybatis的SQL映射文件

## 技术架构
> 基本架构使用Spring Boot，加上使用其他一些辅助库

### Web服务
> Spring Boot Web Starter，里面就是Spring MVC啦

### 授权认证
> 基于Session和WebFilter的授权认证

> 利用Session存储用户登录信息，使用全局WebFilter对请求进行过滤，做访问鉴权

### 数据库
> 使用Mybatis Plus进行数据库访问，数据库驱动使用mysql-connector-java

> Mybatis Plus是Mybatis的加强版，可以使用Mybatis的所有功能，提供默认的ORM接口

### 接口校验
> spring-boot-starter-validation做数据接口校验，主要是用来判空

> 用到Validation和NotNull两个注解

### Lombok
> 一个插件，可以通过注解在编译阶段给类自动生成Getter、Setter和Constructor等

# 项目规约
## 包结构及分层逻辑规约

- 各模块下的Mybatis SQL映射XML文件，必须放在各自模块的resources/mapper文件夹下
- 业务模块(module结尾)的包结构规约
    - 前置base包名为xyz.second.module_name，其中module_name为模块名称
    - config：放置@Configuration注解的配置类
    - controller：放置@RestController注解的控制器，注意，前后端分离，尽量不要使用@Controller，尽量都以JSON方式通信，请使用@RestController。注意，Controller中尽量不要包含业务逻辑，仅作输入数据的校验以及到Service接口的数据转化。
    - dto：放置请求Body的类定义，仅需定义类的属性，并且加上@Data和@NoArgsConstructor注解。否则，务必保证该类至少包含所有属性的Getter和一个无参构造器。
    - mapper：放置数据库访问的Mapper类，mapper/result放置自定义sql响应的resultMap类
    - service：放置服务接口（业务逻辑）定义，service/impl中放置service接口实现。service类是主要的业务逻辑实现类，请不要把业务逻辑放到controller中实现。
    - utils：放置一些工具类
    - vo：放置接口响应给前端的data数据类，仅需定义类的属性，并且加上@Data和@NoArgsConstructor注解。否则，务必保证该类至少包含所有属性的Getter和一个无参构造器。
## 接口规约（非强制）
> 尽可能遵循RESTful风格

- Get请求不要携带Body，不要携带Body，不要携带Body，尽可能使用路径参数（@PathVariable）和查询参数（@RequestParam）。
- Post请求尽可能都以Body形式传输，尽量不要携带路径参数和查询参数，通常用来创建数据
- Put请求尽可能都以Body形式传输，尽量不要携带路径参数和查询参数，通常用来更新数据
> 注：Put请求具有幂等性，Post请求不具有幂等性。这意味着，当发起两个相同的请求时，第二次Put请求不会覆盖第一次请求所造成的结果，而Post请求会。因此Post请求通常用来创建新数据，Put请求通常用来更新数据。

- Delete请求不要携带Body，尽可能使用路径参数（@PathVariable）和查询参数（@RequestParam）传递需要删除数据的id，批量删除则使用body传递id列表。删除数据必须使用Delete请求，不要使用Get、Post和Put。
- 请求响应尽量使用Http状态码表达请求结果的含义，不要使用通用的Body反应错误信息，例如如下响应数据。使用通用错误body响应不符合RESTful风格。
```json
{
  "code": "-1",
  "message": "unknown error"
}
```
## 异常处理（非强制）

- 预期外的异常不需要特殊处理，属于BUG，这类异常Spring Boot会自动响应500状态码，发现该请求异常，请通知对应的负责人修复BUG
- 预期内的异常请在对应模块内新建异常类，通常是在service接口中定义的内部异常类，见ask_for_leave_module中的示例。该异常类继承自common模块中定义的ResponsiveException，会响应传递的Http状态码给调用方（见common模块中ResponsiveExceptionHandler全局异常处理器）。接口开发者和调用者需要明确在该接口中，响应该非请求成功的Http状态码的含义。
## 权限管理
> 某个接口如果需要某个角色的权限才能访问，则该接口的路由定义中请包含角色的名称。例如学生请假需要学生权限，则路由中必须包含student。见common模块中auth包中的UserType定义，ask_for_leave_manage_module中Controller的示例，以及application模块中，SessionFilter类对接口访问的鉴权。

# 部署
> 直接运行training_manage_sytstem这个root工程下的maven的package命令，打包成jar，见application模块中target/application-1.0.0.jar。拿出来，扔到服务器上，执行如下命令

```shell
java -jar application-1.0.0.jar
```

# 其他
## Session管理
> 登录接口中会设置用户的Session，获取用户Session中的信息，参考ask_for_leave_module中Controller的示例。

> 不要在每个Controller接口中校验用户的登录态，请使用全局WebFilter，见application模块中的SessionFilter示例。

## 全局异常处理
> 预期内异常请通过全局异常处理器处理，尽量遵循RESTful风格（可以不用），使用对应错误Http状态码响应。见common模块中exception包内的处理器示例，以及ask_for_leave_manage_module中service包内的示例