中小学学习搭子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

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

请求参数:

{
  "username": "xiaoming",
  "password": "123456",
  "grade": "初三"
}

参数说明:

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

成功响应:

{
  "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"
}

错误响应:

{
  "code": 400,
  "message": "用户名已存在",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}

2. 学习搭子登录

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

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

请求参数:

{
  "username": "xiaoming",
  "password": "123456"
}

参数说明:

username (必填): 用户名
password (必填): 密码

成功响应:

{
  "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"
}

错误响应:

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

通用说明

响应格式

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

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

状态码说明

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

测试数据

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

管理员账户
- 用户名: admin
- 密码: 123456
- 年级: 高三
- 头像: https://example.com/avatar/admin.jpg
测试用户1
- 用户名: xiaoming
- 密码: 123456
- 年级: 初三
- 头像: https://example.com/avatar/xiaoming.jpg
测试用户2
- 用户名: xiaohong
- 密码: 123456
- 年级: 高二
- 头像: https://example.com/avatar/xiaohong.jpg
测试用户3
- 用户名: xiaogang
- 密码: 123456
- 年级: 初二
- 头像: https://example.com/avatar/xiaogang.jpg

3. 获取用户信息

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

功能描述: 根据用户ID获取用户的头像、用户名和昵称等基本信息

请求参数:

id (路径参数，必填): 用户ID

成功响应:

{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "userId": 1,
    "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
    "username": "xiaoming",
    "grade": "初三",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": 1704067200000
}

错误响应:

{
  "code": 404,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1704067200000
}

4. 获取用户列表

接口地址: GET /api/users

功能描述: 获取所有用户的基本信息列表

成功响应:

{
  "code": 200,
  "message": "获取用户列表成功",
  "data": [
    {
      "userId": 1,
      "avatarUrl": "https://example.com/avatar/admin.jpg",
      "username": "admin",
      "grade": "高三",
      "createTime": "2024-01-01T10:00:00",
      "updateTime": "2024-01-01T10:00:00"
    },
    {
      "userId": 2,
      "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
      "username": "xiaoming",
      "grade": "初三",
      "createTime": "2024-01-01T10:00:00",
      "updateTime": "2024-01-01T10:00:00"
    }
  ],
  "timestamp": 1704067200000
}

使用示例（curl命令）

中小学学习搭子注册

curl -X POST http://localhost:8080/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "123456",
    "grade": "初一"
  }'

中小学学习搭子登录

curl -X POST http://localhost:8080/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "xiaoming",
    "password": "123456"
  }'

获取用户信息

curl -X GET http://localhost:8080/api/users/1

获取用户列表

curl -X GET http://localhost:8080/api/users

更新用户信息（仅更新文本信息）

curl -X PUT http://localhost:8080/api/users/1 \
  -F "username=newusername" \
  -F "grade=高一"

更新用户信息（包含头像上传）

curl -X PUT http://localhost:8080/api/users/1 \
  -F "username=newusername" \
  -F "grade=高一" \
  -F "avatar=@/path/to/avatar.jpg"

5. 更新用户信息（支持头像上传）

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

功能描述: 更新用户的昵称、年级和头像等信息，支持头像文件上传

请求参数:

id (路径参数，必填): 用户ID

请求格式: multipart/form-data

请求参数:

username (可选): 新的用户名，2-50个字符
grade (可选): 新的年级，最多20个字符
avatar (可选): 头像文件，支持jpg、jpeg、png格式，最大5MB

参数说明:

如果提供了avatar文件，系统会自动保存文件并更新用户的头像URL
头像文件会保存到服务器的uploads/avatars/目录
头像URL格式为：http://localhost:8080/uploads/avatars/{filename}
支持的图片格式：jpg、jpeg、png
文件大小限制：最大5MB

成功响应:

{
  "code": 200,
  "message": "用户信息更新成功",
  "data": {
    "userId": 1,
    "avatarUrl": "https://example.com/avatar/new.jpg",
    "username": "newusername",
    "grade": "高一",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T12:00:00"
  },
  "timestamp": 1704074400000
}

错误响应:

{
  "code": 404,
  "message": "用户不存在",
  "data": null,
  "timestamp": 1704074400000
}

{
  "code": 400,
  "message": "用户名已存在",
  "data": null,
  "timestamp": 1704074400000
}

