00. 概述

开发说明

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

2. MongoDB 默认使用的 Database 名称是 uestc，可在 config.default.js 文件中修改 MongoDB 的配置

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

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

API 列表

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

1. 标准 API

URL	功能	请求方式	访问是否 需要鉴权 （TOKEN）	数据格式	文档
/api/user/login	使用学号、密码 登录统一身份认证系统	POST	NO	application/json	登录
/api/user/exit	退出登录	POST	YES	application/json	退出登录
/api/user/delete	删除账号信息 停止服务	POST	NO	application/json	删除账户
/api/user/profile	获取个人信息	GET	YES	application/json	获取个人信息
/api/user/profile	设置账户信息	POST	YES	application/json	设置个人信息
/api/user/course	按学年学期 获取用户课程表	POST	YES	application/json	课程
/api/user/exam	按学年学期 获取用户考试安排数据	POST	YES	application/json	考试
/api/user/grade	按学年学期 获取用户成绩数据	POST	YES	application/json	成绩
/api/use r/usualGrade	按学年学期 获取用户平时成绩数据	POST	YES	application/json	平时成绩
/api/user/grade	获取用户 所有学期 成绩数据	GET	YES	application/json	所有成绩
/api/user/gpa	获取用户 所有学期 成绩统计数据 包括绩点（GPA）	GET	YES	application/json	成绩统计
/api/living/ecard	获取一卡通信息	GET	YES	application/json	一卡通
/api/living/loss	挂失一卡通	POST	YES	application/json	一卡通挂失
/api/living/bill	查询消费账单	POST	YES	application/json	账单
/api/liv ing/electricity	获取宿舍电费信息	POST	NO	application/json	电费
/api/home/calendar	获取校历数据	POST	NO	application/json	校历
/api/extra/traffic	出行信息	GET	NO	text/html	其他
/api/extra/traffic	联系信息	GET	NO	text/html	其他
/api/extra/info	教务处常用信息	GET	NO	text/html	其他
/api/extra/stu	教务处 教学管理公告	GET	NO	text/html	其他
/api/extra/edu	教务处 教研教改公告	GET	NO	text/html	其他
/api/extr a/communication	教务处 实践交流公告	GET	NO	text/html	其他
/api/extra/news	教务处 教学新闻	GET	NO	text/html	其他
/api/extra/room	空闲教室查询	GET	NO	text/html	其他
/api/extra/today-course	当日课程查询	GET	NO	text/html	其他
/api/extra/search-course	全校课程查询	GET	NO	text/html	其他
/api/extra/search-teacher	教师信息查询	GET	NO	text/html	其他

2. 开发者 API

URL	功能	请求方式	访问是否 需要鉴权 （TOKEN）	数据格式	文档
/api/dev/idas	使用学号、密码 获取教务系统 Cookies	POST	NO	application/json	教务系统 Cookies
/api/dev/ecard	使用学号、密码 获取一卡通 Cookies	POST	NO	application/json	一卡通 Cookies
/api/liv ing/electricity	获取宿舍电费信息	POST	NO	application/json	电费
/api/home/calendar	获取校历数据	POST	NO	application/json	校历

响应格式

名称	类型	说明
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. 由于一卡通数据源网站已更换为学校官方网站，因此取消了 xifus 用户表，请知悉

users 用户表

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

部分依赖框架/库

1. Egg.js

2. cheerio

3. moment

4. request-promise-native

5. underscore

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