---
# System prepended metadata

title: 1.首頁功能相關 API
tags: [NeutecLife App]

---

---
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": {}
}
```

</br>

**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 |  資料內容 |

</br>

**Response topBar module 最上方橫幅：問候語＆~~通知鈴鐺~~**
| Parameter     | Type     | Require | Description |
| ---------     | -------- | ------- | ----------- |
| greetingMsg   | string   | Y       |  問候語字串   |
| ~~noticeBadge~~| ~~int~~      | ~~Y~~       |  ~~未讀通知總數(包含3大類所有的未讀通知總數)~~<br>將由noticePage.unread控制首頁鈴鐺紅點的顯示與否   |

</br>

**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區塊預設底色，在圖片讀取期間顯示  |


</br>

**Response calendarInfo module 活動週曆**
| Parameter | Type     | Require | Description |
| --------- | -------- | ------- | ----------- |
| today     | string   | Y |  今日日期  |
| startDate | string   | Y |  週曆的可視範圍起始日(<b>今天減60天的日期，其當週的週日。</b>Ex:若今天為2024/3/15，往前減去60天是2024/1/15週一，那startDate就會是2024/1/14週日)  |
| endDate   | string   | Y |  週曆的可視範圍結束日(<b>最後一個活動的日期，其當週的週六。</b>Ex:若DB中撈出最後一個活動的日期是2024/4/19週三，那endDate就會是2024/4/22週六)  |

</br>

**Response eventList module 活動卡片列表**
#### Remark
```
第一階段建置期的活動卡片沒有「已報名」、「報名中」等狀態
```
| Parameter | Type     | Require | Description |
| --------- | -------- | ------- | ----------- |
| date      | string   | Y |  活動卡片日期  |
| eventNum  | int      | Y |  該日活動數量  |
| events    | array    | Y |  活動內容陣列  |
| eventId   | int      | Y |  活動id  |
| timeInfo  | string   | Y |  活動時間資訊<br>Ex：<br>12:00<br> 12:00~13:00<br>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"
}
```
</br>

###  ❇️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| | 活動內頁圖片連結<br><font color=red>(沒有值就不出現此欄位)</font>  |
| urlScheme  | string   |        | 前往路徑(與<a href='https://hackmd.io/-A3kGYJ8SHyjegBROlwJow?both#bookDetailPage' target='_blank'>歸還QRCode的urlScheme</a>相同)<br><br>格式：<a href='https://docs.google.com/presentation/d/1YXL1x9r8xbFr3ebq_SUL7N3xycFaYrD00-bGg2HdYbo/edit#slide=id.g33a0ba89a3b_0_163' target='_blank'>各頁面導向文件說明</a><br>neuteclife://[page_name]/[module_name]/[type_name]/[param_1_name]=[param_1_value]&[param_1_name]=[param_1_value]#anchor<br><br>以開啟webView為例：<br>neuteclife://webView/all/select/?url=https%3A%2F%2Fuat-neulife.neutec.com.tw<br><font color=red>(沒有值就不出現此欄位)</font>  |
| datetime  | string   | Y       | 此活動最後更新時間<br><font color=red>不顯示秒，ex:2025/5/29 15:30</font>  |
```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"
 }
```

</br>

#### 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"
}
```
</br>

### ❇️homePage-closeImportantNotice

URL: `wss://{domain name}/`

Method: `wss`

Descirption: `首頁-關閉重要公告動作`

#### Remark
```
此為App端告知Server端此公告已被使用者點選關閉(或下架時間已到App自動觸發此API)，將不再出現（再次開啟App時不會出現此公告於首頁上方）。
```

<br>

