# 权限管理

**Repository Path**: wusli/123

## Basic Information

- **Project Name**: 权限管理
- **Description**: 权限管理（李金松）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Signing Backend

基于 Java 17、Spring Boot、PostgreSQL、MyBatis 的课堂签到后端系统，支持教师发起签到、学生扫码签到、实时名单查看及数据导出。

## 技术栈

- Java 17
- Spring Boot 3.5
- Spring Security + JWT
- PostgreSQL
- MyBatis 3.0 (注解 + XML 混合 Mapper)
- Swagger-UI / OpenAPI 3
- H2 (测试用内存数据库)

## 项目结构

```
src/main/java/top/sandau/signingbackend
├── config          # Spring / Security / OpenAPI / WebMvc 配置
├── controller      # REST API 控制器
├── domain          # 领域对象 (实体/枚举)
├── dto             # 请求与响应对象
├── entity          # 数据库实体 (不含 Lombok)
├── exception       # 自定义异常 + 全局异常处理器
├── interceptor     # 权限拦截器 (JWT 验证 + 角色校验)
├── mapper          # MyBatis Mapper 接口
├── security        # 认证相关封装
├── service         # 业务逻辑
└── util            # 工具类 (JWT)

src/main/resources
├── application.properties
├── schema.sql              # 主数据库表结构
└── mapper/                 # MyBatis XML 映射文件

sql/
└── init_permission.sql      # 权限系统初始化数据

scripts/
├── init-db.sh               # 数据库初始化脚本
└── start-local-db.sh        # 本地 PostgreSQL 启动脚本
```

## 主要功能模块

### 1. 用户与权限管理

- 用户 CRUD、角色分配、账号状态管理
- 四种角色：管理员(ADMIN)、教师(TEACHER)、辅导员(COUNSELOR)、学生(STUDENT)
- 基于 JWT 的接口鉴权，支持匿名访问注解 `@AnonymousAccess`
- 角色权限注解 `@RequireRole` / `@RequirePermission`

### 2. 班级与课程管理

- 行政班：辅导员管理所属学生
- 教学班：教师创建、管理课程及学生名单
- 学生-行政班/教学班多对多关联

### 3. 签到管理 (核心)

| 接口 | 说明 |
|------|------|
| `POST /api/signin/activities` | 教师创建签到活动 |
| `GET /api/signin/activities/{id}` | 获取签到活动详情 |
| `GET /api/signin/activities/class/{classId}` | 获取班级所有签到活动 |
| `POST /api/signin/activities/{id}/close` | 关闭签到活动 |
| `POST /api/signin/codes/generate` | 教师生成当前签到码 |
| `GET /api/signin/codes/{activityId}` | 获取当前有效签到码 |
| `POST /api/signin/sign` | 学生扫码签到 |
| `GET /api/signin/records/{activityId}` | 获取活动签到名单 |
| `GET /api/signin/records/student/{studentId}` | 学生查看个人签到记录 |
| `GET /api/statistics/attendance` | 班级考勤统计 |
| `GET /api/statistics/export` | 导出考勤 CSV |

**签到码机制：**
- 教师生成 4 位数字验证码，有效期 30 分钟
- 学生输入签到码完成签到
- 防重复签到：同一活动同一学生只能签到一次

## 快速开始

### 1. 启动本地 PostgreSQL

```bash
./scripts/start-local-db.sh
```

### 2. 初始化数据库

```bash
./scripts/init-db.sh
```

### 3. 启动应用

```bash
./mvnw spring-boot:run
```

### 4. 打开接口文档

- Swagger-UI: [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)
- OpenAPI JSON: [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs)

## 默认测试账号

| 角色 | 用户名 | 密码 |
|------|--------|------|
| 管理员 | admin | admin123 |
| 教师 | teacher | teacher123 |
| 辅导员 | counselor | counselor123 |
| 学生 | student | student123 |

### 登录获取 JWT

```bash
curl -X POST 'http://localhost:8080/api/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}'
```

返回示例：
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 86400
  }
}
```

携带 Token 访问受保护接口：
```bash
curl -H 'Authorization: Bearer <accessToken>' \
  'http://localhost:8080/api/signin/activities'
```

## API 鉴权说明

除以下路径外，所有 `/api/**` 接口均需认证：
- `POST /api/auth/login` - 登录
- `POST /api/auth/register` - 注册
- `GET /swagger-ui/**` / `GET /v3/api-docs/**` - 文档

角色权限说明：
- `ADMIN` - 全部权限
- `TEACHER` - 签到管理、班级统计
- `COUNSELOR` - 行政班统计
- `STUDENT` - 签到、个人记录查看

## 测试

```bash
./mvnw test
```

测试使用 H2 内存数据库 (PostgreSQL 兼容模式)，不依赖本地 PostgreSQL。

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DB_URL` | PostgreSQL 连接地址 | `jdbc:postgresql://localhost:5432/signing_backend` |
| `DB_USERNAME` | 数据库用户名 | `postgres` |
| `DB_PASSWORD` | 数据库密码 | `postgres` |
| `DB_INIT_MODE` | 是否初始化数据库 | `never` |
| `JWT_SECRET` | JWT 密钥 | `local-dev-jwt-secret-...` |
| `JWT_EXPIRE_SECONDS` | Token 有效期(秒) | `7200` |