系統架構

架構一覽

NTPU AI Learn 把系統分成兩條路徑：閱讀公開內容時，瀏覽器直接取得建置時預先產生的網頁；需要信任的操作，例如送出評量、同步進度、登入或使用教師與管理功能，則交給 Worker API 驗證、授權後再讀寫資料庫。

• 了解系統 Understand從全貌開始，理解系統邊界與關係
• 建構系統 Build深入結構，掌握 Container 與元件
• 維運系統 Operate掌握部署、運作與失效行為

讀取路徑不需要登入、不呼叫 API，也不碰資料庫，所以公開內容快速、可被搜尋引擎索引。互動路徑則是唯一能讀寫學習資料的地方，每個請求都在 Worker 裡驗證與授權。評量答案與教師專用內容只存在伺服器端，從不出現在公開路徑上。

有些互動操作除了通過驗證與授權的請求之外，還需要更多條件。像結業證書或能力證書這類項目，在核發之前，Worker 會另外執行伺服器端的資格規則，檢查真實的證據（例如已完成的課程單元與通過的評量，或教師對提交內容審閱後判定通過）才會核發，絕不會只因為送出了表單就自動取得。

系統情境 System Context

這張圖聚焦一件事：誰在使用 NTPU AI Learn，以及平台與外部世界如何互動。

讓第一次接觸這個平台的人，也能快速理解系統邊界與整體脈絡。

Container 架構

這張圖把 System Context 裡「NTPU AI Learn」這一整個方塊，攤開成實際部署與執行的技術元件，回答的問題是：主要的執行與資料元件有哪些、各自負責什麼、彼此怎麼溝通。

一次操作如何在系統中流動

以下是兩個實際的例子：一個只讀取公開內容，一個需要伺服器評分並寫入資料。

1. 1瀏覽器請求頁面
   例如 /courses/… 之下的單元網址。
2. 2Worker 處理網址
   舊網址在這一步直接永久轉址；每個回應都加上安全標頭。
3. 3回傳預先產生的網頁
   從 Static Assets 取得建置時產生的完整 HTML、CSS 與 JS。不呼叫 API、不讀取資料庫、不需要登入。
4. 4瀏覽器顯示並接手互動
   內容立即可讀；JavaScript 載入後才加上語言切換、自我檢測與「標記為完成」等互動，進度預設只存在這個瀏覽器。

1. 1開始作答
   瀏覽器以 POST 呼叫 /api/ 之下的評量 API，送出場次代碼與學員代碼（不需要登入）。Worker 驗證格式、確認場次開放中，在 D1 建立一筆作答紀錄，回傳不含答案的題目。
2. 2送出答案
   作答完成後，瀏覽器再以 POST 送出每一題選擇的選項。
3. 3結構驗證
   Worker 先以結構描述檢查請求內容，格式不符的請求直接被拒絕。
4. 4確認作答與場次
   找到這次作答並確認場次仍開放中。已經送出過的作答直接回傳原本的結果，不會重新評分。啟用機器人驗證時，也在這一步由伺服器端核對。
5. 5伺服器端評分
   確認每一題都已作答、題目都存在後，以只存在伺服器端的答案計分，並整理各能力面向的表現。
6. 6寫入 D1
   分數與每一題的作答以參數綁定的查詢寫入資料庫。
7. 7回傳結果並更新進度
   回應包含分數與能力分析（後測另附自己的前測分數）。頁面顯示結果，並在瀏覽器的進度中把這項評量標記為完成。

元件

設計原則

上面的技術選擇背後，是這六個在程式與建置流程中實際執行的原則；下表列出每個原則為什麼重要、它帶來什麼影響，以及採用它必須付出的取捨。

品質屬性 Quality Attributes

以下用具體情境，而不是抽象的形容詞，說明平台在幾個品質面向上實際的行為；每一項都能對照程式或測試驗證，這裡不列出任何未經量測的數字目標。

1. 1無障礙（Accessibility）
   就算瀏覽器的 JavaScript 執行失敗，公開課程內容仍然完整可讀，因為它本來就是建置時就產生好的 HTML（見「漸進增強」原則）。
2. 2安全（Security）
   修改瀏覽器裡的程式碼，不能讓學員改變具有權威性的授權判斷或評量分數；這些判斷只在 Worker 裡決定，見「信任邊界」一節。
