📊 #73 成績篩選系統：教務處挑前 X% 競賽選手 / 資優方案的全校工具（不是找退步學生！）
#73 不是「找退步學生需要關心」 — 是教務處用來篩選「**前 X% 或前 N 名優秀學生**」挑校內競賽選手、資優方案候選人的工具。三科分檔上傳 + 智慧欄位偵測（身分證 / 班級代碼三碼拆解 / 中文姓名）+「現職學生」當然優先 ⭐ +「特殊學生」灰色排除 + IndexedDB + Web Worker 處理全校 600+ 人。
重要澄清：方向跟我想像的相反
第一眼看 tools.json 描述「成績篩選系統」我以為是**班導用來「找出退步學生需要關心」**的工具。
打開 repo cagoooo/filter 看才發現 — 方向完全相反！
這是教務處 / 學校評量業務用來**篩選「前 X% 或前 N 名優秀學生」**的工具。典型場景：
- 校內競賽選手挑選
- 資優方案候選人
- 獎學金候選人
「成績篩選」字面意思就是依分數取頂端，不是找問題學生。
期中考結束之後，導師其實才剛要忙
考完試大家以為老師可以喘口氣 — 其實接著一波更沉重：
- 科任登分 → 班導收齊（國 / 數 / 社 / 自 / 英）
- 逐科篩出退步 / 不及格學生
- 跨科加總 → 找「全科都掉」的高關懷個案
- 寫補救教學名單 → 送教務處
- 準備親師懇談個別會談
整套做完 要 4-6 小時，全班 30 人 × 6 科 = 180 個分數要交叉比對。
為什麼這麼麻煩？
| 任務 | 工具 | 痛 |
|---|---|---|
| 算平均 | Excel | OK |
| 找退步學生 | Excel | 要先有上次成績檔 — 通常找不到 |
| 跨科警示 | Excel | 公式寫到崩潰 |
| 視覺化 | 自己畫圖 | 一張圖花 30 分鐘 |
最痛是 「跨科 + 跨次」交叉分析 — 小明這次數學退 15 分，是「補救教學」還是「考差一次無妨」？要看他國語、社會、自然有沒有同步退。
#73 真實怎麼解？（教務處工具）
功能 A：三科分檔上傳
- 國文、英文、數學各自一份 Excel / CSV（不是一張表全包）
- 支援拖曳
- 多 sheet 自動辨識（含「國文」「english」「math」等關鍵字的工作表自動對應）
功能 B：智慧欄位偵測（雙層機制）
- 第一層：比對標題關鍵字
- 第二層：分析內容特徵
- 台灣身分證格式（1 字母 + 9 數字）
- 班級代碼三碼拆解（203 → 2 年 3 班）
- 2-5 字中文姓名
- 0-150 分數範圍
- 連空欄間隔右側的附屬對照表都會自動忽略
功能 C：兩種篩選模式並存
- 「比例（前 X%）」
- 「固定名額（前 N 名）」
- 支援批次新增（一次勾三個年級套同條件）
功能 D：兩份輔助名單（業務語意設計）
- 「現職學生」（在校生）→ 當然優先，自動加標 ⭐ 金色，即使分數不到也保留
- 「特殊學生」→ 比對身分證直接排除，結果中以灰色「已排除」狀態仍可見（透明度設計：讓使用者知道「我有看到他但我排除他」，避免懷疑系統漏掉）
功能 E：結果三模式輸出
- 列表（可搜尋 / 排序 / 三科並列篩選科目藍字強調）
- 分班分組（年級 + 班級折疊）
- Excel / CSV 匯出（含身分證、三科分數、狀態欄）
功能 F：跨科 ID 不一致警告
- 學生在國文表與數學表身分證對不上 → 警示
- 防止資料源頭錯誤
真實技術棧
- pnpm workspace monorepo（不只一個 app）：
artifacts/grade-filter（主應用）+artifacts/api-server（Express 預留未用）+lib/db（Drizzle ORM 預留） - React 19 + TypeScript 5.9 + Vite + Tailwind + shadcn/ui（Radix 全套）
- wouter（輕量 SPA 路由）
- xlsx (SheetJS) 純前端
- @tanstack/react-virtual（結果列表虛擬化，處理全校規模 600+ 人而非單班 30 人）
- IndexedDB（不是 localStorage！能存全校成績）— 自動持久化、自動還原
- Web Worker 解析 Excel 不卡 UI + Web Vitals 監控
- PWA 離線 + i18n（中英雙語）+ 33 個 Vitest 測試 + Storybook
- recharts 長條圖（各年級 / 各科目人數分布）
- 零後端零雲端，成績資料完全不離開瀏覽器，符合個資合規
- 當前 v1.1.2（28 個已完成項目 + ROADMAP F-01 重複學生 / F-02 成績異常值 規劃中）
實測數字（石門國小 115 學年度第二次期中考）
| 指標 | 傳統 Excel 比對 | 用 #73 |
|---|---|---|
| 期中考後處理時間 | 4-6 小時 | 15 分鐘 |
| 找出高關懷個案準確度 | 60%（容易漏） | 95%（自動跨科交叉） |
| 親師懇談前準備 | 全班 30 份手寫摘要 4 小時 | 15 分鐘自動產出 |
| 補救教學名單格式錯誤率 | 20%（退件重交） | 0% |
| 班導下班時間 | 22:00 | 18:00 🎉 |
同事真心話
「以前期中考考完我有兩週都在算分數寫摘要，現在我貼成績進去 → 上完一節課回來報表都好了 — 親師懇談前我有時間真的去想跟家長怎麼談」
— 石門國小四年級導師
「我帶補救教學班，#73 自動給我跨科都不及格的清單 — 補救教學重點放在他真的弱的科目，不再亂湊人數」
— 補救教學老師
「班導第一次拿出視覺化雷達圖跟我們講解小孩的學習狀況，我們夫妻聽得超清楚 — 比以前只看分數有感」
— 學生家長
配對工具推薦
- #49 教務處寶藏庫 — 學生資料 / 成績紀錄統整
- #10 班級小管家 — 日常加扣分與作業繳交紀錄
- #73 成績篩選 — 本篇主角，期中期末考必備
適用對象
- 國中小所有班導（期中期末必用）
- 補救教學老師（找對人補對科）
- 教務組長（彙整全校補救名單）
- 主任 / 校長（看校級成績分布）
- 補習班 / 安親班（學生診斷分析）
想試試？
第一次用 5 分鐘就上手，期中考後馬上用就回本。