6. 学习目标管理

6.1 创建学习目标

接口地址: POST /api/goals

功能描述: 创建新的学习目标

请求格式: application/json

请求参数:

{
  "userId": 1,
  "subject": "数学",
  "goalType": "DAILY",
  "content": "完成代数练习题",
  "difficulty": "MEDIUM",
  "quantity": 10,
  "estimatedTime": 60,
  "startTime": "2025-01-29T10:00:00"
}

参数说明:

userId (必填): 用户ID
subject (必填): 学科名称，如"数学"、"语文"、"英语"等
goalType (必填): 目标类型，可选值：DAILY（每日）、WEEKLY（每周）、MONTHLY（每月）
content (必填): 目标内容描述
difficulty (必填): 难度等级，可选值：EASY（简单）、MEDIUM（中等）、HARD（困难）
quantity (必填): 目标数量
estimatedTime (必填): 预估完成时间（分钟）
startTime (可选): 开始时间，格式：yyyy-MM-ddTHH:mm:ss

成功响应:

{
  "code": 200,
  "message": "目标创建成功",
  "data": {
    "goalId": 1,
    "userId": 1,
    "subject": "数学",
    "goalType": "DAILY",
    "content": "完成代数练习题",
    "difficulty": "MEDIUM",
    "quantity": 10,
    "estimatedTime": 60,
    "status": "PENDING",
    "createTime": "2025-01-29T10:00:00",
    "startTime": null,
    "endTime": null
  }
}

示例请求:

curl -X POST http://192.168.124.7:8080/api/goals \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "subject": "数学",
    "goalType": "DAILY",
    "content": "完成代数练习题",
    "difficulty": "MEDIUM",
    "quantity": 10,
    "estimatedTime": 60
  }'

6.2 开始执行目标

接口地址: POST /api/goals/{id}/start

功能描述: 开始执行指定的学习目标

请求参数:

id (路径参数，必填): 目标ID

成功响应:

{
  "code": 200,
  "message": "目标已开始执行",
  "data": {
    "goalId": 1,
    "userId": 1,
    "subject": "数学",
    "goalType": "DAILY",
    "content": "完成代数练习题",
    "difficulty": "MEDIUM",
    "quantity": 10,
    "estimatedTime": 60,
    "status": "IN_PROGRESS",
    "createTime": "2025-01-29T10:00:00",
    "startTime": "2025-01-29T10:30:00",
    "endTime": null
  }
}

示例请求:

curl -X POST http://localhost:8080/api/goals/1/start

6.3 获取用户目标列表

接口地址: GET /api/goals/user/{userId}

功能描述: 获取指定用户的所有学习目标

请求参数:

userId (路径参数，必填): 用户ID
status (查询参数，可选): 目标状态筛选，可选值：PENDING、IN_PROGRESS、COMPLETED、CANCELLED
subject (查询参数，可选): 学科筛选
goalType (查询参数，可选): 目标类型筛选

成功响应:

{
  "code": 200,
  "message": "获取用户目标列表成功",
  "data": [
    {
      "goalId": 1,
      "userId": 1,
      "subject": "数学",
      "goalType": "DAILY",
      "content": "完成代数练习题",
      "difficulty": "MEDIUM",
      "quantity": 10,
      "estimatedTime": 60,
      "status": "IN_PROGRESS",
      "createTime": "2025-01-29T10:00:00",
      "startTime": "2025-01-29T10:30:00",
      "endTime": null
    }
  ]
}

示例请求:

# 获取所有目标
curl -X GET http://localhost:8080/api/goals/user/1

# 获取进行中的目标
curl -X GET "http://localhost:8080/api/goals/user/1?status=IN_PROGRESS"

# 获取数学学科的目标
curl -X GET "http://localhost:8080/api/goals/user/1?subject=数学"

6.4 获取今日目标

接口地址: GET /api/goals/user/{userId}/today

功能描述: 获取用户今日的学习目标

请求参数:

userId (路径参数，必填): 用户ID

成功响应:

{
  "code": 200,
  "message": "获取今日目标成功",
  "data": [
    {
      "goalId": 1,
      "userId": 1,
      "subject": "数学",
      "goalType": "DAILY",
      "content": "完成代数练习题",
      "difficulty": "MEDIUM",
      "quantity": 10,
      "estimatedTime": 60,
      "status": "IN_PROGRESS",
      "createTime": "2025-01-29T10:00:00",
      "startTime": "2025-01-29T10:30:00",
      "endTime": null
    }
  ]
}

