00. 概述

开发说明

1. 应用基于 Egg.js 框架开发，Node 版本应高于 v8.0.0

2. 由于测试期间发现请求量很大，5 个用户的月平均请求就已经达到 3.5k 次，迫于生计，数据库已经从 LeanCloud 换成 MongoDB，本地开发时需要自行安装，默认使用的 Database 名称是 uestc，可在 config.default.js 文件中修改 MongoDB 的配置

API 列表

为保证数据安全，建议线上 API 仅接受 HTTPS 请求

URL	功能	访问是否 需要鉴权 （TOKEN）	数据格式	文档
POST /api/user/login	使用学号、密码登录统一身份认证系统	NO	application/json	登录
POST /api/user/exit	退出登录	YES	application/json	退出登录
POST /api/user/delete	删除账号信息，停止服务	NO	application/json	删除账户
GET /api/user/profile	获取个人信息	YES	application/json	个人信息
POST /api/user/profile	设置账户信息	YES	application/json	设置个人信息
POST /api/user/course	按学年学期获取用户课程表	YES	application/json	课程
POST /api/user/exam	按学年学期获取用户考试安排数据	YES	application/json	考试
POST /api/user/grade	按学年学期获取用户成绩数据	YES	application/json	成绩
POST /api/user/usualGrade	按学年学期获取用户平时成绩数据	YES	application/json	平时成绩
GET /api/user/grade	获取用户所有学期成绩数据	YES	application/json	所有成绩
GET /api/user/gpa	获取用户所有学期绩点（GPA）数据	YES	application/json	绩点
POST /api/xifu/bind	登录喜付账户，将喜付账户与学号绑定	YES	application/json	绑定喜付账户
GET /api/xifu/ecard	获取一卡通信息（余额，是否有效等）	YES	application/json	一卡通
GET /api/xifu/bill	获取喜付最近 30 天消费账单 （仅一卡通消费明细，电费账单无法获取）	YES	application/json	账单
POST /api/xifu/electricity	按房间号获取电费信息	YES	application/json	电费
GET /api/extra/traffic	修改后的 http://bbs.uestc.edu.cn/bus 页面，使之适合手机访问	NO	text/html	其他
GET /api/extra/info	302 至教务处常用信息（手机页面）	NO	text/html	其他
GET /api/extra/stu	302 至教务处教学管理公告（手机页面）	NO	text/html	其他
GET /api/extra/edu	302 至教务处教研教改公告（手机页面）	NO	text/html	其他
GET /api/extra/communication	302 至教务处实践交流公告（手机页面）	NO	text/html	其他
GET /api/extra/news	302 至教务处教学新闻（手机页面）	NO	text/html	其他
GET /api/extra/room	302 至空闲教室查询（手机页面）	NO	text/html	其他
GET /api/extra/today-course	302 至当日课程查询（手机页面）	NO	text/html	其他
GET /api/extra/search-course	302 至全校课程查询（手机页面）	NO	text/html	其他
GET /api/extra/search-teacher	302 至教师信息查询（手机页面）	NO	text/html	其他

响应格式

名称	类型	说明
code	number	状态码
msg	string	请求成功信息
err	string	错误信息
data	mixed	响应结果
time	timestamp	UTC 时间戳

HTTP 状态码

对于所有框架可以捕获的服务端错误，服务端都会返回 200 OK，具体状态信息将显示在响应 body 的 code 和 err 中，下表的状态码特指响应 body 的 code。

状态码	状态信息	请求方式	说明
200	OK	[GET]	服务器成功返回用户请求的 数据，该操作是幂等的（Idempotent）
201	Created	[POST]	用户新建或修改或删除数据成功
202	Accept	[POST]	定时任务已经进入后台排队
400	Invalid Request	[*]	用户发出的请求参数错误/没有通过验证
401	Unauthorized	[*]	用户没有权限，一般为 Token 错误
403	Forbidden	[*]	由于后方教务系统等非常 不稳定，故用 403 特指一些可以捕获的后方系统错误
404	Not Found	[*]	用户发出的请求针对的是不存在的 记录，服务器没有进行操作，该操作是幂等的
406	Not Acceptable	[GET]	用户请求的格式不可得（比如用户请求 XML 格式，但是只有 JSON 格式）
500	Internal Server Error	[*]	服务器发生错误，用户将无法判断发出的请求是否成功

数据库表结构

1. 不在数据库中保存非必要的有关用户隐私的数据，如课程、成绩、一卡通等信息，将缓存功能交给客户端

2. 数据库已经更换到 MongoDB，新设计的表结构中不再需要保存用户的密码

users 用户表

字段	类型	说明
username	String	学号
finalCookies	String	教务系统 Cookies
avatarUrl	String	头像 URL
nickName	String	昵称
bio	String	签名/一句话说明
createdAt	Date	数据创建时间
updatedAt	Date	数据更新时间

xifus 喜付账户表

字段	类型	说明
username	String	学号
sid	String	喜付 Cookies
createdAt	Date	数据创建时间
updatedAt	Date	数据更新时间

其他注意事项

• 处于 dev 分支的代码目前处于活跃更新中，有些更新可能更改默认的 API 请求行为，请留意

• 高频率请求教务系统会导致 IP 被冻结，特提供了配置 HTTP(S) 代理的选项，实际使用时请注意调用频率

部分依赖框架/库

1. Egg.js

2. cheerio

3. moment

4. request-promise-native

5. underscore

对于 Egg 框架中没有详细说明的内容，可以在 Egg.js 官网 查阅