add api doc

2024-03-08 00:01:32 +08:00 · 2024-03-08 00:01:32 +08:00 · 0baf91fadf
parent 229dffa9a1
commit 0baf91fadf
1 changed files with 226 additions and 0 deletions
--- a/doc/api.md
+++ b/doc/api.md
@ -0,0 +1,226 @@
+# 接口文档
+
+## 基本格式
+
+### 成功响应格式
+
+```json
+{
+  "success": true,
+  "data": {
+    "foo": "bar"
+  }
+}
+```
+
+**NOTE:** 若无特殊说明，`POST`请求的响应`data`字段为空(`{}`)，可以不用管。
+
+### 失败响应格式
+
+```json
+{
+  "success": false,
+  "err": "some error"
+}
+```
+
+### `GET`请求默认格式（若无特殊说明）
+
+```json
+{
+  "token": "token_test"
+}
+```
+
+## 主页面
+
+### 值班信息 `GET /dutyinfo`
+
+#### 当前在值班
+
+data:
+
+```json
+{
+  "isInDuty": true,
+  "inDutyCnt": 3,
+  "currentDuty": "2"
+}
+```
+
+#### 当前未值班
+
+data:
+
+```json
+{
+  "isInDuty": false,
+  "offDutyReason": "学园维修",
+  "dutyRecoverTime": "下周一"
+}
+```
+
+## 用户页面
+
+### 个人信息 `GET /user/info`
+
+data:
+
+```json
+{
+  "name": "马保国",
+  "phone": "13333333333"
+}
+```
+
+### 修改个人信息 `POST /user/update`
+
+Request body:
+
+```json
+{
+  "name": "宇航员",
+  "phone": "1233333210"
+}
+```
+
+### 本地化设置
+
+#### 获取本地化设置 `GET /user/locale/get`
+
+data:
+
+```json
+{
+  "lang": "zh_CN"
+}
+```
+
+#### 更新本地化设置 `POST /user/locale/update`
+
+Request body:
+
+```json
+{
+  "lang": "en_US"
+}
+```
+
+### 意见反馈 `POST /report`
+
+Request body:
+
+```json
+{
+  "token": "token_test",
+  "content": "aaa bbbb ccccc"
+}
+```
+
+### 我的工单（查询）`GET /user/mytickets`
+
+data (same as oreo):
+
+```json
+{
+  "list": [
+    {
+      "id": 6830,
+      "type": 1,
+      "status": 5,
+      "device": "主机",
+      "deviceModel": "技嘉",
+      "owner": "武技栏",
+      "phone": "18888888888",
+      "createdTime": "2024-03-06T19:49:27.043865",
+      "isConfirmed": false
+    }
+  ]
+}
+```
+
+## 工单详情
+
+### 创建评论 `POST /tickets/newcomment/{id}`
+
+Request
+
+```json
+{
+  "content": "这是一条评论",
+  "token": "token_test"
+}
+```
+
+### 创建工单 `POST /tickets/create`
+
+Request
+
+```json
+{
+  "token": "token_test",
+  "type": 1, // 电器是0，电脑是1(bushi)
+  "device": "华硕",
+  "deviceModel": "天选3",
+  "owner": "西西弗",
+  "phone": "12333333333",
+  "description": "没法用pd充电",
+  "accessories": [0]
+}
+```
+
+### 工单信息 `GET /tickets/info/{id}`
+
+data (same as oreo):
+
+```json
+{
+  "id": 6847,
+  "type": 1,
+  "device": "华硕",
+  "deviceModel": "灵耀X14",
+  "owner": "唐姐姐",
+  "phone": "15555555555",
+  "description": "清灰",
+  "workers": [],
+  "createdTime": "2024-03-07T19:52:48.523303",
+  "status": 5,
+  "isConfirmed": false,
+  "notes": [
+    {
+      "avatar": "https://....jpg",
+      "id": 21368,
+      "op": "宇航员",
+      "type": 0,
+      "content": "",
+      "createdTime": "2024-03-07T19:52:48.523305"
+    },
+    {
+      "avatar": "https://....jpg",
+      "id": 21370,
+      "op": "宇航员",
+      "type": 2,
+      "content": "1",
+      "createdTime": "2024-03-07T19:58:27.838816"
+    },
+    {
+      "avatar": "https://....jpg",
+      "id": 21373,
+      "op": "宇航员",
+      "type": 2,
+      "content": "4",
+      "createdTime": "2024-03-07T20:28:12.070707"
+    },
+    {
+      "avatar": "https://....jpg",
+      "id": 21374,
+      "op": "宇航员",
+      "type": 2,
+      "content": "5",
+      "createdTime": "2024-03-07T20:30:15.770486"
+    }
+  ],
+  "accessories": [2],
+  "picked": false
+}
+```