示例请求:

curl -X GET http://localhost:8080/api/goals/user/1/today

6.5 获取本周目标

接口地址: GET /api/goals/user/{userId}/week

功能描述: 获取用户本周的学习目标

请求参数:

userId (路径参数，必填): 用户ID

成功响应:

{
  "code": 200,
  "message": "获取本周目标成功",
  "data": [
    {
      "goalId": 1,
      "userId": 1,
      "subject": "数学",
      "goalType": "WEEKLY",
      "content": "完成本周数学作业",
      "difficulty": "MEDIUM",
      "quantity": 5,
      "estimatedTime": 300,
      "status": "IN_PROGRESS",
      "createTime": "2025-01-27T09:00:00",
      "startTime": "2025-01-27T09:30:00",
      "endTime": null
    }
  ]
}

示例请求:

curl -X GET http://localhost:8080/api/goals/user/1/week

6.6 获取目标统计

接口地址: GET /api/goals/user/{userId}/stats

功能描述: 获取用户的学习目标统计信息

请求参数:

userId (路径参数，必填): 用户ID

成功响应:

{
  "code": 200,
  "message": "获取目标统计成功",
  "data": {
    "totalGoals": 10,
    "completedGoals": 7,
    "inProgressGoals": 2,
    "pendingGoals": 1,
    "completionRate": 70.0
  }
}

示例请求:

curl -X GET http://localhost:8080/api/goals/user/1/stats

7. 按日期范围获取目标

接口: GET /api/goals/user/{userId}/daterange

描述: 根据日期范围获取用户的学习目标，支持按天查看目标功能

请求参数:

userId (路径参数，必填): 用户ID
startDate (查询参数，必填): 开始日期，格式：yyyy-MM-dd
endDate (查询参数，必填): 结束日期，格式：yyyy-MM-dd

成功响应:

{
  "code": 200,
  "message": "获取目标成功",
  "data": [
    {
      "goalId": 1,
      "goalContent": "完成数学作业",
      "subject": "数学",
      "deadline": "2024-01-15T18:00:00",
      "status": "IN_PROGRESS",
      "progress": 60,
      "createdAt": "2024-01-15T08:00:00",
      "updatedAt": "2024-01-15T10:30:00"
    }
  ]
}

示例请求:

# 获取某一天的目标
curl -X GET "http://localhost:8080/api/goals/user/1/daterange?startDate=2024-01-15&endDate=2024-01-15"

# 获取一周的目标
curl -X GET "http://localhost:8080/api/goals/user/1/daterange?startDate=2024-01-15&endDate=2024-01-21"

AI出题接口

1. AI生成题目

接口: POST /api/ai/generate-questions

描述: 根据目标信息生成相应的题目（当前使用模拟数据生成）

请求参数:

{
  "goalId": 1,
  "subject": "数学",
  "contentType": 1,
  "difficulty": "简单",
  "questionCount": 5,
  "knowledgePoint": "加减法",
  "goalContent": "练习基础数学运算"
}

参数说明:

goalId (必填): 目标ID
subject (必填): 学科名称
contentType (必填): 题目类型，1-选择题，2-填空题，3-单词
difficulty (必填): 难度等级
questionCount (必填): 生成题目数量，必须大于0
knowledgePoint (可选): 知识点
goalContent (可选): 目标内容描述

响应示例:

{
  "code": 200,
  "message": "题目生成成功",
  "data": [
    {
      "detailId": 1,
      "content": "计算：3 + 5 = ?",
      "options": ["A. 6", "B. 7", "C. 8", "D. 9"],
      "answer": "C. 8",
      "difficulty": "简单",
      "knowledgePoint": "加减法",
      "contentType": 1
    }
  ]
}

2. 获取目标题目

接口: GET /api/ai/questions/{goalId}

描述: 获取指定目标的所有题目

路径参数:

goalId: 目标ID

响应示例:

{
  "code": 200,
  "message": "获取题目成功",
  "data": [
    {
      "detailId": 1,
      "content": "计算：3 + 5 = ?",
      "options": ["A. 6", "B. 7", "C. 8", "D. 9"],
      "answer": "C. 8",
      "difficulty": "简单",
      "knowledgePoint": "加减法",
      "contentType": 1
    }
  ]
}

