筆記評分系統使用說明

此專案是以 FastAPI + Jinja2 + SQLite 實作的「多週次筆記評分系統」，提供：

• 學生作業資料夾匯入
• 助教雙人評分（每份作業最多 2 位 TA）
• 教授覆寫最終分數
• 成績匯出 CSV
• 週次資料隔離與跨週統計

1. 系統需求

• Python 3.10+（建議 3.11）
• macOS / Linux / Windows 皆可

2. 安裝與啟動

2.1 建立虛擬環境（建議）

python -m venv .venv
source .venv/bin/activate

若你使用 conda，也可改用：

conda create -n note-grader python=3.11 -y
conda activate note-grader

2.2 安裝套件

pip install -r requirements.txt

2.3 啟動服務

python app.py

預設網址：

• http://127.0.0.1:5000

3. 首次啟動會發生的事

系統會自動建立：

• week_dbs/：每週一個 SQLite，格式為 weekNN.db
• uploads/：上傳檔案資料夾
• static/：靜態檔案資料夾（若不存在會自動建立）

並在每個週次資料庫自動初始化：

• 助教（TA）與教授名單

若某週次尚未有人員資料，系統會先建立預設名單。你可以再到「人員管理」頁統一修改。

預設名單為中性名稱：

• 助教：TA1, TA2, TA3
• 教授：Professor

4. 使用流程（建議順序）

4.1 選擇週次

• 在頁面上方導覽列的「週次」輸入 week01、week02 等
• 按 Enter 後，所有頁面操作都會帶著 ?week=weekNN

4.2 匯入學生檔案

1. 進入「匯入檔案」頁
2. 選擇資料夾上傳（支援多個資料夾）
3. 系統會自動嘗試解析學號與姓名

命名建議格式：

• 學號_姓名/檔案.pdf（例如：student001_demo/note.pdf）
• 學號_姓名.pdf（例如：student001_demo.pdf）
• 學號-姓名 或 學號 姓名（例如：student001-demo、student001 demo）
• 姓名_學號（也可辨識，例如：demo_student001）

注意事項：

• 允許副檔名：pdf, png, jpg, jpeg, docx, pptx, zip, md, markdown
• 系統以檔案 SHA256 去重，重複會被略過
• 會忽略 macOS metadata（如 .DS_Store、__MACOSX）

4.3 助教評分

1. 進入「開始評分」頁
2. 右上角選擇 TA
3. 點 GRADE 或 UPDATE
4. 以 4 個指標（0/25/50/75/100）評分，系統自動換算總分
5. 送出後寫入資料庫

規則：

• 每份作業最多 2 位 TA 評分
• 同一 TA 對同一 submission 會是更新（upsert）

4.4 查看成績與覆寫

1. 進入「查看成績」頁
2. 可看 TA1/TA2、平均分、最終分
3. 教授可用 OVERRIDE 輸入最終分與理由

分數欄位邏輯：

• 平均分：TA 有效分數平均
• 教授覆寫：若有覆寫則顯示
• 最終成績：有覆寫用覆寫分；否則用平均分

4.5 匯出 CSV

• 在成績頁點 EXPORT CSV
• 會下載 UTF-8 with BOM 的 CSV，適合直接用 Excel 開啟

5. 預覽與下載

• /download/{submission_id}：檔案下載/內嵌顯示
• /preview/{submission_id}：支援 docx/pptx/markdown 類型預覽頁

目前行為：

• PDF / 圖片：可直接在瀏覽器內看
• DOCX：前端渲染（docx-preview）
• Markdown：前端渲染（marked + DOMPurify）
• PPTX：目前提供下載提示（尚未啟用完整前端渲染）

6. 管理功能（危險操作）

儀表板提供「重置系統資料」按鈕，會清除：

• 當前週次資料庫中的學生、提交、評分、覆寫
• uploads/<week>/ 下對應檔案

請務必確認週次無誤再執行。

另外也提供「全部週次重置」按鈕，會一次清除所有週次資料庫中的學生、提交、評分、覆寫，並清理所有週次上傳檔案。

人員管理（全域統一）

• 路徑：/admin/staff
• 在同一頁設定 TA 名單與教授姓名
• 儲存後會套用到所有週次資料庫

備註：

• 若某位舊助教已存在評分紀錄，或某位舊教授已存在覆寫紀錄，系統不會強制刪除，會顯示提示。

7. 可設定環境變數

DEFAULT_RUBRIC

用途：設定評分頁 4 個指標的預設值。

格式：4 個 0~100 數字，以逗號分隔。

export DEFAULT_RUBRIC="25,50,75,100"
python app.py

解析失敗或不合法時，會退回預設 0,0,0,0。

8. 常見問題

匯入後看不到資料？

• 先確認上方週次是否和匯入時一致
• 到「查看成績」頁確認是否有資料

為什麼顯示「已匯入（雜湊值重複）」？

• 代表檔案內容 SHA256 相同，系統已判定為重複

出現 CSRF 驗證失敗？

• 通常是頁面過舊或 Cookie 狀態不一致
• 重新整理頁面後再送出

9. 主要頁面清單

• /：單週儀表板
• /dashboard/all-weeks：跨週儀表板
• /import：匯入檔案
• /grade：評分頁
• /results：成績頁
• /export：CSV 匯出
• /admin/reset：重置資料（POST）
• /admin/staff：全域人員管理

10. 授權與備註

此專案目前內部流程用途為主，建議定期備份 week_dbs/。 有什麼問題可以聯絡我