供助教設計的輕量成績登記 SPA（Single-Page Application），在瀏覽器端運行，無需登入。
index.html ← 唯一入口（SPA），只保留 HTML 結構；頂部可設定 Supabase URL/Key
style-preview.html ← 主題預覽頁：一頁看完所有元件在五組主題下的樣子，可即時切換比較
css/tokens.css ← 設計 token（色彩／字級／間距／圓角／陰影）＋五組主題定義
css/style.css ← 全站元件樣式（只引用 token，含 RWD 響應式版型）
js/config.js ← 全域設定與 Supabase 初始化
js/utils.js ← 共用工具、Toast/Confirm、CSV 匯出、分頁、Loading
js/settings.js ← 系統設定（系統名稱、助教名單）與 TA 選單
js/api.js ← API 層（Supabase／原生 REST 皆走此層）
js/grading.js ← 加權平均計算邏輯
js/home.js ← 首頁
js/students.js ← 學生名單 + xlsx 匯入
js/assignments.js ← 作業/測驗管理（含權重占比）
js/grades.js ← 成績登記頁
js/query.js ← 成績查詢頁（依學生／依考試／成績矩陣）
js/app.js ← 導覽（hash 路由）、側邊欄抽屜（RWD）、清除全部資料、初始化
supabase-schema.sql ← 發布用：在 Supabase SQL Editor 執行以建立資料表
vercel.json ← 發布用：Vercel 部署設定（可留空）
README.md ← 說明與發布步驟
⚡ 純靜態網站，無建置流程（不需 npm install / webpack），
css/與js/檔案直接以<link>/<script>引入，Vercel 可直接部署。發布時需設定 Supabase 並用 Vercel 取得網址（見下方）。 📱 已支援 RWD：電腦（≥993px）、平板（577–992px，側邊欄改為可收合抽屜）、手機（≤576px，單欄版型）皆可正常使用。 🎨 已支援換膚：五組主題（學術紙感／現代淺色／極簡黑白／深色模式／經典藍），在「系統設定 → 外觀主題」點選即可切換，選擇記錄在該台裝置的 localStorage。想比較各主題可直接開style-preview.html。
- 顯示系統名稱、今日日期
- 四格統計卡：學生人數、作業/測驗數、已登記成績、平均分數
- 快速導覽卡（點擊跳至各功能頁）
- 最近 x 筆作業/測驗列表，附「直接登記」按鈕
- 新增 / 編輯 / 刪除學生（學號、姓名、班級）
- 關鍵字搜尋（學號、姓名、班級）
- 班級篩選下拉
- 分頁顯示
- 📂 匯入 .xlsx / .xls / .csv 學生名單
- 拖曳或點擊上傳
- 自動偵測欄位（學號/姓名/班級）
- 預覽前 x 筆、手動調整欄位對應
- 重複學號自動略過
- 匯出 CSV
- 新增 / 編輯 / 刪除（測驗ID、名稱、類型、日期、滿分、占比 (%)、描述）
- 類型：作業 / 小考 / 期中期末
- 關鍵字搜尋 + 類型篩選
- 占比 (%)：設定該作業/測驗占學期總成績的權重，用於計算「加權平均」；列表上方會顯示目前權重總和，方便確認是否接近 100%
- 選擇作業/測驗 → 顯示所有學生
- 班級篩選
- 黏性操作列：進度條、未儲存筆數、「全部儲存」、跳位搜尋隨捲動固定在畫面上；表頭同時黏性化
- 鍵盤流程：
Enter存檔並往下、Shift+Enter存檔並往上、↑/↓純移動不存檔（公假列自動跳過） - 跳位搜尋：輸入學號或姓名的一部分，直接跳到該列並聚焦分數欄
- 未儲存保護：切換頁面、切換作業或關閉/重新整理瀏覽器前都會提醒，避免改到一半靜默遺失
- 「全部儲存」批次存檔
- 色彩標示：未儲存（黃）/ 已儲存（綠）/ 未登記（灰）
- 記錄登記人（右上角助教身份）
- 匯出 CSV
- Tab 1 – 依學生查詢：輸入學號/姓名，顯示所有成績 + 得分率長條圖 + 加權學期成績
- Tab 2 – 依作業查詢：選擇作業，顯示全班成績 + 統計（平均/最高/最低）+ 分佈直方圖
- Tab 3 – 成績矩陣：學生 × 作業完整矩陣，色彩標示（≥90% 綠 / 60-89% 黃 / <60% 紅），平均欄改為加權平均 (%)；橫向捲動時凍結學號／姓名／班級三欄（手機只凍結學號），不會看不出是誰的成績
- 三種 Tab 均可匯出 CSV
- 每個作業/測驗可在「作業/測驗管理」個別設定占比 (%)（例如：小考1=5%、小考2=5%、期中=40%、期末=50%），並可選擇類型：作業 / 小考 / 期中期末 / 大會考
- 某位學生的加權平均 = 該生「已登記成績」的項目，依其占比比例重新正規化計算（尚未登記的項目不會拉低平均）
- 若所有作業/測驗都尚未設定占比，系統會自動改用「得分率」的簡單平均，不影響原有使用方式
- 套用範圍：首頁統計卡「加權平均成績」、成績矩陣「加權平均(%)」欄、成績查詢「加權學期成績」、CSV 匯出
- 「滿分」欄位僅用於限制成績登記時可輸入的最高分（例如某次考卷加分題很多、真實總分是 131 分，就把滿分設為 131，讓分數可以填到 131），不會拿來當作百分比計算的分母
- 計算得分率時一律直接把輸入的分數當作「100 分制」下的分數（例如填 76 分就是 76%，不會再除以滿分 131 變成 58%）
- 因此若某次分數超過 100（例如加分後 105），超過的部分才視為「超額加分」，觸發下方的回補機制；未超過 100 則直接以該分數為得分率
- 若某次考試分數超過 100（例如加分後 105 分），超過的部分視為「加分」，得分率會先封頂在 100%
- 多出來的加分會依「未滿分比例」自動分配、回補到同類型（作業/小考/期中期末/大會考，依「類型」欄位判斷）其他未滿分的項目，缺額越大分配越多，直到補滿 100% 或加分用完為止
- 例：小考1 考了 105 分（超額 5 分），小考2 考了 92 分（缺 8 分），若小考3 也缺 2 分，則超額的 5 分依缺額比例（8:2 = 4:1）分配，小考2 補回 4 分（變 96）、小考3 補回 1 分（變 99）
- 成績登記頁的分數欄位旁可勾選「公假」，勾選後不需輸入分數，且不會被計入「未登記」提醒
- 若某位學生在同類型中有一次（或多次）標記公假，該次（或那幾次）的占比會依「有考」項目原本的占比比例，自動合併到有考的項目上
- 例：兩次小考各占 10%，某生一次公假、一次有考，則有考那次即以 20% 計算
- 若同類型有多筆有考、多筆公假，公假的占比會依那幾筆有考項目原本的占比比例分配（不是平均分配）
- 若同類型全部都是公假（沒有任何一次有考），該類型不列入該生的加權平均計算（不會用 0 分計算）
- 純粹「缺考」（沒有請假、直接不到）請照舊直接登記 0 分，不要勾選公假，兩者計算方式不同
- 外觀主題：五組主題點選即時切換（見下方「外觀主題」）
- 修改系統顯示名稱（左上角 & 瀏覽器標題）
- 修改助教名稱：可新增/刪除/重命名（最多 5 位），儲存後立即生效
- 設定會同步到 Supabase（
app_settings），並在本機localStorage保留快取
樣式採 token 驅動：css/tokens.css 定義所有色彩／字級／間距／圓角／陰影，css/style.css 只引用這些變數，因此切換 <html data-theme="..."> 就能整站換膚，不需改動任何元件樣式。
| 主題 | data-theme |
風格 |
|---|---|---|
| 學術紙感（預設） | academic |
米白紙感底 + 深墨藍 + 暖金，襯線標題 |
| 現代淺色 | saas |
淺灰白底 + 淺色側邊欄 + 靛藍強調 |
| 極簡黑白 | minimal |
近黑白、直角細線、無陰影 |
| 深色模式 | dark |
深藍黑底 + 青色強調 |
| 經典藍 | classic |
改版前的原始配色 |
- 切換方式：系統設定 → 外觀主題，或直接開
style-preview.html比較各主題下所有元件 - 主題記在該台裝置的
localStorage（calc_ta_theme），不同助教可各自選擇，不會互相影響 - 成績矩陣色塊與 Chart.js 圖表顏色都是讀取當前主題的 CSS 變數，換膚後自動跟著變
其他操作體驗改善：
- 網址對應頁面：改用 hash 路由（
#/students、#/grades…），重新整理會留在原頁，瀏覽器上一頁與加書籤都可用 - 對話框：
Esc關閉、點遮罩關閉、開啟時自動聚焦第一個欄位、Enter直接送出、Tab焦點鎖在對話框內、關閉後焦點回到原按鈕。確認類對話框預設聚焦「取消」，避免誤按 Enter 執行刪除 - 載入狀態：改用骨架屏（skeleton）取代轉圈遮罩，減少畫面跳動
右上角下拉選單切換「助教名」（或自訂名稱）。
選擇後自動存入 localStorage（裝置偏好），每次成績登記自動帶入登記人欄位。
| 功能 | 端點 |
|---|---|
| 學生 CRUD | tables/students |
| 作業/測驗 CRUD | tables/assignments |
| 成績 CRUD | tables/grades |
| 欄位 | 型別 | 說明 |
|---|---|---|
| id | text | 系統自動生成 UUID |
| student_id | text | 學號 |
| name | text | 姓名 |
| class_name | text | 班級 |
| 欄位 | 型別 | 說明 |
|---|---|---|
| id | text | UUID |
| test_id | text | 測驗代號（如 HW01） |
| name | text | 名稱 |
| type | text | homework/quiz/exam |
| date | datetime | 日期 |
| max_score | number | 滿分 |
| weight | number | 占學期總成績的權重百分比（例：10 代表 10%），用於加權平均計算 |
| description | text | 描述 |
| 欄位 | 型別 | 說明 |
|---|---|---|
| id | text | UUID |
| student_id | text | 關聯 students.id |
| assignment_id | text | 關聯 assignments.id |
| score | number | 分數（公假時為 null） |
| note | text | 備註 |
| ta | text | 登記助教名稱 |
| status | text | normal（一般）或 excused（公假，占比併入同類型其他有考項目） |
- 若有後端（見下方「發布取得網址」），用瀏覽器打開發布後的網址即可。
- 先至「學生名單」上傳 .xlsx 匯入名單。
- 至「作業/測驗」建立評分項目。
- 至「成績登記」選擇項目並開始登記。
- 至「成績查詢」查看統計並匯出 CSV。
目標：取得一個公開網址 → 把網址傳給助教 → 對方用瀏覽器打開就能用。
本系統已內建 Supabase 後端支援，用 Vercel 免費託管即可得到網址。只需做一次設定。
- 前往 supabase.com → 註冊／登入 → New project。
- 建立專案（名稱、密碼自訂，Region 選近的即可）→ 等專案就緒。
- 左側 SQL Editor → New query → 開啟專案裡的
supabase-schema.sql，整段複製貼上 → Run。 - 左側 Settings → API，複製：
- Project URL（例如
https://xxxxx.supabase.co） - anon public key（一長串 JWT）
- Project URL（例如
- 用編輯器打開專案中的
index.html。 - 搜尋
window.SUPABASE_URL，會看到兩行：window.SUPABASE_URL = '';window.SUPABASE_ANON_KEY = '';
- 把剛才複製的 Project URL 貼進
SUPABASE_URL的引號裡。 - 把 anon public key 貼進
SUPABASE_ANON_KEY的引號裡。
（anon key 可公開、僅供前端使用，權限由 Supabase 的 RLS 控制。）
- 安裝 Node.js（若尚未安裝）：nodejs.org。
- 在終端機進入本專案資料夾，執行：
npx vercel
- 依提示登入 Vercel（可用 GitHub 登入），專案名稱直接 Enter 即可。
- 完成後終端機會給一個網址，例如：
https://calculus-score-xxx.vercel.app。 - 複製這個網址，傳給另一位助教即可。對方用瀏覽器打開就能用，兩人共用同一份資料。
- 改完程式碼後，在專案資料夾再執行一次
npx vercel，會更新同一個網址的內容。 - 其他人不用換網址，重新整理頁面（F5）就會看到最新版。
如果你的 Supabase 專案是在「加權平均」功能推出前建立的，資料表裡還沒有 weight / status 欄位，請做一次以下操作（不影響現有資料）：
- 前往 Supabase 專案 → SQL Editor → New query。
- 貼上並執行：
alter table public.assignments add column if not exists weight numeric default 0; alter table public.grades add column if not exists status text not null default 'normal';
- 執行後即可到「作業/測驗管理」為每個項目設定占比、在「成績登記」勾選「公假」。若尚未設定占比，系統會自動以簡單得分率平均顯示，不影響原本使用。
若看到錯誤
Could not find the 'weight' column of 'assignments' in the schema cache或類似訊息，就是代表還沒執行上面的 SQL，執行後重新整理頁面即可。
- 兩位助教都要從同一個 Vercel 網址進入，資料才會同步。
- 若用本機直接開
index.html（file://），且未設定 Supabase，則無法存資料（需依上述步驟設定並用 Vercel 網址）。
| 需求 | 方法 |
|---|---|
| 修改助教名稱 | 進入「系統設定」頁面直接修改，不需改程式碼 |
| 修改系統名稱 | 同上 |
| 修改主色調 | 編輯 index.html 頂部 :root 中的 --primary 等 CSS 變數 |