docs: update README.md

README.md

@@ -1,8 +1,44 @@
-# gzic_bus (WIP)
+# gzic_bus
 
 华南理工大学广州国际校区校巴预约API（对应`GZIC智慧服务`小程序）
 > ~~摆脱这个巨卡无比的小程序~~
 
-## ScreenShot
+## 项目介绍
 
-![demo](demo.gif)
+- `api`文件夹为校巴相关接口的爬虫（包含校巴查看、预约、获取二维码等借口）
+- `cli`文件夹为命令行脚本相关模块，可以直接运行进行预约等操作
+- 整理了校巴接口的[文档](docs/%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3.md)，方便用别的语言重写
+
+## cli使用方法
+
+1. 安装依赖(`requests`和`questionary`)
+    ```
+    pip install -r requirements.txt
+    ```
+
+2. 运行脚本
+    ```
+    python main.py
+    ```
+
+3. 关于`token`
+    > 校巴接口需要传递`token`作为鉴权`header`，本程序会将`token`保存为`.token`文件，首次使用将进行统一认证登陆获取`token`，之后默认读取本地文件。`token`有效期较长，不需要经常更新。
+
+## cli功能
+
+- 预约校巴 
+    > 非常简单的起点终点选择，而不是反应缓慢的小程序点击
+    >
+    > 日期的选择，只查看某一天的班次，而不是小程序的杂乱列表
+    >
+    > 几个回车就能马上预约到校巴，而小程序可能刚刚加载好
+
+- 查看已预约校巴
+    > 列出预约未乘坐的班次，只显示有用的信息
+    >
+    > 轻松取消校巴
+
+## 后续更新方向
+
+1. 自动预约脚本
+2. 抢票脚本

api/bus.py

@@ -1,4 +1,3 @@
-from unittest import result
 import requests
 
 

docs/接口文档.md

@@ -0,0 +1,149 @@
+# `GZIC智慧服务`小程序校巴预约模块接口文档
+
+## 一. 基本信息
+
+`base_url`: `"https://life.gzic.scut.edu.cn/commute/open/commute"`
+
+发送请求需要附带`http`头：`authorization`，其值为统一认证登陆之后获取到的`token`
+
+参考：[api/bus.py](../api/bus.py)
+
+## 二、预约校巴列表
+
+- Method: `POST`
+- URL: `/commuteOrder/frequencyChoice?PageNum={page_num}&PageSize={page_size}`
+  - `page_num`和`page_size`分别为展示页码数和页面容量，都为 0 则展示全部
+- Param:
+
+  ```json
+  {
+    "startDate": "yyyy/mm/dd",
+    "startCampus": "校区名称",
+    "endDate": "yyyy/mm/dd",
+    "endCampus": "校区名称",
+    "startHsTime": "hh:mm",
+    "endHsTime": "hh:mm"
+  }
+  ```
+
+  > 校区名称为`广州国际校区`、`大学城校区`、`五山校区`
+
+- Response:
+  ```json
+  {
+    "code": 200,
+    "msg": "",
+    "list": []
+  }
+  ```
+
+## 三、预约车票
+
+- Method: `POST`
+- URL: `/commuteOrder/submitTicket`
+- Param:
+  ```json
+  [
+    {
+      "ids": "",
+      "dateDeparture": "",
+      "startDate": "",
+      "endDate": "",
+      "startLocation": "",
+      "downtown": "",
+      "tickets": 1,
+      "ischecked": true,
+      "subTickets": 1
+    }
+  ]
+  ```
+  > 参数除`ischecked`和`subTickets`外都为`预约校巴列表`接口返回的信息
+- Response:
+  ```json
+  {
+    "code": 200,
+    "msg": ""
+  }
+  ```
+
+## 四、查看某车票信息
+
+- Method: `GET`
+- URL: `/commuteOrder/ticketDetail?id={ticket_id}`
+  - `ticket_id`为车票 id
+- Response:
+  ```json
+  {
+    "data": {
+      "id": 1,
+      "startTime": "",
+      "endTime": "",
+      "ruteName": ""
+    }
+  }
+  ```
+
+## 五、车票二维码
+
+> 车票二维码实际上为`json文本信息`，内容为：
+
+```json
+{
+  "id": 0, // 车票id
+  "frequencyId": 0 // 车票frequencyId
+}
+```
+
+只需获取信息后转化为二维码即可
+
+## 六、查看车票
+
+- Method: `GET`
+- URL: `/commuteOrder/orderFindAll?status={status}&PageNum={page_num}&PageSize={page_size}`
+  - `status`为 0 时返回全部预约过的车票，为 1 时返回已预约未乘车的车票，为 2 时返回失约未乘车车票，为 3 时返回未评价车票
+  - `page_num`和`page_size`分别为展示页码数和页面容量，都为 0 则展示全部
+- Response:
+  ```json
+  {
+    "code": 200,
+    "msg": "",
+    "totalPage": 1,
+    "totalSize": 1,
+    "list": [
+      {
+        "id": 0,
+        "orderDate": "",
+        "dateDeparture": "",
+        "startTime": "",
+        "ruteName": ""
+      }
+    ]
+  }
+  ```
+
+## 七、取消车票
+
+- Method: `GET`
+- URL: `/commuteOrder/cancelTicket?id={ticket_id}`
+  - `ticket_id`为车票id
+- Response:
+  ```json
+  {
+    "code": 200,
+    "msg": "",
+  }
+  ```
+
+
+## 八、删除车票记录（请在取消车票后调用）
+
+- Method: `GET`
+- URL: `/commuteOrder/removeOrderCanal?id={ticket_id}`
+  - `ticket_id`为车票id
+- Response:
+  ```json
+  {
+    "code": 200,
+    "msg": "",
+  }
+  ```