450 lines
12 KiB
Markdown
450 lines
12 KiB
Markdown
# 📋 家长端成长记录功能 - API接口对照表
|
||
|
||
## 🎯 接口概览
|
||
|
||
| 序号 | 接口名称 | 请求方式 | 接口路径 | 状态 |
|
||
|------|---------|---------|---------|------|
|
||
| 1 | 获取成长记录列表 | GET | `/api/growth-record/parent/list` | ✅ 已实现 |
|
||
| 2 | 获取成长记录详情 | GET | `/api/growth-record/parent/{id}` | ✅ 已实现 |
|
||
| 3 | 标记为已读 | POST | `/api/growth-record/parent/{id}/read` | ✅ 已实现 |
|
||
| 4 | 获取周反馈列表 | GET | `/api/growth-record/parent/weekly/list` | ✅ 已实现 |
|
||
| 5 | 获取月反馈列表 | GET | `/api/growth-record/parent/monthly/list` | ✅ 已实现 |
|
||
|
||
---
|
||
|
||
## 📝 接口详细说明
|
||
|
||
### 1. 获取成长记录列表
|
||
|
||
**接口地址：** `GET /api/growth-record/parent/list`
|
||
|
||
**功能说明：** 家长端获取学生的成长记录列表，支持按类型筛选和分页
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| studentId | Long | 是 | 学生ID | 1 |
|
||
| recordType | String | 否 | 记录类型：daily/weekly/monthly | daily |
|
||
| startDate | String | 否 | 开始日期 | 2026-01-01 |
|
||
| endDate | String | 否 | 结束日期 | 2026-01-31 |
|
||
| page | Integer | 否 | 页码，默认1 | 1 |
|
||
| size | Integer | 否 | 每页数量，默认10 | 10 |
|
||
|
||
**请求示例：**
|
||
```bash
|
||
GET /api/growth-record/parent/list?studentId=1&recordType=daily&page=1&size=10
|
||
```
|
||
|
||
**响应参数：**
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码：200成功 |
|
||
| message | String | 提示信息 |
|
||
| data | Object | 分页数据 |
|
||
| data.records | Array | 记录列表 |
|
||
| data.total | Long | 总记录数 |
|
||
| data.size | Long | 每页数量 |
|
||
| data.current | Long | 当前页码 |
|
||
| data.pages | Long | 总页数 |
|
||
|
||
**记录对象（Record）：**
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | Long | 记录ID |
|
||
| orderId | Long | 订单ID |
|
||
| studentId | Long | 学生ID |
|
||
| studentName | String | 学生姓名 |
|
||
| teacherId | Long | 陪伴员ID |
|
||
| teacherName | String | 陪伴员姓名 |
|
||
| recordDate | String | 记录日期 |
|
||
| recordType | String | 记录类型：daily/weekly/monthly |
|
||
| recordTypeName | String | 记录类型名称 |
|
||
| content | String | 反馈内容 |
|
||
| imageList | Array | 图片列表 |
|
||
| videoList | Array | 视频列表 |
|
||
| duration | Integer | 服务时长（分钟） |
|
||
| durationText | String | 服务时长文本 |
|
||
| status | Integer | 状态：1已提交，0草稿 |
|
||
| statusName | String | 状态名称 |
|
||
| createTime | String | 创建时间 |
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"orderId": 101,
|
||
"studentId": 1,
|
||
"studentName": "小明",
|
||
"teacherId": 1,
|
||
"teacherName": "张老师",
|
||
"recordDate": "2026-01-23",
|
||
"recordType": "daily",
|
||
"recordTypeName": "每日反馈",
|
||
"content": "今天学习状态很好，完成了所有作业。数学题目理解能力有所提升。",
|
||
"imageList": [
|
||
"https://example.com/image1.jpg",
|
||
"https://example.com/image2.jpg"
|
||
],
|
||
"videoList": [
|
||
"https://example.com/video1.mp4"
|
||
],
|
||
"duration": 120,
|
||
"durationText": "120分钟",
|
||
"status": 1,
|
||
"statusName": "已提交",
|
||
"createTime": "2026-01-23 18:00:00"
|
||
}
|
||
],
|
||
"total": 10,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取成长记录详情
|
||
|
||
**接口地址：** `GET /api/growth-record/parent/{id}`
|
||
|
||
**功能说明：** 家长端获取成长记录的详细信息
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| id | Long | 是 | 记录ID（路径参数） | 1 |
|
||
|
||
**请求示例：**
|
||
```bash
|
||
GET /api/growth-record/parent/1
|
||
```
|
||
|
||
**响应参数：**
|
||
|
||
与"获取成长记录列表"中的记录对象相同
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"orderId": 101,
|
||
"studentId": 1,
|
||
"studentName": "小明",
|
||
"teacherId": 1,
|
||
"teacherName": "张老师",
|
||
"recordDate": "2026-01-23",
|
||
"recordType": "daily",
|
||
"recordTypeName": "每日反馈",
|
||
"content": "今天学习状态很好，完成了所有作业。数学题目理解能力有所提升。在学习过程中表现出很强的专注力，能够独立完成大部分题目。",
|
||
"imageList": [
|
||
"https://example.com/image1.jpg",
|
||
"https://example.com/image2.jpg",
|
||
"https://example.com/image3.jpg"
|
||
],
|
||
"videoList": [
|
||
"https://example.com/video1.mp4"
|
||
],
|
||
"duration": 120,
|
||
"durationText": "120分钟",
|
||
"status": 1,
|
||
"statusName": "已提交",
|
||
"createTime": "2026-01-23 18:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 标记为已读
|
||
|
||
**接口地址：** `POST /api/growth-record/parent/{id}/read`
|
||
|
||
**功能说明：** 家长端标记成长记录为已读
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| id | Long | 是 | 记录ID（路径参数） | 1 |
|
||
|
||
**请求示例：**
|
||
```bash
|
||
POST /api/growth-record/parent/1/read
|
||
```
|
||
|
||
**响应参数：**
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | Integer | 状态码：200成功 |
|
||
| message | String | 提示信息 |
|
||
| data | Boolean | 操作结果：true成功 |
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "标记成功",
|
||
"data": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 获取周反馈列表
|
||
|
||
**接口地址：** `GET /api/growth-record/parent/weekly/list`
|
||
|
||
**功能说明：** 家长端获取学生的周反馈列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| studentId | Long | 是 | 学生ID | 1 |
|
||
| startDate | String | 否 | 开始日期 | 2026-01-01 |
|
||
| endDate | String | 否 | 结束日期 | 2026-01-31 |
|
||
| page | Integer | 否 | 页码，默认1 | 1 |
|
||
| size | Integer | 否 | 每页数量，默认10 | 10 |
|
||
|
||
**请求示例：**
|
||
```bash
|
||
GET /api/growth-record/parent/weekly/list?studentId=1&page=1&size=10
|
||
```
|
||
|
||
**响应参数：**
|
||
|
||
与"获取成长记录列表"相同，但recordType固定为"weekly"
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 2,
|
||
"studentId": 1,
|
||
"studentName": "小明",
|
||
"teacherId": 1,
|
||
"teacherName": "张老师",
|
||
"recordDate": "2026-01-19",
|
||
"recordType": "weekly",
|
||
"recordTypeName": "周反馈",
|
||
"content": "本周学习状态良好，完成了所有作业...",
|
||
"imageList": [],
|
||
"videoList": [],
|
||
"duration": 600,
|
||
"durationText": "600分钟",
|
||
"status": 1,
|
||
"statusName": "已提交",
|
||
"createTime": "2026-01-19 18:00:00"
|
||
}
|
||
],
|
||
"total": 5,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取月反馈列表
|
||
|
||
**接口地址：** `GET /api/growth-record/parent/monthly/list`
|
||
|
||
**功能说明：** 家长端获取学生的月反馈列表
|
||
|
||
**请求参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|
||
|--------|------|------|------|------|
|
||
| studentId | Long | 是 | 学生ID | 1 |
|
||
| startDate | String | 否 | 开始日期 | 2026-01-01 |
|
||
| endDate | String | 否 | 结束日期 | 2026-01-31 |
|
||
| page | Integer | 否 | 页码，默认1 | 1 |
|
||
| size | Integer | 否 | 每页数量，默认10 | 10 |
|
||
|
||
**请求示例：**
|
||
```bash
|
||
GET /api/growth-record/parent/monthly/list?studentId=1&page=1&size=10
|
||
```
|
||
|
||
**响应参数：**
|
||
|
||
与"获取成长记录列表"相同，但recordType固定为"monthly"
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 3,
|
||
"studentId": 1,
|
||
"studentName": "小明",
|
||
"teacherId": 1,
|
||
"teacherName": "张老师",
|
||
"recordDate": "2026-01-31",
|
||
"recordType": "monthly",
|
||
"recordTypeName": "月反馈",
|
||
"content": "本月学习进步明显，各科成绩都有提升...",
|
||
"imageList": [],
|
||
"videoList": [],
|
||
"duration": 2400,
|
||
"durationText": "2400分钟",
|
||
"status": 1,
|
||
"statusName": "已提交",
|
||
"createTime": "2026-01-31 18:00:00"
|
||
}
|
||
],
|
||
"total": 2,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 权限说明
|
||
|
||
### 认证方式
|
||
- 使用JWT Token认证
|
||
- Token放在请求头：`Authorization: Bearer {token}`
|
||
|
||
### 权限验证
|
||
- 家长只能查看自己孩子的成长记录
|
||
- 需要验证studentId与当前登录家长的关联关系
|
||
|
||
---
|
||
|
||
## 📊 状态码说明
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未登录或token过期 |
|
||
| 403 | 无权限访问 |
|
||
| 404 | 记录不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 🧪 测试用例
|
||
|
||
### 测试用例 1：获取每日反馈列表
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/growth-record/parent/list?studentId=1&recordType=daily&page=1&size=10" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 测试用例 2：获取周反馈列表
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/growth-record/parent/weekly/list?studentId=1&page=1&size=10" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 测试用例 3：获取月反馈列表
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/growth-record/parent/monthly/list?studentId=1&page=1&size=10" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 测试用例 4：获取记录详情
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/api/growth-record/parent/1" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 测试用例 5：标记为已读
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/api/growth-record/parent/1/read" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 前端调用示例
|
||
|
||
### 使用request工具
|
||
|
||
```javascript
|
||
import request from '@/utils/request'
|
||
|
||
// 1. 获取成长记录列表
|
||
async function getGrowthRecordList(params) {
|
||
const res = await request.get('/api/growth-record/parent/list', { params })
|
||
return res.data
|
||
}
|
||
|
||
// 2. 获取成长记录详情
|
||
async function getGrowthRecordDetail(id) {
|
||
const res = await request.get(`/api/growth-record/parent/${id}`)
|
||
return res.data
|
||
}
|
||
|
||
// 3. 标记为已读
|
||
async function markAsRead(id) {
|
||
const res = await request.post(`/api/growth-record/parent/${id}/read`)
|
||
return res.data
|
||
}
|
||
|
||
// 4. 获取周反馈列表
|
||
async function getWeeklyList(params) {
|
||
const res = await request.get('/api/growth-record/parent/weekly/list', { params })
|
||
return res.data
|
||
}
|
||
|
||
// 5. 获取月反馈列表
|
||
async function getMonthlyList(params) {
|
||
const res = await request.get('/api/growth-record/parent/monthly/list', { params })
|
||
return res.data
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 与陪伴员端接口对比
|
||
|
||
| 功能 | 家长端接口 | 陪伴员端接口 | 区别 |
|
||
|------|-----------|-------------|------|
|
||
| 获取列表 | `/api/growth-record/parent/list` | `/api/growth-record/daily/list` | 家长端按studentId筛选，陪伴员端按teacherId筛选 |
|
||
| 获取详情 | `/api/growth-record/parent/{id}` | `/api/growth-record/daily/{id}` | 家长端只读，陪伴员端可编辑 |
|
||
| 创建记录 | ❌ 无 | `/api/growth-record/daily` | 只有陪伴员可以创建 |
|
||
| 更新记录 | ❌ 无 | `/api/growth-record/daily/{id}` | 只有陪伴员可以更新 |
|
||
| 删除记录 | ❌ 无 | `/api/growth-record/daily/{id}` | 只有陪伴员可以删除 |
|
||
| 标记已读 | `/api/growth-record/parent/{id}/read` | ❌ 无 | 只有家长需要标记已读 |
|
||
|
||
---
|
||
|
||
**编写日期：** 2026-01-23
|
||
**编写人员：** Kiro AI Assistant
|
||
**版本：** v1.0
|