3. 3隱私（Privacy）
   公開頁面與前端程式包不會包含受保護的評量答案、教師專用備註或不必要的使用者資料；每次建置都會掃描所有公開輸出檔案，一旦偵測到外洩就讓建置失敗。
4. 4可靠性（Reliability）
   資料庫無法使用時，已經預先產生的公開學習內容仍然可以透過 Static Assets 提供；只有需要讀寫資料庫的互動功能（例如送出評量）會受影響，見下方「失效與降級」一節。
5. 5可維護性（Maintainability）
   網址、路由與資料庫結構的變更都在版本控制中審查；一份路由表同時產生前端路由、轉址、404 與 sitemap，避免正式行為與文件各自對不上。
6. 6可重現性（Reproducibility）
   只要有相同的原始碼版本與支援的工具鏈，維護者就能重新建置整個公開網站，並依序套用版本化的資料庫 migration 重建資料庫結構。
7. 7國際化（Internationalization）
   切換語言時會停留在同一個邏輯頁面；因為兩種語言的課程、文件與測驗共用同一組穩定 ID，自動化測試會檢查兩邊的章節結構、連結與 ID 是否一致。

內容與資料

「內容」和「使用者資料」是兩件不同的事，分開存放、分開管理。修改課程文字不會動到任何學員資料，學員的操作也不會寫回內容。

瀏覽器本機的學習進度是第三種：它只存在你的裝置上，除非你選擇同步到課程場次。

• 進度如何運作

課後回饋的元件

課後回饋由前端表單、四組 Worker API、D1 資料表、排程與郵件寄送組成，全部沿用既有的信任邊界：授權、遮罩、門檻與稽核都在 Worker 中完成。

信任邊界

• 安全概覽

部署 Deployment

NTPU AI Learn 分為三個部署環境，各自承擔不同階段的開發與發布工作。

Production 與 Staging 使用彼此獨立的部署與資料環境；本機開發則使用本機模擬資源，不會直接操作正式環境的資料。

失效與降級 Failure & Degradation

以下只涵蓋已經可以在架構與程式行為中驗證的情境；存放庫裡目前沒有找到 migration 失敗，或身分驗證服務本身降級時的正式回滾與事故處理程序文件，所以這裡不列出未經驗證的處理步驟。

1. 1靜態內容可用、Worker API 無法使用
   公開課程內容持續可以透過 Static Assets 閱讀，不受影響；需要 Worker 的互動操作（登入、送出評量、同步進度等）會失敗，並顯示明確的錯誤，而不是假裝成功。
2. 2Worker API 可用、D1 資料庫無法使用
   公開內容不受影響，因為它由 Static Assets 提供，不會讀取資料庫；需要讀寫資料庫的互動操作會失敗，不會回傳假的成功結果。
3. 3Worker API 可用、R2 檔案儲存無法使用
   公開內容與其他不涉及檔案的互動操作不受影響；認證佐證檔案的上傳與下載、教師投影片匯出檔的下載會失敗並顯示明確的錯誤，不會回傳假的成功結果。
4. 4JavaScript 無法執行
   公開課程內容仍然可讀，因為它是建置時就產生好的 HTML；只有 React 載入後才加上的互動（例如語言切換、自我檢測、標記完成）無法使用。

網址與語言

平台只有一份路由表：前端路由、Worker 的轉址與 404、預先產生的頁面與 sitemap 都從同一份定義產生。路由表也把每個網址分成三類：公開內容（預先產生、可被索引）、公開的互動流程（不預先產生、不被索引），以及需要授權的受保護頁面。

語言由網址決定，切換語言時會停留在同一個邏輯頁面；因為兩種語言共用同一組 ID，進度與連結不會因切換語言而失效。

• 雙語設計

架構決策 Architecture Decisions

重要的架構決策會以 Architecture Decision Record（ADR）記錄，包含決策背景、採用方案與後續影響。

ADR 屬於存放庫內的工程文件，供需要進一步理解實作或參與開發時查閱。

相關文件

• 安全概覽：伺服器端授權、評分與輸入輸出處理
• 隱私：哪些資料留在瀏覽器、哪些會送到伺服器
• 角色與權限：學員、教師與管理員各自能做什麼
• 雙語設計：網址、穩定 ID 與內容一致性