3. 自动生成题目

接口: POST /api/ai/auto-generate

描述: 保存目标后自动生成题目（内部调用）

请求参数:

{
  "goalId": 1,
  "subject": "数学",
  "goalType": "选择",
  "totalQuantity": 10,
  "difficulty": "简单"
}

示例请求:

# 生成题目
curl -X POST "http://localhost:8080/api/ai/generate-questions" \
  -H "Content-Type: application/json" \
  -d '{
    "goalId": 1,
    "subject": "数学",
    "contentType": 1,
    "difficulty": "简单",
    "questionCount": 5,
    "knowledgePoint": "加减法"
  }'

# 获取题目
curl -X GET "http://localhost:8080/api/ai/questions/1"

注意事项

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

AI对话接口

1. 发送消息

接口: POST /api/ai/chat

描述: 发送消息给AI并获取回复

请求参数:

{
  "userId": 1,
  "content": "你好，我想学习数学"
}

响应示例:

{
  "code": 200,
  "message": "消息发送成功",
  "data": {
    "chatId": 1,
    "userId": 1,
    "content": "你好！我很乐意帮助你学习数学。你想从哪个方面开始呢？",
    "type": 1,
    "timestamp": "2025-01-30T10:30:00"
  }
}

2. 获取聊天记录

接口: GET /api/ai/chat/history/{userId}

描述: 获取用户的完整聊天历史记录

响应示例:

{
  "code": 200,
  "message": "获取聊天记录成功",
  "data": [
    {
      "chatId": 2,
      "userId": 1,
      "content": "你好！我很乐意帮助你学习数学。你想从哪个方面开始呢？",
      "type": 1,
      "timestamp": "2025-01-30T10:30:00"
    },
    {
      "chatId": 1,
      "userId": 1,
      "content": "你好，我想学习数学",
      "type": 0,
      "timestamp": "2025-01-30T10:29:30"
    }
  ]
}

3. 获取最近聊天记录

接口: GET /api/ai/chat/recent/{userId}?limit=20

描述: 获取用户最近的聊天记录（默认20条）

4. 清空聊天记录

接口: DELETE /api/ai/chat/history/{userId}

描述: 清空用户的所有聊天记录

响应示例:

{
  "code": 200,
  "message": "清空聊天记录成功",
  "data": null
}

消息类型说明

type: 0 - 用户消息
type: 1 - AI回复

使用示例

发送消息

curl -X POST http://localhost:8080/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "content": "请帮我解释一下二次函数"
  }'

获取聊天记录

curl -X GET http://localhost:8080/api/ai/chat/history/1

学习报告接口

1. 获取用户学习报告列表

接口: GET /api/reports/user/{userId}

描述: 获取指定用户的所有学习报告

路径参数:

userId: 用户ID

响应示例:

{
  "code": 200,
  "message": "获取学习报告成功",
  "data": [
    {
      "reportId": 1,
      "goalId": 1,
      "userId": 1,
      "generateTime": "2025-01-30T15:30:00",
      "accuracy": 85.5,
      "goalContent": "完成数学练习题",
      "subject": "数学",
      "shareUrl": "http://localhost:8080/api/reports/1/share"
    }
  ]
}

2. 获取学习报告详情

接口: GET /api/reports/{reportId}

描述: 获取指定学习报告的详细信息

路径参数:

reportId: 报告ID

响应示例:

{
  "code": 200,
  "message": "获取报告详情成功",
  "data": {
    "reportId": 1,
    "goalId": 1,
    "userId": 1,
    "generateTime": "2025-01-30T15:30:00",
    "accuracy": 85.5,
    "knowledgeAnalysis": {
      "基础运算": 8,
      "代数方程": 5,
      "几何图形": 7
    },
    "difficultyAnalysis": {
      "简单": 12,
      "中等": 6,
      "困难": 2
    },
    "recentAnswers": [
      {
        "answerId": 1,
        "contentId": 1,
        "userAnswer": "C",
        "isCorrect": 1,
        "spendTime": 30,
        "answerTime": "2025-01-30T15:25:00"
      }
    ],
    "shareUrl": "http://localhost:8080/api/reports/1/share"
  }
}

3. 生成学习报告

接口: POST /api/reports/generate

