# 🗓️ ncku Moodle Calendar

> [!Caution]
> 本專案基於大神[nyraa](https://github.com/ncchen99/NCKU-Evaluator) ，並非我做的，只是參考並把內容說明優化而已

## ✨功能與特色
- **⚙️ 自動同步**：將 Moodle 作業行事曆自動同步至您的 Google 日曆。
- **🎨狀態顏色標示**：在 Google 日曆中，透過顏色直觀地了解作業狀態。
- 🟩 **綠色**: 已繳交
- 🟨 **黃色**: 未繳交
- 🟥 **紅色**: 已逾期

- **📧郵件通知**：
- 當有新作業時，自動發送 Email 通知。
- 當作業的截止日期或內容更新時，自動發送 Email 通知。

- **🔐 安全憑證管理**：
- 腳本會自動儲存並更新 Moodle Token（有效期限約3個月），避免重複登入。
- 您可以選擇性地儲存 Moodle 帳號密碼，以便在 Token 過期後自動重新獲取。

## 🎯 使用方法

請依照以下步驟完成設定。

#### 1️⃣ 步驟一：建立專案副本
1. 在瀏覽器中登入您的 Google 帳號。
2. 點擊此連結前往 Google Apps Script 專案：[NCKU Moodle Calendar Prototype](https://script.google.com/d/1u1hWVz9TYh-ktlUT6_OQWr3gTMI2Kk2fBL99skcLRdDCqOVD-r_iQ5yW/edit)。
3. 先在左方點選**總覽**並在你的 Google 帳號下**建立一份複本**(圈起來的問號下方 星號左方)
4. 點擊「建立複本」按鈕，將專案複製到您自己的雲端硬碟中。

#### 2️⃣ 步驟二：設定腳本屬性
1. 在您複製的專案中，點擊左方選單的「專案設定」（齒輪圖示）。
2. 在「指令碼屬性」區塊，點擊「新增指令碼屬性」。
3. 新增以下兩個屬性，並填入您的 Moodle 帳號與密碼：
- **屬性**: `moodleid`
**值**: `你的Moodle學號`
- **屬性**: `moodlekey`
**值**: `你的Moodle密碼`

#### 3️⃣ 步驟三：初始化專案
1. 點擊左方選單的「編輯器」（`<>` 圖示）。
2. 在檔案清單中，選擇 `Initialize.gs` 檔案。
3. 在上方工具列中，確認函式選擇框為 `initialize`，然後點擊「執行」。
4. 首次執行時，會彈出「需要授權」視窗，請依照指示完成授權，允許腳本存取您的 Google 日曆與Email。
5. 執行成功後，腳本會在您的 Google 日曆中建立一個名為 `Moodle Calendar` 的新日曆，並將 Moodle 作業同步進去。

:::warning
在 `Main.gs` 檔案中，
**第19行**有一個`for(let i = -6; i < 6; ++i)`意思是處理範圍從前6個月到後6個月
如果只想要看未來的可以把i = -6改成i = 0，`for(let i = 0; i < 6; ++i)`代表只從現在開始查詢
:::

#### 4️⃣ 步驟四：設定自動觸發器
1. 點擊左方選單的「觸發條件」（時鐘圖示）。
2. 點擊右下角的「新增觸發條件」。
3. 依照以下設定建立觸發器：
- **要執行的功能選擇**: `main`
- **選取活動來源**: `時間驅動`
- **選取時間型根據的觸發條件類型**: `小時計時器`
- **選取小時間隔**: `每 6 小時` 或 `每 8 小時`
4. 點擊「儲存」。此後，腳本將會依您設定的間隔自動執行同步。

#### 5️⃣ 步驟五：（選擇性）密碼
為了安全起見，您可以在初始化完成後，回到「專案設定」頁面，刪除 `moodleid` 和 `moodlekey` 這兩個屬性。腳本會依賴已獲取的 `wstoken` 運作。當 `wstoken` 未來失效時，您只需重新加入這兩個屬性並手動執行一次 `main` 函式即可。

## ⚠️ 重要注意事項
- **執行頻率**：請勿將觸發條件的間隔設定得太短（例如每小時），以免對 Moodle 伺服器造成不必要的負擔。
- **日曆管理**：請勿在程式自動建立的 `Moodle Calendar` 日曆中手動新增或修改活動，因為在同步過程中，任何非由腳本管理的事件都可能被清除。
- **執行者**：授權及設定觸發條件的 Google 帳號將是此專案的**執行者**。日曆會建立在執行者的帳號下，通知 Email 也會寄送至執行者的信箱。

## 權限說明
此專案需要以下 Google 權限：
| 權限 | 用途 |
| ---------------------------------------------------------------- | -------------------------------- |
| `查看、編輯、分享和永久刪除您可以使用 Google 日曆存取的所有日曆` | 同步作業活動到 Google 行事曆。 |
| `連線到外部服務` | 從 Moodle 伺服器取得資料。 |
| `以您的身分傳送電子郵件` | 傳送新作業或更新的 Email 通知。 |

## 通知設定
您可以直接修改 `Main.gs` 檔案來開關 Email 通知功能。
| 設定名稱 | 預設值 | 功能 |
|----------|--------|------|
| `enableNewEventNotify` | `true` | 當有新的作業時傳送通知。 |
| `enableEditEventNotify` | `true` | 當作業截止日期或內容變更時傳送通知。 |

## 故障排除

#### Exception: You have been creating or deleting too many calendars or calendar events in a short time.
- **原因**：這是最常見的錯誤。由於您在短時間內（尤其首次執行時）建立或更新了大量日曆事件，觸發了 Google 的 API 頻率限制。
- **解決方案**：此問題已在最新版本的程式碼中透過加入延遲 (`Utilities.sleep(1000)`) 來解決。如果您是從舊版本更新，請確保在建立、更新、刪除事件的迴圈中有加入延遲。

#### Exception: Address unavailable... / Request failed returned code 503...
- **原因**：從 Moodle 取得資料時發生網路問題或 Moodle 伺服器暫時不穩定。
- **解決方案**：此為暫時性問題，如果沒有持續發生，可以忽略。腳本會在下次觸發時重試。

#### 無效的通行證 -- 找不到通行憑證
- **原因**：Moodle Token (`wstoken`) 已失效，且您已移除 `moodleid` 和 `moodlekey`。
- **解決方案**：請回到「專案設定」中重新加入 `moodleid` 和 `moodlekey` 屬性，然後手動執行一次 `main` 函式以取得新的 Token。

#### Login failed
- **原因**：您在「指令碼屬性」中填寫的 Moodle 帳號或密碼不正確。
- **解決方案**：請仔細檢查帳號密碼是否拼寫正確。