5.我的 API - HackMD

--- tags: NeutecLife App --- # 5.我的 API :::info 目錄： <a href="https://hackmd.io/FStSBTFdRhac3tsDr8OyiA">0.登入功能相關 API 文件</a> <a href="https://hackmd.io/coOyibBDRYqJpluQIQFYmg">1.首頁功能相關 API 文件</a> <a href="https://hackmd.io/-A3kGYJ8SHyjegBROlwJow">2-1.分類列表：分類列表頁、借書＆歸還 API 文件</a> <a href="https://hackmd.io/boCGrFpsR0CciLYEXS-kxw">2-2.分類列表：借物 API 文件</a> <a href="https://hackmd.io/jBWDb0OaT_KV-_ducdzqsQ">2-3.分類列表：會議室＆英文課 API 文件</a> <a href="https://hackmd.io/FhZ89ZDxSbOK8oYslEXuCA">3.最新消息 API 文件</a> <a href="https://hackmd.io/SSAxobFGQEC8lyHiu485iQ">4.通知 API 文件</a> <a href="https://hackmd.io/Fz8d0LtbS2iwhuI3QmmzYQ">5.我的 API 文件</a> > [time=Jan 4, 2024] * `更新` Document init > [time=Jul 29, 2024] * `更新` 日期格式統一採用 yyyy/M/d > [time=Jul 31, 2024] * `更新` 設定頁新增accountInfo module * `更新` returnWeekDay由Server端直接回傳中文 > [time=Aug 8, 2024] * `更新` 圖片路徑將不帶入domain，App端將預設domain帶入 > [time=Aug 9, 2024] * `更新` favoriteList與loanList更改type定義＆新增itemGroupId > [time=Aug 14, 2024] * `更新` favorite收藏功能修改，由App實做大部分的工，Server端僅透過minePage.favoriteList回傳 > [time=Nov 4, 2024] * `新增` 所有websocket API皆可額外帶入timeout參數 > [time=Nov 5, 2024] * `更新` accountInfo module 移除 isForceUpdatePassword 欄位，此參數改在handshake時給予 * `更新` loanList module 新增 loanDate 與 loanWeekDate 欄位 > [time=Nov 6, 2024] * `更新` loanList module 移除 isFavorite > [time=Jun 27, 2025] * `更新` 將setting module更名，統一使用mineSetting做all, list & update動作 ---- ::: #### Remark ``` 所有websocket API皆可額外帶入timeout參數做測試用途：參數名稱：timeout 值：0-9 代表延遲回應的秒數，可模擬網路不穩回應變慢的情況 99 代表Server端出現未知的錯誤，可模擬Server端某功能出現異常的情況 ``` ### ❇️ minePage URL: `wss://{domain name}/` Method: `wss` Descirption: `「我的」資訊頁` **Request** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | page | string | Y | 手機畫面名稱 | | module | string | Y | 功能區塊名稱 | | type | string | Y | 資料處理型態 | | data | object | Y | 資料參數 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "page": "minePage", "module": "all", "type": "select", "data": { } } ``` **Response** | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | status | int | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | info | array | Y | 手機畫面資訊 | | module | string | Y | 手機畫面區塊名稱 | | status | int | Y | [狀態代碼](#狀態代碼) | | type | string | Y | 資料處理型態 | | num | int | Y | 資料筆數 | | data | array | Y | 資料內容陣列 | **Response loanList module 我的借用清單** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | functionId | int | Y | 分類列表id （1書籍、3其他設備、5電動、6露營裝備、7桌遊、8其他） | | itemId | int | Y | 書籍/物品id | | loanDate | string | Y | 借用(或預約)起始日期 | | loanWeekDay | string | Y | 借用(或預約)起始日期是星期幾(中文日～六) | | returnDate | string | Y | 歸還日期 | | returnWeekDay| string | Y | 歸還日期是星期幾(中文日～六) | | leftDays | int | Y | 剩餘幾天要歸還 | | loanStatus | int | Y | 借用狀態 1:書籍排隊中 2:書籍/物品借用中 3:物品已預約(時間尚未超過預約起始日) 4:書籍/物品已逾期 5:書籍/物品已歸還 API排序order by loanStatus ASC, updateTime DESC | | title | string | Y | 借用項目標題 | | iconUrl | string | Y | 借用項目圖片連結 | **Response favoriteList module 收藏(我的最愛)清單** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | type | int | Y | 項目型態 1:書籍/物品 [Phase2] 2:活動/意見調查 | | id | int | Y | 如果type == 1 or 2，id代表itemId [Phase2] 若type==2，id代表eventId | | functionId| int | Y | 分類列表id(1~8固定：1書籍、2會議室、3其他設備、4英文課、5電動、6露營裝備、7桌遊、8其他)| | title | string | Y | 借用項目標題(書名/品名/活動名稱) | | subtitle | string | Y | functionId為1＝author(書籍作者)； functionId為3~8＝clubName(物品所屬的社團名稱) | | iconUrl | string | Y | 借用項目圖片連結 | **Response mineSetting module 我的設定** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | isPushNewItem| bool | Y | 是否開啟書籍/物品新上架推播通知(false:不開啟 true:開啟) | | quickEntrance | array | Y | 快速入口功能id (依照分類列表8項功能id) 1:書籍 2:會議室 3:其他設備 4:英文課 5:電玩 6:露營裝備 7:桌遊 8:其他 | mineSetting 執行「設定」動作請參照下方[minePage-mineSetting 設定動作](#❇%EF%B8%8F-minePage-mineSetting-設定動作) **Response accountInfo module 帳號資訊** | Parameter | Type | Require | Description | | --------- | -------| ------- | ----------- | | workNo | string | Y | 員工工號 (Ex:NE097) | | name | string | Y | 員工英文全名 (Ex:Bruce Huang) | | imgUrl | string | Y | 員工照片路徑 | | datetime | string | Y | 資料發佈時間 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "status": 200, "page": "minePage", "info": [ { "module": "loanList", "status": 200, "type":"list", "num": 2, "data": [ { "functionId":1, "itemId":1, "loanDate":"", "loanWeekDay":"", "returnDate":"", "returnWeekDay":"", "leftDays":0, "loanStatus":1, "title":"無腦理財術，小資大翻身！", "iconUrl":"/book/1.png" }, { "functionId":1, "itemId":3, "loanDate":"2024/1/3", "loanWeekDay":"一", "returnDate":"2024/1/13", "returnWeekDay":"三", "leftDays":5, "loanStatus":2, "title":"哈利波特-神秘的魔法石", "iconUrl":"/book/3.png" }, { "functionId":6, "itemId":2, "loanDate":"2024/1/5", "loanWeekDay":"一", "returnDate":"2024/1/19", "returnWeekDay":"三", "leftDays":2, "loanStatus":3, "title":"全自動戶外野營帳篷", "iconUrl":"/item/2.png" }, { "functionId":6, "itemId":5, "loanDate":"2024/1/3", "loanWeekDay":"一", "returnDate":"2024/1/16", "returnWeekDay":"三", "leftDays":-1, "loanStatus":4, "title":"折疊野餐桌", "iconUrl":"/item/5.png" }, { "functionId":6, "itemId":5, "loanDate":"2023/11/12", "loanWeekDay":"一", "returnDate":"2023/11/18", "returnWeekDay":"三", "leftDays":0, "loanStatus":5, "title":"折疊野餐桌", "iconUrl":"/item/5.png" } ], "datetime":"2024/1/17 10:00:01" }, { "module": "favoriteList", "status": 200, "type":"list", "num": 2, "data": [ { "type":1, "functionId":1, "id":1, "title":"無腦理財術，小資大翻身！", "subTitle":"林大維", "iconUrl":"/book/1.png" }, { "type":1, "functionId":6, "id":1, "title":"全自動戶外野營帳篷", "subTitle":"露營社", "iconUrl":"/item/1.png" } ], "datetime":"2024/1/17 10:00:01" }, { "module": "mineSetting", "status": 200, "type":"list", "num": 1, "data": [ { "isPushNewItem":true, "quickEntrance":[7,1,3,6,5,4] } ] }, { "module": "accountInfo", "status": 200, "type": "list", "num": 1, "data": [ { "workNo":"NE097", "name":"Bruce Huang", "imgUrl":"/member/member.jsp?u=7e662482-b98a-4542-811e-8c2e8b88823d" } ], "datetime":"2024/1/17 10:00:01" } ], "datetime": "2023/11/1 12:38:11" } ``` ### ❇️ minePage-favorite URL: `wss://{domain name}/` Method: `wss` Descirption: `「我的」資訊頁-收藏/取消收藏動作` #### Remark ``` 1.收藏有異動時，API僅回傳minePage.favoriteList。 ``` **Request 新增收藏** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | page | string | Y | 手機畫面名稱 | | module | string | Y | 功能區塊名稱 | | type | string | Y | 資料處理型態 | | data | object | Y | 資料參數 | | itemId | int | Y | 書籍/物品id | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "page": "minePage", "module": "favorite", "type": "insert", "data": { "itemId":1 } } ``` **Response 新增收藏** | Parameter | Type | Require | Description | | --------- | -------| ------- | ----------- | | requestId | string | Y | 對話id | | status | number | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | info | string | Y | 手機畫面資訊 | | module | string | Y | 手機畫面區塊名稱 | | status | number | Y | [狀態代碼](#狀態代碼) | | type | string | Y | 資料處理型態 | | num | int | Y | 資料筆數 | | data | array | Y | 資料內容陣列 | | type | int | Y | 項目型態 1:書籍/物品 [Phase2] 2:活動/意見調查 | | functionId | int | Y | 分類列表id （1書籍、3其他設備、5電動、6露營裝備、7桌遊、8其他） | | id | int | Y | 如果type == 1 or 2，id代表itemId [Phase2] 若type==2，id代表eventId | | title | string | Y | 借用項目標題(書名/品名/活動名稱) | | subtitle | string | Y | functionId為1＝author(書籍作者)； functionId為3~8＝clubName(物品所屬的社團名稱) | | iconUrl | string | Y | 借用項目圖片連結 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "status": 200, "page": "minePage", "info": [ { "module": "favoriteList", "status": 200, "type":"add", "num": 1, "data": [ { "type":1, "functionId":1, "id":1, "title":"無腦理財術，小資大翻身！", "subTitle":"林大維", "iconUrl":"/book/1.png" } ], "datetime":"2023/11/1 12:38:11" } ], "datetime": "2023/11/1 12:38:11" } ``` **Request 取消收藏** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | page | string | Y | 手機畫面名稱 | | module | string | Y | 功能區塊名稱 | | type | string | Y | 資料處理型態 | | data | object | Y | 資料參數 | | itemId | int | Y | 書籍/物品id | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "page": "minePage", "module": "favorite", "type": "delete", "data": { "itemId":1 } } ``` **Response 取消收藏** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | status | number | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | info | string | Y | 手機畫面資訊 | | module | string | Y | 手機畫面區塊名稱 | | status | number | Y | [狀態代碼](#狀態代碼) | | type | string | Y | 資料處理型態 | | num | int | Y | 資料筆數 | | data | array | Y | 資料內容陣列 | | type | int | Y | 項目型態 1:書籍/物品 [Phase2] 2:活動/意見調查 | | functionId | int | Y | 分類列表id （1書籍、3其他設備、5電動、6露營裝備、7桌遊、8其他） | | id | int | Y | 如果type == 1 or 2，id代表itemId [Phase2] 若type==2，id代表eventId | | title | string | Y | 借用項目標題(書名/品名/活動名稱) | | subtitle | string | Y | functionId為1＝author(書籍作者)； functionId為3~8＝clubName(物品所屬的社團名稱)| | iconUrl | string | Y | 借用項目圖片連結 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "status": 200, "page": "minePage", "info": [ { "module": "favoriteList", "status": 200, "type":"remove", "num": 1, "data": [ { "type":1, "functionId":1, "id":1, "title":"無腦理財術，小資大翻身！", "subTitle":"林大維", "iconUrl":"/book/1.png" } ], "datetime":"2023/11/1 12:38:11" } ], "datetime": "2023/11/1 12:38:11" } ``` ### ❇️ minePage-mineSetting 設定動作 URL: `wss://{domain name}/` Method: `wss` Descirption: `「我的」資訊頁-設定(新書通知、新活動通知＆快速入口)動作` #### Remark ``` Server端若遇到該使用者是全新無設定資料時，需給予預設值： 1. "isPushNewItem":true 2. "quickEntrance":[1,2,3,4,5,6,7,8] ``` **Request** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | page | string | Y | 手機畫面名稱 | | module | string | Y | 功能區塊名稱 | | type | string | Y | 資料處理型態 | | data | object | Y | 資料參數 | | isPushNewItem| bool | | 是否開啟書籍/物品新上架通知 (false:關閉 true:開啟) | | quickEntrance| array | | 快速入口順序(至少4個，最多8個) 功能id (依照分類列表8項功能id) 1:書籍 2:會議室 3:其他設備 4:英文課 5:電玩 6:露營裝備 7:桌遊 8:其他 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "page": "minePage", "module": "mineSetting", "type": "update", "data": { "isPushNewItem":true, "quickEntrance":[1,2,3,4,5,6,7,8] } } ``` **Response** | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | status | int | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | info | array | Y | 手機畫面資訊 | | module | string | Y |手機畫面區塊名稱 | | status | int | Y | [狀態代碼](#狀態代碼) | | type | string | Y | 資料處理型態 | | num | int | Y | 資料筆數 | | data | array | Y | 資料內容陣列 | | isPushNewItem| bool | | 是否開啟書籍/物品新上架通知 (false:關閉 true:開啟) | | quickEntrance| array | | 快速入口順序(至少4個，最多8個) 功能id (依照分類列表8項功能id) 1:書籍 2:會議室 3:其他設備 4:英文課 5:電玩 6:露營裝備 7:桌遊 8:其他 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "status": 200, "page": "minePage", "info": [ { "module": "mineSetting", "status": 200, "type":"list", "num": 1, "data": [ { "isPushNewItem":true, "quickEntrance":[2,3,5,4] } ], "datetime":"2023/11/1 12:38:11" } ], "datetime": "2023/11/1 12:38:11" } ``` --- <iframe src="https://hackmd.io/zqx1OcNuTKSHCI89YIHMOw?view" width="100%" height="500"></iframe>