1.首頁功能相關 API

--- tags: NeutecLife App --- # 1.首頁功能相關 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=Jun 12, 2024] * `更新` 統一型態：不使用0與1代表Bool，將number修正為int型態 > [time=Nov 4, 2024] * `新增` 所有websocket API皆可額外帶入timeout參數 > [time=Jan 23, 2025] * `更新` homePage.promoteBanner增加defBgColor，用來提前顯示的預設背景色 > [time=Feb 25, 2025] * `更新` importantNoticeIsClosed更名為closeImportantNotice * `更新` closeImportantNotice的type改用update (原為delete) * `更新` 移除importantNotice module，因為與noticePage的importantNotice性質相同 > [time=Mar 11, 2025] * `更新` promoteBannedId更名為eventId，在第一階段中，首頁Banner合併於行事曆卡片功能之中 > [time=Mar 12, 2025] * `更新` homePage.closeImportant的response改成只需要回應noticePage.importantNotice * `更新` closeInSeconds欄位增加範圍值設定，0-28800 > [time=Apr 15, 2025] * `更新` eventList module移除urlScheme欄位 * `更新` promoteBanner module移除style欄位 * `更新` promoteBanner module的imgUrl欄位更改為optional型態 > [time=Apr 29, 2025] * `更新` homePage移除quickEntrance module，改由minePage取得(因為homePage與minePage都會在同一時間獲取資料) * `更新` homePage.promoteBanner去除imgUrl欄位，就只有背景圖與文字，不採用兩張圖片疊加的方式 * > [time=May 29, 2025] * `更新` eventDetailPage.eventContent中的datetime(用於最後更新時間顯示的欄位)，不顯示秒。ex:2025/5/29 13:30 * > [time=Aug 26, 2025] * `更新` 移除homePage中selectedDate參數，由Server端直接控制給予當日資料 * > [time=Sep 3, 2025] * `更新` 補上查無此活動案例 * > [time=Dec 24, 2025] * `更新` 補上訂閱機制的案例 ---- ::: #### Remark ``` 所有websocket API皆可額外帶入timeout參數做測試用途：參數名稱：timeout 值：0-9 代表延遲回應的秒數，可模擬網路不穩回應變慢的情況 99 代表Server端出現未知的錯誤，可模擬Server端某功能出現異常的情況 ``` ## 1. 首頁功能相關 API ### ❇️homePage URL: `wss://{domain name}/` Method: `wss` Descirption: `首頁資訊` #### Remark ``` ``` **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": "homePage", "module": "all", "type": "select", "data": {} } ``` **Response** | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | status | int | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | info | string | Y | 手機畫面資訊 | | module | string | Y | 手機畫面區塊名稱 | | status | int | Y | [狀態代碼](#狀態代碼) | | type | string | Y | 資料處理型態 | | num | int | Y | 資料筆數 | | data | array | Y | 資料內容 | **Response topBar module 最上方橫幅：問候語＆~~通知鈴鐺~~** | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | greetingMsg | string | Y | 問候語字串 | | ~~noticeBadge~~| ~~int~~ | ~~Y~~ | ~~未讀通知總數(包含3大類所有的未讀通知總數)~~ 將由noticePage.unread控制首頁鈴鐺紅點的顯示與否 | **Response promoteBanner module 首頁推廣Banner** ``` 1. 在第一階段中，首頁推廣Banner為行事曆卡片內容的延伸，因此點擊Banner與點擊卡片都將前往活動內容頁(eventDetailPage)。 2. bgUrl一定會有，不論後台設定為「單一圖檔」或「固定版位」。單一圖檔：只有一張圖，沒有文字與文字色碼。固定版位：有一張圖，也有主標文字＋色碼＆副標文字＋色碼。 ``` | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | eventId | int | Y | 行事曆卡片id | | bgUrl | string | Y | Banner背景圖路徑 | | title | string | | Banner主標文字 | | titleColor| string | | Banner主標文字顏色色碼 | | subTitle | string | | Banner副標文字 | | subTitleColor| string| | Banner副標文字顏色色碼 | | defBgColor| string | Y | Banner區塊預設底色，在圖片讀取期間顯示 | **Response calendarInfo module 活動週曆** | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | today | string | Y | 今日日期 | | startDate | string | Y | 週曆的可視範圍起始日(今天減60天的日期，其當週的週日。Ex:若今天為2024/3/15，往前減去60天是2024/1/15週一，那startDate就會是2024/1/14週日) | | endDate | string | Y | 週曆的可視範圍結束日(最後一個活動的日期，其當週的週六。Ex:若DB中撈出最後一個活動的日期是2024/4/19週三，那endDate就會是2024/4/22週六) | **Response eventList module 活動卡片列表** #### Remark ``` 第一階段建置期的活動卡片沒有「已報名」、「報名中」等狀態 ``` | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | date | string | Y | 活動卡片日期 | | eventNum | int | Y | 該日活動數量 | | events | array | Y | 活動內容陣列 | | eventId | int | Y | 活動id | | timeInfo | string | Y | 活動時間資訊 Ex： 12:00 12:00~13:00 12:30集合、12:40準時發車 | | title | string | Y | 活動標題 | | iconUrl | string | Y | 活動左側icon連結 | ```json= { "requestId": "1fb7d801-4a05-0b1d-ea16-de1d32c97d6c", "status": 200, "page": "homePage", "info": [ { "module": "topBar", "status": 200, "type": "list", "num": 1, "data": [ { "greetingMsg" : "早安，您好！", } ], "datetime": "2023/11/1 07:10:13" }, { "module": "promoteBanner", "status": 200, "type": "list", "num": 5, "data": [ { "eventId": 1, "bgUrl": "/images/promote_banner/style_1_bg.png", "title": "泰拳比賽賽前訓練營報名活動", "titleColor": "#FFFFFF", "subTitle": "泰強了～", "subTitleColor": "#E8E8E8", "defBgColor": "#FFFFFF", "datetime": "2023/11/1 12:38:11" }, { "eventId": 2, "bgUrl": "/images/promote_banner/style_2_bg.png", "title": "熱舞社舞林大道活動報名開始", "titleColor": "#000000", "subTitle": "愛你呦～", "subTitleColor": "#747474", "defBgColor": "#FFFFFF", "datetime": "2023/11/1 12:38:11" }, { "eventId": 3, "bgUrl": "/images/promote_banner/banner_3.png", "title": "", "titleColor": "", "subTitle": "", "subTitleColor": "", "defBgColor": "#FFFFFF", "datetime": "2023/11/1 12:38:11" }, { "eventId": 4, "bgUrl": "/images/promote_banner/style_1_bg.png", "title": "吉他社溫情音樂會", "titleColor": "#FFFFFF", "subTitle": "吉他溫情暖心扉", "subTitleColor": "#E8E8E8", "defBgColor": "#FFFFFF", "datetime": "2023/11/1 12:38:11" }, { "eventId": 5, "bgUrl": "/images/promote_banner/style_2_bg.png", "title": "籃球社日新盃年度大賽報名開始", "titleColor": "#000000", "subTitle": "等你來挑戰", "subTitleColor": "#747474", "defBgColor": "#FFFFFF", "datetime": "2023/11/1 12:38:11" } ], "datetime": "2023/11/1 07:10:13" }, { "module": "calendarInfo", "status": 200, "type":"list", "num": 1, "data": [ { "today":"2024/1/17", "startDate":"2024/1/16", "endDate":"2024/4/20" } ], "datetime": "2023/11/1 07:10:13" }, { "module": "eventList", "status": 200, "type":"list", "num": 2, "data": [ { "date":"2024/1/17", "eventNum":2, "events":[ { "eventId":1, "timeInfo":"12:00", "title":"5月按摩開放預約", "iconUrl":"/images/event/1.png" }, { "eventId":2, "timeInfo":"14:00-15:00", "title":"提拉皮斯初階課", "iconUrl":"/images/event/2.png" }, ] }, { "date":"2024/1/18", "eventNum":1, "events":[ { "eventId":3, "timeInfo":"14:00-15:30", "title":"名人講座", "iconUrl":"/images/event/3.png" }, ] } ], "datetime": "2023/11/1 07:10:13" } ], "datetime": "2023/11/17 12:38:11" } ``` ### ❇️eventDetailPage URL: `wss://{domain name}/` Method: `wss` Descirption: `首頁-行事曆卡片內容頁(第一階段專用)，點選行事曆卡片後進入的內容頁` #### Remark ``` 此為第一階段暫時性公能。第二階段將由「最新消息(活動功能)」取代此頁。 ``` **Request** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | page | string | Y | 手機畫面名稱 | | module | string | Y | 功能區塊名稱 | | type | string | Y | 資料處理型態 | | data | object | Y | 資料參數 | | eventId | int | Y | 活動id | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "page": "eventDetailPage", "module": "all", "type": "select", "data": { "eventId":1 } } ``` **Response** | Parameter | Type | Require | Description | | ----------| ------ | ------- | ----------- | | requestId | string | Y | 對話id | | status | int | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | info | string | Y | 手機畫面資訊 | | module | string | Y |手機畫面區塊名稱 | | status | int | Y | [狀態代碼](#狀態代碼) | | type | string | Y | 資料處理型態 | | num | int | Y | 資料筆數 | | data | array | Y | 資料內容陣列 | | eventId | string | Y | 活動id | | date | string | Y | 活動日期 | | title | string | Y | 活動標題 | | content | string | Y | 活動內容 | | contentImgUrl| string| | 活動內頁圖片連結 (沒有值就不出現此欄位) | | urlScheme | string | | 前往路徑(與<a href='https://hackmd.io/-A3kGYJ8SHyjegBROlwJow?both#bookDetailPage' target='_blank'>歸還QRCode的urlScheme</a>相同) 格式：<a href='https://docs.google.com/presentation/d/1YXL1x9r8xbFr3ebq_SUL7N3xycFaYrD00-bGg2HdYbo/edit#slide=id.g33a0ba89a3b_0_163' target='_blank'>各頁面導向文件說明</a> neuteclife://[page_name]/[module_name]/[type_name]/[param_1_name]=[param_1_value]&[param_1_name]=[param_1_value]#anchor 以開啟webView為例： neuteclife://webView/all/select/?url=https%3A%2F%2Fuat-neulife.neutec.com.tw (沒有值就不出現此欄位) | | datetime | string | Y | 此活動最後更新時間 不顯示秒，ex:2025/5/29 15:30 | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "status": 200, "page": "eventDetailPage", "info": [ { "module": "eventContent", "status": 200, "type": "list", "num": 1, "data": [ { "eventId": 12, "date": "2024/1/6", "title": "一月份慶生會", "content": "2024 年 1 月慶生會 Birthday Party\r\r將於本週三 (6/5) 15:45 下午茶時間舉辦，敬邀所有同仁一同享用！\r\r下午茶：一沐日手搖飲 #一人一杯\r\r本次慶生會負責福委：Claire Chien", "contentImgUrl": "/images/event/12.jpg", "urlScheme": "neuteclife://webView/all/select/?url=https%3A%2F%2Fuat-neulife.neutec.com.tw", "datetime": "2023/11/1 07:10", } ], "datetime": "2023/11/1 07:10:13" } ], "datetime": "2023/11/1 12:38:11" } ``` #### Response for 失敗(卡片內容被刪除或下架) | Parameter | Type | Require | Description | | ----------| -------| ------- | ----------- | | requestId | string | Y | 對話id | | status | int | Y | [狀態代碼](#狀態代碼) | | page | string | Y | 手機畫面名稱 | | errorMsg | string | Y | 錯誤訊息 | | datetime | string | Y | 資料回應時間 | <img src="https://hackmd.io/_uploads/BkGqYWOXel.png" width="250" /> ```json= { "requestId": "1fb7d801-4a05-0b1d-ea16-de1d32c97d6c", "status": 200, "page": "eventDetailPage", "info": [ { "module": "eventContent", "status": 1051, "errorMsg": "查無此活動", "detetime": "2025/8/13 12:38:11" } ], "datetime": "2025/8/13 12:38:11" } ``` ### ❇️homePage-closeImportantNotice URL: `wss://{domain name}/` Method: `wss` Descirption: `首頁-關閉重要公告動作` #### Remark ``` 此為App端告知Server端此公告已被使用者點選關閉(或下架時間已到App自動觸發此API)，將不再出現（再次開啟App時不會出現此公告於首頁上方）。 ``` **Request** | Parameter | Type | Require | Description | | ----------- | -------- | ------- | ----------- | | requestId | string | Y | 對話id | | page | string | Y | 手機畫面名稱 | | module | string | Y | 功能區塊名稱 | | type | string | Y | 資料處理型態 | | data | object | Y | 資料參數 | | noticeId | int | Y | 公告id | ```json= { "requestId": "64d94767-c926-6156-44a5-8bf08a3691d4", "page": "homePage", "module": "closeImportantNotice", "type": "update", "data": { "noticeId":1 } } ``` **Response** ``` Response只需要回應noticePage.importantNotice，以modify的方式通知App端該筆資料已被使用者關閉(或下架時間已到App自動觸發此API)於首頁上方。 ``` | Parameter | Type | Require | Description | | --------- | -------- | ------- | ----------- | | noticeId | int | Y | 公告id | | iconUrl | string | Y | 列表左側icon圖片url | | title | string | Y | 公告標題 | | content | string | Y | 公告內容 | | contentImgUrl| string| | 公告內頁圖片連結 (沒有值就不出現整個欄位) | | group | string | Y | 公告分類 (important / event / personal) | | category | string | Y | 公告分類的子分類 (ex:大樓公告) | | isNew | bool | Y | 是否為新公告(false:舊公告 true:7日內上架的新公告) | | isClosedOnHomePage | bool | Y | 是否已關閉於首頁最上方區域 (false:開啟 true:已關閉) 執行關閉動作條件有二（任一成立即執行<a href='https://hackmd.io/coOyibBDRYqJpluQIQFYmg?both#homePage-importantNoticeIsClosed' target='_blank'>homePage-importantNoticeIsClosed</a>）： 1.現在時間於start_time與end_time區間外 2.當使用者按下「Ｘ」按鈕 只有importantNotice才有此欄位 | | closeInSeconds | int | Y | 公告將於幾秒後結束 Duration.between(now, endTime).getSeconds() 範圍值(0-28800) 只有importantNotice才有此欄位 | | urlScheme | string | Y | 前往路徑(與<a href='https://hackmd.io/-A3kGYJ8SHyjegBROlwJow?both#bookDetailPage' target='_blank'>歸還QRCode的urlScheme</a>相同) 格式：<a href='https://docs.google.com/presentation/d/1YXL1x9r8xbFr3ebq_SUL7N3xycFaYrD00-bGg2HdYbo/edit#slide=id.g33a0ba89a3b_0_163' target='_blank'>各頁面導向文件說明</a> neuteclife://[page_name]/[module_name]/[type_name]/[param_1_name]=[param_1_value]&[param_1_name]=[param_1_value]#anchor 前往noticePage並以「個人通知」為優先顯示 neuteclife://noticePage/all/select/#personal | | datetime | string | Y | 此公告最後更新時間 | ```json= { "requestId": "1fb7d801-4a05-0b1d-ea16-de1d32c97d6c", "status": 200, "page": "noticePage", "info": [ { "module": "importantNotice", "status": 200, "type": "modify", "num": 1, "data": [ { "noticeId": 1, "iconUrl": "/images/notice/icon_important.png", "title": "今日中午餐廳備有萬聖節大餐，敬請共襄盛舉！", "content": "今日中午餐廳備有萬聖節大餐，敬請共襄盛舉！\r知菜單請點擊下方「查看詳情」。", "contentImgUrl":"/images/notice/content_image_url_1.png", "group": "important", "category": "重要公告", "isNew": true, "isClosedOnHomePage": true, "closeInSeconds": 2198, "urlScheme": "neuteclife://webview/all/select/?url=https%3A%2F%2Fuat-neulife.neutec.com.tw%2Fguest%2Fevents%2Fevent.jsp%3Fid%3D1", "datetime": "2024/12/30 11:02:28" } ], "datetime": "2024/12/30 11:02:28" } ] } ``` --- <iframe src="https://hackmd.io/zqx1OcNuTKSHCI89YIHMOw?view" width="100%" height="500"></iframe>