**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
  }
}
```

<br>

**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|      | 公告內頁圖片連結<br><font color=red>(沒有值就不出現整個欄位)</font>  |
| group     | string   | Y       | 公告分類 (important / event / personal)  |
| category  | string   | Y       | 公告分類的子分類 (ex:大樓公告)  |
| isNew     | bool      | Y       | 是否為新公告(false:舊公告 true:7日內上架的新公告)  |
| isClosedOnHomePage   | bool      |  Y      | 是否已關閉於首頁最上方區域<br>(false:開啟 true:已關閉)<br><br>執行關閉動作條件有二（任一成立即執行<a href='https://hackmd.io/coOyibBDRYqJpluQIQFYmg?both#homePage-importantNoticeIsClosed' target='_blank'>homePage-importantNoticeIsClosed</a>）：<br>1.現在時間於start_time與end_time區間外<br>2.當使用者按下「Ｘ」按鈕<br><br><font color='red'>只有importantNotice才有此欄位</font> |
| closeInSeconds  | int   |  Y      | 公告將於幾秒後結束<br>Duration.between(now, endTime).getSeconds()<br><br><b>範圍值(0-28800)</b><br><br><font color='red'>只有importantNotice才有此欄位</font> |
| urlScheme  | string   |  Y      | 前往路徑(與<a href='https://hackmd.io/-A3kGYJ8SHyjegBROlwJow?both#bookDetailPage' target='_blank'>歸還QRCode的urlScheme</a>相同)<br><br>格式：<a href='https://docs.google.com/presentation/d/1YXL1x9r8xbFr3ebq_SUL7N3xycFaYrD00-bGg2HdYbo/edit#slide=id.g33a0ba89a3b_0_163' target='_blank'>各頁面導向文件說明</a><br>neuteclife://[page_name]/[module_name]/[type_name]/[param_1_name]=[param_1_value]&[param_1_name]=[param_1_value]#anchor<br><br>前往noticePage並以「個人通知」為優先顯示<br>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"
    }
  ]
}
```

</br>

---

</br>

<iframe src="https://hackmd.io/zqx1OcNuTKSHCI89YIHMOw?view" width="100%" height="500"></iframe>

<!--
### 狀態代碼

| status | description |
| -----  |-------------|
| 200    | Success |
| 1001   | Not found this page or module. |
| 1003   | Not found this DATA. |
| 1004   | DATA parameter error. |
| 1005   | Data processing error. |
| 1006   | 您輸入的帳號或密碼錯誤，請重新輸入 |
| 1008   | Your account has been logged in another device. |
| 1009   | Touch too fast. |
| 1010   | Unknow error. |
| 1011   | 身份驗證失敗，請重新登入 |
| 1012   | Blacklist. |
| 1013   | Not found this lastId. |
| 1014   | 已超過書籍借用2本上限 |
| 1015   | 此書籍正在借閱中，借閱失敗 |
| 1016   | 書籍有人排隊預約，展延失敗 |
| 1017   | 時段衝突，此時段已有人預約 |
| 1018   | 物品已進入借用狀態，無法取消 |
| 1030   | 已有他人在此時段預約\r請重新選擇起訖時間 |
| 1031   | 會議時段衝突\r請重新選擇循環時段 |

<br>

### socket對話資料處理型態
| type   | description |
| -----  |-------------|
| select | App端請求「顯示用」資料。<br>ex:需要顯示書籍列表時。 |
| insert | App端請求「新增」動作。<br>ex:使用者按下借用按鈕時。 |
| update | App端請求「更新」動作。<br>ex:使用者更換快速入口項目時。 |
| delete | App端請求「刪除」動作。<br>ex:使用者按下取消收藏按鈕時。 |
| list   | Server端請求刷新整個區塊資料，或僅告知事件已處理完成。<br>ex:需要顯示書籍列表時。 |
| add    | Server端請求新增資料到區塊中。<br>ex:當後台新增了一筆通知時。 |
| modify | Server端請求更新畫面中的某筆資料。<br>ex:當後台修改了某一筆已發出通知的錯字時。 |
| remove | App端請求「刪除」動作。<br>ex:大樓消防演練通知會在演練結束後自動在App端移除消失。  |


-->