# 中小学学习搭子APP - API接口使用说明文档

## 项目概述

本项目是一个基于Spring Boot + JPA的中小学学习搭子APP后端API，为中小学生提供寻找学习伙伴的平台功能。

**服务地址**: http://localhost:8080/api

**API文档**: http://localhost:8080/api/docs

## 🔄 数据持久化说明

**数据存储方式**: H2文件数据库（持久化存储）
- ✅ **数据持久化**: 所有用户数据会永久保存到磁盘文件中
- ✅ **应用重启**: 重启后数据不会丢失，用户信息依然存在
- 📁 **数据文件位置**: `./data/testdb.mv.db`
- 🔍 **数据库控制台**: http://localhost:8080/api/h2-console
  - JDBC URL: `jdbc:h2:file:./data/testdb`
  - 用户名: `sa`
  - 密码: (空)

---

## 接口列表

### 1. 学习搭子注册

**接口地址**: `POST /api/users/register`

**功能描述**: 创建新的学习搭子用户账户

**请求参数**:
```json
{
  "username": "xiaoming",
  "password": "123456",
  "grade": "初三"
}
```

**参数说明**:
- `username` (必填): 用户名，3-50个字符
- `password` (必填): 密码，6个字符以上
- `grade` (可选): 年级（如：小一、小二、小三、小四、小五、小六、初一、初二、初三、高一、高二、高三等）

**成功响应**:
```json
{
  "code": 200,
  "message": "注册成功",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "初三",
    "avatarUrl": null,
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": "2024-01-01T10:00:00"
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "用户名已存在",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}
```

---

### 2. 学习搭子登录

**接口地址**: `POST /api/users/login`

**功能描述**: 验证学习搭子用户凭据并返回用户信息

**请求参数**:
```json
{
  "username": "xiaoming",
  "password": "123456"
}
```

**参数说明**:
- `username` (必填): 用户名
- `password` (必填): 密码

**成功响应**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "初三",
    "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": "2024-01-01T10:00:00"
}
```

**错误响应**:
```json
{
  "code": 401,
  "message": "用户名或密码错误",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}
```

---

### 3. 获取学习搭子信息

**接口地址**: `GET /api/users/{id}`

**功能描述**: 根据用户ID获取学习搭子详细信息

**请求参数**:
- `id` (路径参数): 用户ID

**请求示例**: `GET /api/users/1`

**成功响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "初三",
    "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": "2024-01-01T10:00:00"
}
```

**错误响应**:
```json
{
  "code": 404,
  "message": "用户不存在",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}
```

---

### 4. 获取所有学习搭子

**接口地址**: `GET /api/users`

**功能描述**: 获取系统中所有学习搭子的列表

**请求参数**: 无

**成功响应**:
```json
{
  "code": 200,
  "message": "获取中小学学习搭子列表成功",
  "data": [
    {
      "userId": 1,
      "username": "admin",
      "grade": "高三",
      "avatarUrl": "https://example.com/avatar/admin.jpg",
      "createTime": "2024-01-01T10:00:00",
      "updateTime": "2024-01-01T10:00:00"
    },
    {
      "userId": 2,
      "username": "xiaoming",
      "grade": "初三",
      "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
      "createTime": "2024-01-01T10:00:00",
      "updateTime": "2024-01-01T10:00:00"
    }
  ],
  "timestamp": "2024-01-01T10:00:00"
}
```

---

### 5. 更新学习搭子信息

**接口地址**: `PUT /api/users/{id}`

**功能描述**: 更新指定学习搭子的信息

**请求参数**:
- `id` (路径参数): 用户ID
- 请求体:
```json
{
  "grade": "高一",
  "avatarUrl": "https://example.com/avatar/new.jpg"
}
```

**参数说明**:
- `grade` (可选): 年级
- `avatarUrl` (可选): 头像URL

