jiaozijun / teaching-service-wiki

Go to a project
Toggle navigation Toggle navigation pinning
jiangtengfei
844954e2 1 parent ee1589ef

add other .md files

Inline Side-by-side
Showing 5 changed files with 710 additions and 0 deletions
#发推送接口
接口地址：/teaching/callback/push_notification
请求方式：GET
Request Params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|-----------|--------|-----------------|
|work_order_id |是 |工单id |Long |
|notification_type|是 |推送类型 |“ABSENT” or "START_CLASS" 不区分大小写|
# 发推送接口 - 通用
接口地址：/teaching/callback/push
请求方式：POST
RequestBody:
```
[
{
"user_id":12938,
"push_title":"testtt",
"data":{
"type":"GRABORDER",
"count":123
}
},
{
"user_id":12938,
"push_title":"testtt",
"data":{
"type":"GRABORDER",
"count":123
}
}
]
```
返回值：
```
{
"data": {},
"returnCode": 200,
"returnMsg": "success"
}
```
#查询工单对应的腾讯云错误码和信息
接口地址：/teaching/callback/qcloud/error_info
请求方式：GET
请求参数： work_order_id
返回值：
```
[
{
"work_order_id": 345,
"error_code":"10002",
"error_msg":"群组不存在，或者曾经存在过，但是目前已经被解散。"
},
{
"work_order_id": 3453,
"error_code":"10001",
"error_msg":"群组ID非法，请检查群组ID是否填写正确。"
}
]
```
# 发短信接口 - 通用
接口地址: /teaching/sms/send
请求方式: POST
请求参数:
|参数名 |是否必须 |说明 |参数类型 |
|--------------|-----------|--------|-----------------|
|user_id |是 |用户id |Long |
|template_code |是 |短信模板id|String |
|data |是 |短信模板中的参数json|String |
返回值:
status: 200
# 群发通知接口 - 通用
接口地址: /teaching/callback/push/group
请求方式: POST
request body :
```
{
"alias": [
"12938",
"12939"
],
"push_title": "aaaa",
"data": {
"type":"T"
}
}
```
返回值:
```
{
"data": "ok",
"returnCode": 200,
"returnMsg": "success"
}
```
# 根据工单id获取群成员资料
接口地址: /teaching/group/member
请求方式: POST
request body:
```
[123,456,789,57073]
```
response body:
```
[
{
"groupId": "@TGS#2MSRWMJEG",
"workOrderId": 123,
"memberAccount": [
"202cb962ac59075b964b07152d234b70"
]
},
{
"groupId": "@TGS#2RSE7WJEH",
"workOrderId": 57073,
"memberAccount": [
"b0d3549dd95ee0e99f402b37778d1a88",
"2d7d9ba8bc62e62b491208e7bb1e397c"
]
}
]
```
\ No newline at end of file
... ...
* [返回远程教学之流程消息](远程教学之流程消息)
* [返回在线授课相关文档](在线授课相关文档)
### 接口定义
#### 名词定义
* 在线授课必备消息
在线授课必须的公用群名、群Id（授课指令用）以及聊天室Room的Id（音视频聊天用）
* 听课学生基本信息
Id、头像、昵称、目标、学习统计（词汇量、阅读量、听力时长、口语时长）
* 授课教师基本信息
Id，头像，昵称
### 获取用户访问Qcloud的identifier和签名
/user/me接口中增加返回值：
```
...
"qcloud": {
"identifier": "5de6f7a36339ef5bedc3dc8741a1e222",
"sign": "eJxFkN1ugkAQRt*F2zZ12R8Xe4doG9BGjZLaK4K7g6yUFWElYNN3LxJMb8*ZLzPf-Fi75fYlLgolo9hEpJTWq4Ws5x5DU6gSojgxUHbYZoxhhB62hrJSZ90JjGxmY4LQv1QStFGJ6oNMwjjhMRkTMoGEHUAKIoXDqR3bgDEeMpU6dsMf8y-P38xWp0nwbXahDg*e66U34be6qjd1VmdN6gZzAQ5-aszeXI9*6i7eQK3VjE61TZcB359QkKD3URhePqdbslq3eSBu-LLw89Fjmcyivva9GL1fTgljgzQqh54zh3DGKB94LMT5qk1k2gL6P-3*AfZQX20_"
},
...
```
# 更新鱼卡状态说明
| 鱼卡状态 | 状态说明 |是否需要客户端参与 |备注 |
|--------------|---------------------------|------------------|--------|
|创建 |鱼卡创建初始状态 |N | |
|分配课程 |分配课程 |N | |
|分配教师 |匹配教师 |N | |
|等待学生上课应答 |老师发起上课邀请后 |N | |
|~~就绪~~ |~~双方进入房间，学生课程已下载~~ |Y | |
|正在上课 |老师点击开始上课 |Y | |
|完成 |下课（1.点击下课。2.强制下课） |Y | 下课前5分钟内离开，服务器自己更新状态|
|教师旷课 |上课5分钟后老师没有发起邀请 |N | |
|学生旷课 |上课5分钟后学生没有接受邀请 |N | |
|学生早退 |学生中途离开5分钟以上 |Y |客户端老师端上报信息|
|教师早退 |教师中途离开5分钟以上 |Y |客户端学生端上报信息|
|系统异常 |异常 |Y |客户端双方上报信息|
# 0.统一状态码
> * 设备未绑定成功 错误码：101 描述：设备未绑定成功
> * deprecate ~~工单校验失败 错误码：102 描述：工单校验失败~~
> * 进入房间回调失败 错误码: 103 描述: 进入房间回调失败
> * 工单不存在 错误码: 105 描述: 工单不存在
# 1.显示学生、课程等信息
> 说明：授课客户端需要获取**在线授课必备消息**和**听课学生基本信息**
>
> 显示学生信息，课程信息，饼图，柱状图
>
接口地址：/teaching/student/info
请求方式：GET
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|-----------|--------|-------------------|
|work_order_id |是 |工单id |Long |
**腾讯云的用户identifier 为盒子鱼用户id的小写md5值**
Response：
```
{
"data": {
"student_detail": {
"student_info": {
"real_name": "Mmm",
"figure_url": "http://avatars.boxfish.cn/user/12938/figure/1423708364.jpg",
"level": 6,
"level_name": "滔滔6级"
},
"lesson_info": {
"id": "L3NoYXJlL3N2bi_nvo7lm73or63mlocyLTEvMDAxLkV2ZW5pbmcgYXQgSG9tZS54bHN4",
"name": "Evening at Home",
"lastModified": 1448379647022,
"type": "全面提高",
"difficulty": "1.5",
"cover": "73dcb39a42bbfd6b3cc83b2569cf4bce"
},
"achievement_info": {
"read_word_count": "0词",
"listening_time": "0秒",
"record_time": "0秒",
"word_count": "3词"
},
"course_type_info": {
"course_type_ratio": [
{
"course_type": "Conversation",
"ratio": 0.1
},
{
"course_type": "Passage",
"ratio": 0.05
},
{
"course_type": "Function",
"ratio": 0.15
},
{
"course_type": "Phonics",
"ratio": 0.1
},
{
"course_type": "Examination",
"ratio": 0.1
},
{
"course_type": "Words",
"ratio": 0.1
},
{
"course_type": "Grammar",
"ratio": 0.2
},
{
"course_type": "Textbook",
"ratio": 0.1
},
{
"course_type": "Music",
"ratio": 0.1
}
],
"course_count": 324
}
},
"group_room_info": {
"group_name": "BOXFiSH Online Teaching Group",
"group_id": "@TGS#2SMUBTAER",
"chat_room_id": 359755386104019
}
},
"returnCode": 200,
"returnMsg": "success"
}
```
# 2.发推送 - 通知学生开始上课
> 说明：通知某次课程相应的学生准备上课，通过发送推送信息的方式通知给学生。推送的通知中应该包括**在线授课必备消息**和**授课教师的基本信息**
>
>
接口地址：/teaching/student/push
请求方式：GET
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|----------------|----------|--------|------------|
|work_order_id |是 |工单id | Long |
推送json：
```json
{
"type":"ONCLASS",
"figure_url": "http://wx.qlogo.cn/mmopen/PiajxSqBRaEJrztQnGAk8X1G2A0AfjvPRBdgLFOjxsM9AoicoOUrH3Yia3qY9uic5ibQO6wMkJ6bPUx15IN4Vrxv8CA/0",
"teacher_name": "喜洋洋老师",
"teacher_id": "5",
"work_order_id": "34",
"start_time": "2016-05-18 09:00:00",
"end_time": "2016-05-18 10:00:00",
"group_name": "boxfish-class001",
"group_id": "@TGS#2AA4BQAEN",
"chat_room_id": "100001"
}
```
Response:
1.工单有效
```
{
"data": {
"msg_id": 3385486500,
"sendno": 1380240050,
"originalContent": "{\"sendno\":\"1380240050\",\"msg_id\":\"3385486500\"}",
"resultOK": true,
"rateLimitQuota": 600,
"rateLimitRemaining": 599,
"rateLimitReset": 60
},
"returnCode": 200,
"returnMsg": "success"
}
```
2.工单无效
(1) 未到上课时间
```
{
"data": {},
"returnCode": 10,
"returnMsg": "未到上课时间"
}
```
(2) 迟到未在上课时间
```
{
"data": {},
"returnCode": 20,
"returnMsg": "迟到未在上课时间"
}
```
(3) 不存在对应的工单
```
{
"data": {},
"returnCode": 1,
"returnMsg": "不存在对应的工单"
}
```
# 3.课程正常结束接口
接口地址：/teaching/student/finish
请求方式： POST
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|----------|--------|----------|
|work_order_id |是 |工单id |Long |
返回值：
```
{
"data": {},
"returnCode": 200,
"returnMsg": "success"
}
```
# 4.房间进入状态回调接口
> 说明：老师进入房间、学生进入房间各回调一次
接口地址：/teaching/callback/chat_room
请求方式：POST
Request body：
```
{
"userId":12938,
"type":"TEACHER",
"workOrderId": 34,
"chatRoomId":12345
}
```
Response
```
{
"data": {},
"returnCode": 200,
"returnMsg": "success"
}
```
# 5.客户端断线重连获取课程状态
> 说明：
接口地址：/teaching/course/status
请求方式：GET
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|----------|--------|----------|
|work_order_id |是 |工单id |Long |
Response：
```
{
"data": {
"recover": true
},
"returnCode": 200,
"returnMsg": "success"
}
```
# 6.学生端未收到上课推送主动发起上课接口
> 说明：
接口地址：/teaching/student/enter_class
请求方式：GET
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|----------|--------|----------|
|work_order_id |是 |工单id |Long |
Response:
1.工单有效
```
{
"data": {
"group_id": "@TGS#2SMUBTAER",
"chat_room_id": 359755386104019
},
"returnCode": 200,
"returnMsg": "success"
}
```
2.工单无效
(1) 未到上课时间
```
{
"data": {},
"returnCode": 10,
"returnMsg": "未到上课时间"
}
```
(2) 迟到未在上课时间
```
{
"data": {},
"returnCode": 20,
"returnMsg": "迟到未在上课时间"
}
```
(3) 不存在对应的工单
```
{
"data": {},
"returnCode": 1,
"returnMsg": "不存在对应的工单"
}
```
# 7.获取课程所有资源列表
> 说明： 学生端调用，从学生端的课程列表可以获取到lesson_id
>
接口地址：/teaching/resource/lesson
请求方式：GET
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|-----------|--------|-----------|
|lesson_id |是 |课程id |String |
Response ：
```
{
"data": [
"0a29673921a26ffb5e5ee81ffed45a9e",
"0c8a151d1b5eb95bd435e2e1af23ea15",
"2156d9b3f571381b3eca40d6e9d6e1cc"
"23dc1178bf9b5f813911f4e798949233",
...
"e77a984dc4cbf889c081f8a53a36f859"
],
"returnCode": 200,
"returnMsg": "success"
}
```
# 8 .旷课回调接口
>在Request body的参数中,`userId`是用户自己的id, `type`是用户类型, `TEACHER` 或者`STUDENT`
>
接口地址：/teaching/callback/absent
请求方式：POST
Request body：
```
{
"userId":12938,
"type":"STUDENT",
"workOrderId":3979
}
```
Response ：
```
{
"data": {},
"returnCode": 200,
"returnMsg": "success"
}
```
# 9.进入课堂回调接口
> 老师点击`开始上课`后调用该接口
接口地址：/teaching/callback/start_class
请求方式：POST
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|----------|--------|----------|
|work_order_id |是 |工单id |Long |
Response：
```
{
"data": {
},
"returnCode": 200,
"returnMsg": "success"
}
```
# 10.取消推送接口
> 老师在发送推送页面点击`取消`按钮调用该接口
接口地址：/teaching/student/cancel_push
请求方式：GET
Request params：
|参数名 |是否必须 |说明 |参数类型 |
|--------------|----------|--------|----------|
|work_order_id |是 |工单id |Long |
推送 json：
```
{
"work_order_id":"12938",
"type":"CANCEL"
}
```
Response:
```
{
"data": {
},
"returnCode": 200,
"returnMsg": "success"
}
```
\ No newline at end of file
... ...
|学生 |templateCode |
|-----------------------------------------------------------------------------|---------------|
|同学，你今天{startTime}的在线课程在{minute}分钟后开始，请提前做好上课准备。 |SMS_15110230 |
|同学，你明天有{quantity}节在线课程，上课时间{startTime}，请提前做好上课准备。 |SMS_15120322 |
|老师 |templateCode |
|-----------------------------------------------------------------------------|---------------|
|老师您好，您今天有{quantity}节在线课程，第一节在{startTime}开始，请准时上课。祝愉快。 |SMS_15160346 |
|老师您好，新增{startTime}课程《{courseName}》，请您准时上课。祝愉快。 |SMS_15085203 |
|老师您好，您的课程：{startTime}《{courseName}》，由于{cancelReason}已取消。祝愉快。 |SMS_15115267 |
\ No newline at end of file
... ...
# 状态码
* 设备未绑定成功 错误码：101 描述：设备未绑定成功
* deprecate ~~工单校验失败 错误码：102 描述：工单校验失败~~
* 进入房间回调失败 错误码:103 描述: 进入房间回调失败
* 旷课回调失败 错误码: 104 描述: 旷课回调失败
* 工单不存在 错误码: 105 描述: 工单不存在
\ No newline at end of file
... ...
# 工单校验文案
英文文案
订单不存在： WORK_ORDER_NOT_EXISTS=The lesson's canceled for some reason.
上课太早：WORK_ORDER_TOO_EARLY=Not the right time for class yet; Please try again later.
老师旷课：WORK_ORDER_TOO_LATE=You've missed the lesson; It's already over.
学生旷课：WORK_ORDER_STUDENT_ABSENT=Your student have missed the lesson; It's already over.
课程已结束：WORK_ORDER_CLASS_OVER=Class is over
中文文案
订单不存在： WORK_ORDER_NOT_EXISTS=本次课已取消
上课太早：WORK_ORDER_TOO_EARLY=未到上课时间，请准点上课。
老师旷课：WORK_ORDER_TOO_LATE=您已旷课，课程结束。
学生旷课：WORK_ORDER_STUDENT_ABSENT=您的学生已旷课
课程已结束：WORK_ORDER_CLASS_OVER=课程已结束
\ No newline at end of file
... ...