# BJTU

**Repository Path**: pvthonc/bjtu

## Basic Information

- **Project Name**: BJTU
- **Description**: BJTU 线上家教发布与qq身份信息验证平台
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-06
- **Last Updated**: 2026-02-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 北京交通大学学生身份验证系统

这是一个用于验证北京交通大学学生身份与QQ号关联信息的前后端分离Web应用系统。

## 📋 项目简介

本系统允许北京交通大学学生通过邮箱验证生成5分钟有效的证明码，用于向他人证明自己的学号与QQ号的关联关系。验证方可以通过证明码查询并查看学号（支持掩码显示）和QQ号信息。

## ✨ 功能特性

- **生成证明码**：学生通过邮箱验证后生成5分钟有效的证明码
- **验证证明码**：通过证明码查询并显示学号和QQ号（支持学号掩码显示）
- **邮箱验证**：使用6位随机验证码，10分钟有效期
- **学号掩码**：可选择显示学号的前N位，保护隐私
- **访问日志**：记录所有验证请求的访问日志

## 🛠️ 技术栈

### 后端
- **框架**：Spring Boot 3.2.5
- **语言**：Java 17
- **数据库**：MySQL 8.0
- **ORM**：Spring Data JPA
- **邮件服务**：Spring Mail
- **构建工具**：Maven

### 前端
- **框架**：Vue 3
- **构建工具**：Vite 5.0
- **UI组件库**：Element Plus 2.6
- **路由**：Vue Router 4.3
- **状态管理**：Pinia 2.1
- **HTTP客户端**：Axios 1.6

## 📁 项目结构

```
bjtu-verification_b/
├── bjtu-verification-backend/     # Spring Boot 后端项目
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/bjtu/verification/
│   │   │   │       ├── controller/    # 控制器层
│   │   │   │       ├── service/       # 服务层
│   │   │   │       ├── repository/    # 数据访问层
│   │   │   │       ├── entity/        # 实体类
│   │   │   │       ├── dto/           # 数据传输对象
│   │   │   │       └── util/          # 工具类
│   │   │   └── resources/
│   │   │       └── application.yml    # 配置文件
│   │   └── test/
│   └── pom.xml                       # Maven 依赖配置
│
├── bjtu-verification-frontend/    # Vue 3 前端项目
│   ├── src/
│   │   ├── api/                    # API 接口定义
│   │   ├── views/                  # 页面组件
│   │   ├── router/                 # 路由配置
│   │   ├── utils/                  # 工具函数
│   │   ├── App.vue                 # 根组件
│   │   └── main.js                 # 入口文件
│   ├── public/                     # 静态资源
│   ├── package.json                # NPM 依赖配置
│   └── vite.config.js              # Vite 配置
│
└── 运行指南.md                      # 详细运行指南
```

## 🚀 快速开始

### 前置要求

- **Java**：JDK 17 或更高版本
- **Node.js**：16.x 或更高版本
- **MySQL**：8.0 或更高版本
- **Maven**：3.6+（用于构建后端）
- **npm** 或 **yarn**（用于安装前端依赖）

### 1. 数据库准备

创建MySQL数据库：

```sql
CREATE DATABASE bjtu_verification CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 2. 后端配置与启动

#### 2.1 修改配置文件

编辑 `bjtu-verification-backend/src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/bjtu_verification?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: root          # 修改为你的MySQL用户名
    password: password      # 修改为你的MySQL密码

  mail:
    host: smtp.qq.com
    port: 587
    username: your-email@qq.com    # 修改为你的QQ邮箱
    password: your-auth-code       # 修改为QQ邮箱授权码
```

#### 2.2 构建项目

在 `bjtu-verification-backend` 目录下执行：

```bash
mvn clean package
```

构建成功后应看到 `BUILD SUCCESS`。

#### 2.3 启动后端服务

```bash
mvn spring-boot:run
```

启动成功后应看到：
```
Tomcat started on port(s): 8080
Started VerificationApplication in XX seconds
```

后端服务运行在 **http://localhost:8080**

### 3. 前端配置与启动

#### 3.1 安装依赖

在 `bjtu-verification-frontend` 目录下执行：

```bash
npm install
```

#### 3.2 启动开发服务器

```bash
npm run dev
```

启动成功后应看到：
```
VITE v5.x  ready in Xs