**成功响应**:
```json
{
  "code": 200,
  "message": "中小学学习搭子信息更新成功",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "高一",
    "avatarUrl": "https://example.com/avatar/new.jpg",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T11:00:00"
  },
  "timestamp": "2024-01-01T11:00:00"
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "参数格式不正确",
  "data": null,
  "timestamp": "2024-01-01T11:00:00"
}
```

---

### 6. 删除学习搭子

**接口地址**: `DELETE /api/users/{id}`

**功能描述**: 删除指定学习搭子

**请求参数**:
- `id` (路径参数): 用户ID

**请求示例**: `DELETE /api/users/1`

**成功响应**:
```json
{
  "code": 200,
  "message": "中小学学习搭子删除成功",
  "data": null,
  "timestamp": "2024-01-01T12:00:00"
}
```

**错误响应**:
```json
{
  "code": 404,
  "message": "中小学学习搭子不存在",
  "data": null,
  "timestamp": "2024-01-01T12:00:00"
}
```

---

### 7. 修改密码

**接口地址**: `POST /api/users/{id}/change-password`

**功能描述**: 修改中小学学习搭子密码

**请求参数**:
- `id` (路径参数): 用户ID
- 请求体:
```json
{
  "oldPassword": "123456",
  "newPassword": "newpassword123"
}
```

**参数说明**:
- `oldPassword` (必填): 原密码
- `newPassword` (必填): 新密码，6个字符以上

**成功响应**:
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": null,
  "timestamp": "2024-01-01T13:00:00"
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "原密码错误",
  "data": null,
  "timestamp": "2024-01-01T13:00:00"
}
```

---

## 通用说明

### 响应格式

所有接口都使用统一的响应格式：

```json
{
  "code": 200,
  "message": "操作结果描述",
  "data": "具体数据或null",
  "timestamp": "响应时间戳"
}
```

### 状态码说明

- `200`: 操作成功
- `400`: 请求参数错误
- `401`: 未授权（用户名或密码错误）
- `404`: 资源不存在
- `500`: 服务器内部错误

### 测试数据

系统启动时会自动创建以下测试中小学学习搭子：

1. **管理员账户**
   - 用户名: `admin`
   - 密码: `123456`
   - 年级: `高三`
   - 头像: `https://example.com/avatar/admin.jpg`

2. **测试用户1**
   - 用户名: `xiaoming`
   - 密码: `123456`
   - 年级: `初三`
   - 头像: `https://example.com/avatar/xiaoming.jpg`

3. **测试用户2**
   - 用户名: `xiaohong`
   - 密码: `123456`
   - 年级: `高二`
   - 头像: `https://example.com/avatar/xiaohong.jpg`

4. **测试用户3**
   - 用户名: `xiaogang`
   - 密码: `123456`
   - 年级: `初二`
   - 头像: `https://example.com/avatar/xiaogang.jpg`

### 使用示例（curl命令）

#### 中小学学习搭子注册
```bash
curl -X POST http://localhost:8080/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "123456",
    "grade": "初一",
    "avatarUrl": "https://example.com/avatar/newuser.jpg"
  }'
```

#### 中小学学习搭子登录
```bash
curl -X POST http://localhost:8080/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "xiaoming",
    "password": "123456"
  }'
```

#### 获取中小学学习搭子信息
```bash
curl -X GET http://localhost:8080/api/users/1
```

#### 获取所有中小学学习搭子
```bash
curl -X GET http://localhost:8080/api/users
```

---

## 注意事项

1. **跨域支持**: 所有接口都支持跨域访问，方便前端调用
2. **参数验证**: 所有接口都有完整的参数验证
3. **错误处理**: 统一的错误处理和响应格式
4. **日志记录**: 所有操作都有详细的日志记录
5. **数据库**: 默认使用H2文件数据库，数据持久化存储
6. **密码安全**: 生产环境建议使用BCrypt加密（当前为演示用简单加密）
7. **中小学学习搭子匹配**: 可根据年级等信息进行学习伙伴匹配
8. **个人资料**: 支持头像展示，适合中小学生使用

---

## 联系方式

如有问题，请联系开发团队：dev@example.com