描述: 为指定目标生成学习报告

请求参数:

{
  "goalId": 1,
  "userId": 1
}

响应示例:

{
  "code": 200,
  "message": "学习报告生成成功",
  "data": {
    "reportId": 1,
    "goalId": 1,
    "userId": 1,
    "generateTime": "2025-01-30T15:30:00",
    "accuracy": 85.5,
    "shareUrl": "http://localhost:8080/api/reports/1/share"
  }
}

4. 分享学习报告

接口: GET /api/reports/{reportId}/share

描述: 获取学习报告的分享页面

路径参数:

reportId: 报告ID

响应: 返回HTML页面，展示学习报告的分享内容

使用示例

获取用户报告列表

curl -X GET http://localhost:8080/api/reports/user/1

获取报告详情

curl -X GET http://localhost:8080/api/reports/1

生成学习报告

curl -X POST http://localhost:8080/api/reports/generate \
  -H "Content-Type: application/json" \
  -d '{
    "goalId": 1,
    "userId": 1
  }'

答题记录接口

1. 提交答案

接口: POST /api/answers/submit

描述: 提交用户答案并记录答题情况

请求参数:

{
  "userId": 1,
  "goalId": 1,
  "contentId": 1,
  "userAnswer": "C",
  "spendTime": 30
}

参数说明:

userId: 用户ID
goalId: 目标ID
contentId: 题目ID
userAnswer: 用户提交的答案
spendTime: 答题用时（秒）

响应示例:

{
  "code": 200,
  "message": "答案提交成功",
  "data": {
    "answerId": 1,
    "isCorrect": true,
    "correctAnswer": "C",
    "explanation": "正确答案是C，因为3+5=8"
  }
}

2. 获取答题记录

接口: GET /api/answers/goal/{goalId}

描述: 获取指定目标的所有答题记录

路径参数:

goalId: 目标ID

响应示例:

{
  "code": 200,
  "message": "获取答题记录成功",
  "data": [
    {
      "answerId": 1,
      "userId": 1,
      "goalId": 1,
      "contentId": 1,
      "userAnswer": "C",
      "isCorrect": 1,
      "spendTime": 30,
      "answerTime": "2025-01-30T15:25:00"
    }
  ]
}

更新日志

2025-01-30

删除了通义千问AI出题功能
AI出题接口现在使用模拟数据生成题目
保持API接口格式不变，确保系统功能正常
新增AI对话功能
- 集成DeepSeek大模型（deepseek-reasoner）
- 支持实时AI对话交互
- 提供聊天记录保存和查看功能
- 新增ai_chat数据表存储对话记录
新增学习报告功能
- 学习报告生成和管理接口
- 学习报告详情查看功能
- 知识点分析和难度分析
- 学习报告分享功能
新增答题记录功能
- 答案提交和校验接口
- 答题记录查询和统计
- 学习进度跟踪功能

联系方式

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

API接口使用说明.md 23 KB Permalink Cronologia Originale

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

项目概述

🔄 数据持久化说明

接口列表

1. 学习搭子注册

2. 学习搭子登录

通用说明

响应格式

状态码说明

测试数据

3. 获取用户信息

4. 获取用户列表

使用示例（curl命令）

中小学学习搭子注册

中小学学习搭子登录

获取用户信息

获取用户列表

更新用户信息（仅更新文本信息）

更新用户信息（包含头像上传）

5. 更新用户信息（支持头像上传）

6. 学习目标管理

6.1 创建学习目标

6.2 开始执行目标

6.3 获取用户目标列表

6.4 获取今日目标

6.5 获取本周目标

6.6 获取目标统计

7. 按日期范围获取目标

AI出题接口

1. AI生成题目

2. 获取目标题目

3. 自动生成题目

注意事项

AI对话接口

1. 发送消息

2. 获取聊天记录

3. 获取最近聊天记录

4. 清空聊天记录

消息类型说明

使用示例

发送消息

获取聊天记录

学习报告接口

1. 获取用户学习报告列表

2. 获取学习报告详情

3. 生成学习报告

4. 分享学习报告

使用示例

获取用户报告列表

获取报告详情

生成学习报告

答题记录接口

1. 提交答案

2. 获取答题记录

更新日志

2025-01-30

联系方式

API接口使用说明.md 23 KB

Permalink Cronologia Originale