BXT Protocol

bxt

1.基础信息

除了一些特殊接口（比如登录）之外，其它业务接口全部使用 RESTFul 形式提供，使用本协议前，请参考 RESTFul 协议说明。

特殊说明：

1. 班级表理应命名为 class，但由于跟 PHP 的关键字相同，所以统一命名为 klass，所以需要传递参数的地方，和 RESTFul 接口都使用 klass 命名。
2. 本次接口的调试用到了 mock server，所以将接口响应信息放到了 mock server 中进行描述。

2.用户相关

2.1.用户登录

请求：

• 类型：POST
• 路径：/wx-login
• 参数：

2.2.查询个人信息

用于刷新当前登录用户信息。

请求：

• 类型：GET
• 路径：/user-info
• 参数：无

反馈：

跟2.1.用户登录相同

3.学校相关

3.1.查询所有省

请求：

• 类型：GET
• 路径：/provinces
• 参数：

3.2.查询省内城市

• 类型：GET
• 路径：/cities
• 参数：

3.3.查询市内县区

• 类型：GET
• 路径：/counties
• 参数：

4.学校相关

4.1.查询学校

• 类型：GET
• 路径：/schools
• 参数：

4.2.添加学校

• 类型：POST
• 路径：/shcools
• 参数：

5.班级相关

5.1.查询班级

（用户靠微信分享找到所属班级，所以暂时用不到该接口）

查询学校内的所有班级。

• 类型：GET
• 路径：/klasses
• 参数

5.2.添加班级

• 类型：POST
• 路径：/klasses
• 参数：

5.3.修改班级

• 类型：PATCH
• 路径：/klasses/{{klassSid}}
• 参数：

绑定微信群到班级：只传 password, wxGroupUid 和 wxGroupName 时，实现绑定班级到微信群功能。

6.学生相关

6.1.查询学生

• 类型：GET
• 路径：/students
• 参数：

只能查询班级内的所有学生。

6.2.添加学生

向某个班级添加学生，用于绑定家长和学生关系时，如果学生不存在，首先要添加学生到班级。

• 类型：POST
• 路径：/students
• 参数：

6.3.修改学生

• 类型：PATCH
• 路径：/students/{{studentSid}}
• 参数：

6.3.删除学生

• 类型：DELETE
• 路径：/students/{{studentSid}}
• 参数：无

注意：

1. 只有创建者才能删除自己创建的学生；
2. 删除学生后，自动删除所有跟该学生绑定的家长关系。

7.家长关系

7.1.绑定家长关系

• 类型：POST
• 路径：/student-user-relations
• 参数：

7.2.修改家长关系

• 类型：PATCH
• 路径：/student-user-relations/{{studentUserRelationSid}}
• 参数：

8.老师相关

8.1.查询老师

只能查询班级内的所有老师。

• 类型：GET
• 路径：/teachers
• 参数：

8.2.添加老师

• 类型：POST
• 路径：/teachers
• 参数：

8.3.修改老师

• 类型：PATCH
• 路径：/teachers/{{teacherSid}}
• 参数：

9.通知相关

9.1.查询通知

只能查询一个班级的所有通知。

• 类型：GET
• 路径：/notices
• 参数：

反馈：

{
    "status": 0,
    "msg": "查询成功",
    "items": [
        {
            "sid": "5A6007B6C4D21768913367",
            "category": 0,
            "subject": "语文",
            "title": "1-18 日作业",
            "content": "期末测试卷订正，家长签字。",
            "images": "http://1.jpg|http://2.jpg",
            "deadline": "2018-01-18 08:30:00",
            "state": 0,
            // 发向多个班级的通知有此属性
            "groupUid": "22018-01-20 09:49:27",
            "receiptRequirement": "image,text",
            "createdAt": "2018-01-18 10:34:30",
            "updatedAt": "2018-01-18 10:34:30",
            "klassSid": "5A5DDA1C6D7B9969670340",
            "creatorSid": "5A5F6F0B90382339402696",
            // 通知创建者信息
            "creatorInfo": "郭冰怡老师",
            // 通知反馈状态
            "receiptStatus": "0/1",
            // 通知发向多个班级的班级 ID，逗号分隔
            "sharedKlasses": "5A62A027DF366478143055,5A62A027E0DE1633776242"
        }
    ]
}

9.2.添加通知

• 类型：POST
• 路径：/notices
• 参数：

10.回执相关

10.1.查询回执

• 类型：GET
• 路径：/receipts
• 参数：

10.2.添加回执

• 类型：POST
• 路径：/receipts
• 参数：

10.3.修改回执

• 类型：PATCH
• 路径：/receipts/{{receiptSid}}
• 参数：

支持 “添加回执”中除了 noticeSid 和 studentSid 以外的所有参数。

10.3.删除回执

• 类型：DELETE
• 路径：/receipts/{{receiptSid}}
• 参数：无

11.表单 ID 相关

11.1.添加 formId

• 表单 ID 对应小程序 API 中的 formId 字段，用于通过模板消息向用户主动推送通知；
• 我们为每个用户缓存 10 个 formId，所以最多可以向用户发送 10 条模板消息；
• formId 在超过 7 天不用时会失效，所以原则上希望能够随时更新 formId；

为了能随时更新缓存用户的 formId，我们将它的更新机制设计到以下接口中：

• 班级：create, update (暂未实现）
• 通知：create, update
• 回执：create, update (暂未实现）

在调用以上接口时，请自主增加 formId 参数，服务器收到后，会自动将 formId 缓存到 formId 表中。

11.2.查询 formId

• 类型：GET
• 路径：/form-ids
• 参数：无

{
    "status": 0,
    "msg": "操作成功",
    "object": {
        "createdAt": "2018-01-23 18:23:54",
        "updatedAt": "2018-01-23 18:30:57",
        "userSid": "5A5DD9A587D53831485354",
        "formIds": [
            {
                "formId": "songyushaninnoticeupdate1",
                "obtainTime": "2018-01-23 18:25:32"
            },
            {
                "formId": "songyushaninnoticeupdate2",
                "obtainTime": "2018-01-23 18:30:57"
            }
        ]
    }
}

TODO:

• 修改学生图片时，服务器判断新旧图片数组，将已经不需要的图片删除。
• 老师可以对回执进行评价：接受、拒绝，并发表意见。