# spring-tutorial

**Repository Path**: SirLeon/spring-tutorial

## Basic Information

- **Project Name**: spring-tutorial
- **Description**: 开源的Spring项目基础代码。
更多有趣的内容，尽在pi-apple.com
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Tutorial API

Spring Boot 教学项目，演示用户管理、阶段任务管理、文件上传下载等功能。

## 快速开始

### 环境要求

- JDK 17+
- MySQL 8.0+
- Redis (可选，用于Token管理)

### 配置数据库

1. 创建数据库并初始化表结构：
```bash
# 方式一：使用 MySQL 命令行
mysql -u root -p < sql/init.sql

# 方式二：登录 MySQL 后执行
mysql -u root -p
source /path/to/sql/init.sql
```

或者手动创建：
```sql
CREATE DATABASE spring_demo;
```

2. 修改 `src/main/resources/application.properties` 中的数据库连接配置：
```properties
spring.datasource.url=jdbc:mysql://localhost:3306/spring_demo?useSSL=false&useUnicode=true&characterEncoding=utf-8&serverTimezone=UTC&allowPublicKeyRetrieval=true
spring.datasource.username=root
spring.datasource.password=你的密码
```

### 启动项目

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

项目启动后访问：
- 应用地址：http://localhost:8888
- Swagger UI：http://localhost:8888/swagger-ui/index.html
- OpenAPI 文档：http://localhost:8888/v3/api-docs

---

## Swagger API 测试指南

### 1. 用户注册

**接口**：`POST /user/register`

**步骤**：
1. 打开 Swagger UI，找到 **用户管理** 分组
2. 点击 `POST /user/register` 接口
3. 点击 **Try it out**
4. 在 Request body 中输入：
```json
{
  "userName": "张三",
  "userAccount": "zhangsan",
  "userPassword": "123456"
}
```
5. 点击 **Execute** 执行
6. 查看响应结果，成功返回：
```json
{
  "code": 200,
  "message": "注册成功",
  "data": null
}
```

---

### 2. 用户登录

**接口**：`POST /user/login`

**步骤**：
1. 找到 `POST /user/login` 接口
2. 点击 **Try it out**
3. 输入登录信息：
```json
{
  "userAccount": "zhangsan",
  "userPassword": "123456"
}
```
4. 点击 **Execute**
5. 成功响应示例：
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "userId": 1,
      "userName": "张三",
      "userAccount": "zhangsan"
    }
  }
}
```
6. **重要**：复制返回的 `token`，后续需要认证的接口会用到

---

### 3. 获取用户信息（需要认证）

**接口**：`GET /user/info`

**步骤**：
1. 找到 `GET /user/info` 接口
2. 点击 **Try it out**
3. 在 **Authorization** 输入框中填入 Token：
```
Bearer eyJhbGciOiJIUzI1NiJ9...
```
   > 注意：需要在 token 前加 `Bearer ` 前缀（有空格）
4. 点击 **Execute**

---

### 4. 查看阶段列表

**接口**：`GET /api/stages`

**步骤**：
1. 找到 **API接口** 分组下的 `GET /api/stages`
2. 点击 **Try it out** → **Execute**
3. 返回所有阶段列表

---

### 5. 查看当前阶段任务

**接口**：`GET /api/current-stage`

**功能**：获取用户当前正在进行的阶段及其任务列表

**步骤**：
1. 找到 `GET /api/current-stage` 接口
2. 点击 **Try it out**
3. 可选参数 `userId`（默认为1）
4. 点击 **Execute**
5. 响应示例：
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "stageId": 1,
    "stageName": "选题阶段",
    "stageIndex": 0,
    "totalStages": 5,
    "tasks": [
      {
        "taskId": 1,
        "taskTitle": "确定论文题目",
        "taskDesc": "与导师沟通确定研究方向",
        "completed": 0
      }
    ],
    "totalTasks": 3,
    "completedTasks": 0
  }
}
```

---

### 6. 查看阶段详情

**接口**：`GET /api/stage/detail`

**步骤**：
1. 找到 `GET /api/stage/detail` 接口
2. 点击 **Try it out**
3. 输入参数：
   - `stageId`：阶段ID（必填），如 `1`
   - `userId`：用户ID（可选，默认1）
4. 点击 **Execute**

---

