1. 系統定位與技術架構
一套以 PHP + MySQL 建置的 LMS（Learning Management System），專注於程式教學與作答評測。
技術堆疊
- 後端：原生 PHP（無 MVC / 無 Composer）
- 資料庫：MySQL（PDO prepared statements）
- 前端：Bootstrap 5 + Bootstrap Icons + 原生 JS/AJAX
- 程式評測：`includes/Judge.php` + `includes/sandbox_runner.py`
登入與帳號管理
- 支援傳統帳號密碼登入
- 支援 Google OAuth 2.0 一鍵登入／註冊（`auth.php`）
- 可設定僅允許特定 Email 網域（例如學校 @whsh.tc.edu.tw），其他 Google 帳號將被拒絕
- 可獨立控制：是否允許 Google 帳號新建用戶、是否限制網域
- 設定集中於 `teacher/config.php` 的 `auth.google` 與 `registration` 區塊
資料層核心結構
- `courses` → `chapters`（父子層級）
- `chapter_questions` 連接章節與題庫
- `chapter_challenges` 連接章節與程式挑戰
- `quiz_results` / `challenge_submissions` 皆為歷程追加式記錄
2. 角色與功能
系統以 Session 角色（admin / teacher / student）與課程設定共同控制可見範圍。
學生端
- 課程列表瀏覽與自由選課（`index.php` / `enroll.php`）
- 閱讀章節內容、附件下載（`chapter_view.php`）
- 作答填充、單選、多選題（AJAX 寫入 `quiz_results`）
- 章節內可直接做「牛刀小試」程式執行練習（含即時中文錯誤說明）
- 進入程式挑戰，可語法檢查、自訂輸入測試（不計次數），或正式提交批改（`solve_challenge.php`）
- 挑戰頁與章節頁均有浮動「?」說明按鈕，引導學生了解各項功能
教師端
- 建立課程、設定開課日期與選課模式（`teacher/dashboard.php`）
- 章節/小節編輯、排序、複製與附件管理（`teacher/manage_course.php`）
- 管理題庫分類與題目（含牛刀小試）（`teacher/question_bank.php`）
- 建立程式挑戰與測資（`teacher/challenge_bank.php`，目前含 Python/PHP/C/C++）
- 查看學生挑戰狀態矩陣與最近提交程式碼
管理員端
- 系統統計儀表板（使用者、課程、提交數）
- 使用者新增/編修/刪除，CSV 批次匯入學生
- 可直接使用 admin 權限存取所有課程內容
- `admin/settings.php` 目前為預留頁，尚未有可調整項目
3. 主要功能流程
以下是實務上最常用的教學流程與系統行為。
步驟 1：教師建立課程，指定 `public`、`free_enroll` 或 `manual_enroll`，並設定起訖日期。
步驟 2：教師建立章節內容（可父子層級），並綁定「隨堂測驗題」與「程式挑戰」。
步驟 3：學生進入課程時，系統先檢查日期是否開放，再檢查選課資格。
步驟 4：學生在章節頁作答測驗，系統立刻回傳正誤並寫入歷程。
步驟 5：學生在挑戰頁可先用「語法檢查」確認語法，用「測試執行」輸入自訂資料試跑（均不計入提交次數），確認無誤後再「提交批改」。
步驟 6：Judge 逐筆測資比對並記錄結果；若發生 Runtime Error，系統自動附加中文錯誤說明協助除錯。
步驟 7：教師可於課程管理頁查看各學生在各挑戰的最新狀態、作答次數與提交程式碼。
4. 線上評測（Online Judge）說明
評測引擎現已支援 Python、PHP、C、C++、Java，採語言層限制 + OS 層資源限制的雙層保護。
保護機制
- Python：`python3 -I` + `sandbox_runner.py` 攔截危險模組與 `os` 方法
- PHP：`disable_functions` 封鎖外部執行與高風險檔案/網路函式
- OS：`ulimit` + `timeout` 限制 CPU、記憶體與執行時間
常見評測狀態
accepted wrong_answer runtime_error time_limit_exceeded security_violation（保留）每次提交都寫入 `challenge_submissions`，包含通過測資數、總測資數與實際輸出。
中文錯誤說明系統（`assets/js/error-hints.js`）
- Runtime Error 發生時自動顯示藍色「💡 錯誤說明」區塊
- 覆蓋 Python / C / C++ / Java / PHP 數十種常見例外
- Python 3.10+ 支援「Did you mean: 'xxx'?」拼字建議綠色高亮
- 共用於 `solve_challenge.php`（提交/語法檢查/測試執行）與 `chapter_view.php`（牛刀小試）
挑戰頁工具列
- 語法檢查：靜態分析語法，錯誤標記至編輯器行號，不計提交次數
- 測試執行：自訂 stdin 試跑程式，不計提交次數、老師不可見
- 提交批改：跑所有測資（含隱藏），計次、老師可見提交紀錄
- 浮動 ? 按鈕：左下角即時開啟功能說明 Modal
5. 功能地圖（頁面對照）
便於維護與功能擴充時快速定位程式檔案。
| 功能區 | 主要檔案 | 說明 |
|---|---|---|
| 首頁與課程 | index.php / course_view.php |
課程列表、可否進入、課程章節樹與挑戰進度總覽 |
| 章節學習 | chapter_view.php |
章節內容、附件、隨堂測驗、章節挑戰入口、牛刀小試（含中文錯誤說明）、浮動 ? 說明按鈕 |
| 中文錯誤說明 | assets/js/error-hints.js |
共用模組；覆蓋 Python/C/C++/Java/PHP 常見錯誤，支援 Python 拼字建議 |
| 挑戰作答 | solve_challenge.php |
Ace editor、測資說明、語法檢查、自訂輸入測試執行、提交批改、中文錯誤說明、浮動 ? 說明按鈕 |
| 教師課程管理 | teacher/manage_course.php |
章節 CRUD、附件管理、課程設定、進度矩陣 |
| 題庫管理 | teacher/question_bank.php |
分類與多題型題目管理（填充/單選/多選） |
| 挑戰庫管理 | teacher/challenge_bank.php / teacher/edit_challenge.php |
程式挑戰與公開/隱藏測資管理 |
| 管理員 | admin/dashboard.php / admin/manage_users.php |
系統統計、帳號權限管理、CSV 匯入 |
6. 現況限制與維護重點
以下項目是維運與後續開發時最需要先確認的地方。
資料庫結構一致性
schema.md與init.php目前存在欄位/資料表落差。- 例如：`question_categories`、`chapter_attachments` 與 `question_bank` 新欄位需確認已建好。
- 新環境部署建議：初始化後立刻執行補充 migration。
安全與設定
- DB 帳密目前寫在 `includes/db.php`。
- 上傳路徑與 URL 前綴在 `teacher/config.php`（含 base path）。
- Judge 已有基本沙箱，但非完整容器隔離，需持續強化。