➜  Local:   http://localhost:5173/
```

前端应用运行在 **http://localhost:5173**

#### 3.3 构建生产版本（可选）

```bash
npm run build
```

构建产物将输出到 `dist/` 目录。

## 📖 使用说明

### 生成证明码流程

1. 访问前端首页（http://localhost:5173）
2. 点击"生成证明码"
3. 输入北交大邮箱（学号@bjtu.edu.cn）和QQ号
4. 选择要显示的学号位数（用于掩码显示）
5. 接收邮箱验证码（6位数字，10分钟有效）
6. 输入验证码完成验证
7. 获取5分钟有效的证明码
8. 将证明码分享给他人

### 验证证明码流程

1. 访问前端首页
2. 点击"验证证明码"
3. 输入对方提供的证明码
4. 查看验证结果：
   - 学号（掩码显示）
   - QQ号
   - 剩余有效时间

## 🔧 配置说明

### 后端配置项（application.yml）

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `app.verification-code-expiry` | 邮箱验证码有效期（秒） | 600（10分钟） |
| `app.proof-code-expiry` | 证明码有效期（秒） | 300（5分钟） |
| `app.default-mask-digits` | 默认学号显示位数 | 4 |
| `app.allow-any-email` | 测试模式：允许任意邮箱 | false |
| `app.test-student-id` | 测试模式：固定学号 | - |

### 前端配置

前端API请求地址配置在 `src/api/verification.js` 中，默认指向 `http://localhost:8080`。

如需修改后端地址，请编辑该文件中的 `baseURL`。

## 🐛 常见问题

### 后端启动问题

1. **`Access denied for user`**
   - 检查 `application.yml` 中的数据库用户名和密码是否正确

2. **`Unknown database 'bjtu_verification'`**
   - 确保已创建数据库，参考"数据库准备"部分

3. **`Port 8080 is already in use`**
   - 8080端口被占用，可以：
     - 关闭占用8080端口的程序
     - 修改 `application.yml` 中的 `server.port` 配置

4. **邮件发送失败**
   - 检查QQ邮箱授权码是否正确
   - 确保已开启QQ邮箱的SMTP服务
   - 检查网络连接

### 前端启动问题

1. **`npm install` 失败**
   - 检查网络连接
   - 尝试使用 `npm install --registry=https://registry.npmmirror.com`（使用国内镜像）

2. **无法连接后端API**
   - 确保后端服务已启动
   - 检查 `src/api/verification.js` 中的 `baseURL` 配置
   - 检查浏览器控制台的错误信息

## 📝 API 接口文档

### 生成验证码

**POST** `/api/verification/send-code`

请求体：
```json
{
  "email": "student@bjtu.edu.cn",
  "qqNumber": "123456789"
}
```

响应：
```json
{
  "success": true,
  "message": "验证码已发送"
}
```

### 验证验证码并生成证明码

**POST** `/api/verification/verify-code`

请求体：
```json
{
  "email": "student@bjtu.edu.cn",
  "qqNumber": "123456789",
  "verificationCode": "123456",
  "maskDigits": 4
}
```

响应：
```json
{
  "success": true,
  "data": {
    "proofCode": "abc123def456",
    "expiresAt": "2024-01-01T12:05:00"
  }
}
```

### 验证证明码

**POST** `/api/verification/check-proof`

请求体：
```json
{
  "proofCode": "abc123def456"
}
```

响应：
```json
{
  "success": true,
  "data": {
    "studentId": "1234****",
    "qqNumber": "123456789",
    "expiresAt": "2024-01-01T12:05:00",
    "remainingSeconds": 180
  }
}
```

## 🔒 隐私与安全

- 证明码有效期仅5分钟，过期后相关信息将被自动删除
- 学号支持掩码显示，用户可选择展示的位数
- 邮箱验证码有效期10分钟
- 所有访问记录都会记录在访问日志中

## 📄 许可证

MIT License

## 👥 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题或建议，请通过以下方式联系：
- 提交 GitHub Issue
- 发送邮件至项目维护者

---

**注意**：本项目仅供学习和研究使用。在生产环境部署前，请确保：
1. 修改默认的数据库密码和邮箱配置
2. 配置合适的HTTPS证书
3. 设置强密码策略
4. 定期备份数据库
5. 监控系统日志和性能指标