### 7. 更新任务完成状态

**接口**：`POST /api/task/updateStatus`

**步骤**：
1. 找到 `POST /api/task/updateStatus` 接口
2. 点击 **Try it out**
3. 输入参数：
   - `taskId`：任务ID
   - `completed`：完成状态（0-未完成，1-已完成）
   - `userId`：用户ID（可选）
4. 点击 **Execute**

---

### 8. 上传文件

**接口**：`POST /api/file/upload`

**步骤**：
1. 找到 `POST /api/file/upload` 接口
2. 点击 **Try it out**
3. 参数说明：
   - `file`：选择要上传的文件（点击 **Choose File** 按钮）
   - `stageId`：阶段ID
4. 点击 **Execute**
5. 成功响应示例：
```json
{
  "code": 200,
  "message": "上传成功",
  "data": {
    "attachmentId": 1,
    "attachmentName": "文档.docx",
    "attachmentSize": "25.5KB",
    "downloadUrl": "/api/file/download/1"
  }
}
```

**说明**：
- 上传成功后返回 `attachmentId`（附件ID）和 `downloadUrl`（下载地址）
- 原始文件名保存在数据库中，下载时自动使用原始文件名
- 文件存储在项目根目录下的 `upload_files` 文件夹

---

### 9. 下载文件

**接口**：`GET /api/file/download/{attachmentId}`

**步骤**：
1. 使用上传时返回的 `attachmentId`
2. 访问下载地址：`http://localhost:8888/api/file/download/1`
3. 文件会自动下载，使用原始文件名

**示例**：
```
GET http://localhost:8888/api/file/download/1
```

---

### 10. 删除文件

**接口**：`DELETE /api/file/{attachmentId}`

**步骤**：
1. 找到 `DELETE /api/file/{attachmentId}` 接口
2. 点击 **Try it out**
3. 输入路径参数 `attachmentId`：附件ID
4. 点击 **Execute**

---

## 数据库表结构说明

### 用户表 (user)
| 字段 | 说明 |
|------|------|
| user_id | 用户ID |
| user_name | 用户名称 |
| user_account | 用户账号 |
| user_password | 用户密码 |

### 阶段表 (stage)
| 字段 | 说明 |
|------|------|
| stage_id | 阶段ID |
| stage_name | 阶段名称 |
| stage_starttime | 开始时间 |
| stage_endtime | 结束时间 |

### 任务表 (task)
| 字段 | 说明 |
|------|------|
| task_id | 任务ID |
| stage_id | 所属阶段ID |
| task_title | 任务标题 |
| task_desc | 任务描述 |

### 用户阶段表 (user_stage)
| 字段 | 说明 |
|------|------|
| user_id | 用户ID |
| stage_id | 阶段ID |
| score | 分数 |
| file_path | 文件路径 |
| arrange_message | 评语 |

### 用户任务表 (user_task)
| 字段 | 说明 |
|------|------|
| task_id | 任务ID |
| user_id | 用户ID |
| completed | 完成状态(0/1) |

### 附件表 (attachment)
| 字段 | 说明 |
|------|------|
| attachment_id | 附件ID |
| attachment_name | 文件名 |
| attachment_size | 文件大小 |
| attachment_type | 类型(file/link/ai_tool) |
| attachment_url | 访问URL |
| stage_id | 所属阶段ID |

---

## 配置说明

### application.properties 关键配置

```properties
# 服务器端口
server.port=8888

# 文件上传配置
upload.filePath=upload_files
upload.handler=/file/**

# JWT配置
jwt.secret=your-secret-key
jwt.expiration=86400000

# Redis配置（可选）
spring.data.redis.host=localhost
spring.data.redis.port=6379
```

---

## 常见问题

### Q: Swagger UI 无法访问？
A: 确保项目已正确启动，检查端口是否被占用。

### Q: 文件上传后无法访问？
A: 检查 `upload.filePath` 配置是否正确，确保目录有读写权限。

### Q: 登录后其他接口返回401？
A: 确保请求头中携带正确的 `Authorization: Bearer <token>`。

---

## 技术栈

- Spring Boot 3.5.x
- MyBatis-Plus 3.5.x
- MySQL 8.x
- Redis
- JWT (jjwt)
- SpringDoc OpenAPI (Swagger)
- Lombok