A-52 Trophy Exam Detail & Class Analytics
尚無原型配圖完整規格見下方正文。
- P1新增 +1移除 −0
第一版式樣草案 · Markdown 來源：04-App畫面-管理員.mdGitHub 版本尚未推送；目前以本機手冊為準
原型待補： 尚無本節專屬的 QL APP Frame；保留文字規格，不以舊圖或生成圖替代。
交付分期： 共用統計口徑與班級聚合 CSV 屬本次最小範圍，由 A-50 原頁增加 Export 入口。以下完整頁面、KPI Cards、下鑽與 Student Detail 為後續候選畫面，不是 CSV 的前置需求。第一階段不提供新的逐學生查看／導出入口，也不新增 15 分鐘下載政策或非同步匯出平台；沿用既有授權下載能力，容量上限與異步需求有實際證據後另行確認。 檢定班級完成度與營運導出
⚠️ Figma 待設計： Repository 目前沒有 A-52 對應 Frame／截圖。此節是開發、驗收與後續 Figma 補稿的目標規格。
🎯 功能定位
使用者： Admin / Super Admin
- 逐班追蹤： 讓管理員在一個 Exam 下比較各 School／Class 的派送、完成、分數與及格情況。
- 追溯明細： 從班級摘要下鑽至每次 Challenge 與每位派送對象的狀態。
- 營運導出： 直接導出 Trophy 完成度 CSV；這是校務營運報表，不包含 A-90 的研究使用數據或原始語音。
🧱 畫面結構
| 區域 | 說明 |
|---|---|
| Header | < Back to Trophy Library、Exam Name／Level／Round／Status、[Preview Test] |
| Scope Filters | Date Range、Zone → School → Class、Exam Version、Challenge；Completion／Pass Status 只篩 Student Detail |
| KPI Cards | Assigned、Completion、Avg. Score、Pass Count／Rate |
| Class Breakdown | School、Class、Challenge Count、Assigned、Completed、Completion、Avg. Score、Pass Count／Rate、[View Students] |
| Student Detail | School Student ID、Student、Member State、Challenge、Progress、Effective Score、Pass／Fail、Attempt Count、Completed At |
| Actions | [Export Trophy CSV]；Admin 僅能導出管轄 Zone，Super Admin 可導出所有可見範圍 |
🔗 Trophy 資料關係
正在載入流程圖…
exam_id + source_version識別不可變內容修訂；由系統對應既有 Exam 記錄／快照，不要求管理員手填版本或新增匯入欄位。同一內容可多次派送，摘要與 CSV 按內容修訂分列。challenge_id識別一次派送，不等於 Listening／Reading Section。challenge_member_snapshot在實際派送瞬間建立；Send Now 為確認時，Pre-arrange 為排程真正送出時。- 同一 Snapshot Member 即使有多次 Attempt，在 Assigned／Completed／Pass Count 中都只算一人次。
📐 指標真值定義
| 指標 | 計算方式 | 空值／邊界 |
|---|---|---|
| Assigned | COUNT(challenge_member_snapshot) | 不使用目前 Class roster |
| Completed | 有至少一筆 Final Submitted Attempt 的 Snapshot Member 數 | 未開始、進行中、逾期未交都不算 Completed |
| Completion Rate | Completed / Assigned × 100% | Assigned = 0 顯示 — |
| Effective Result | 每位完成者 Final Submitted Attempt 的最高分；同分取 completed_at 最新者 | Auto-Submit 也屬 Final Submitted |
| Avg. Score | SUM(effective_score) / Completed | Completed = 0 顯示 — |
| Pass Count | effective_score >= exam.pass_score 的完成者數 | 只在 Completed 中判定 |
| Pass Rate | Pass Count / Completed × 100% | Completed = 0 顯示 — |
查詢範圍與永久刪除後的計算邊界
- 時間範圍： Date Range 以實際
assigned_at選擇 Challenge，使用校務時區將起訖日期轉成 UTC 半開區間；不是只計期間內有提交的學生。T-01 的 month／latest 與 T-40／T-42 使用同一派送時間口徑。 - 分母不隨結果篩選： Pass／Fail、完成狀態、姓名搜尋及分頁只作用於 Student Detail；KPI、Class Breakdown 與班級 CSV 保持同一 Scope 下完整派送分母。例如派送 30 人、提交 24 人，篩選 Pass 21 人後仍顯示 Completion
24 / 30，不能變成21 / 21。 - 先加總再除： 跨 Challenge／Class 先加總 Assigned、Completed、分數總和與 Pass Count，再計比例；不能直接平均班級完成率。不同 Exam 版本分列，不合併不同配分版本的原始平均分。
- 刪除後不能只 COUNT 現存列： 上表 COUNT 是對邏輯派送對象的定義，不代表刪除後掃描剩餘個人表。Assigned 的派送總數需獨立保存；Completed／Pass Count／Score Sum 只有在已驗證的非個人聚合保存方案中才可保留，且不得與剩餘個人列重複計算。該保存、刪除與重試契約仍待實作驗證；驗證前含永久刪除貢獻的表現統計依下方規則抑制，不猜補數值。
- 歷史歸屬不等於授權：
scope_snapshot用於顯示派送歸屬，不能單獨授予舊 Zone 管理員對已遷出學生的即時分析權限。跨 Zone 遷移後歷史聚合的歸屬需產品確認；個人連結每次以當前授權判斷。
名冊變更與刪除後的歷史口徑
| 事件 | 歷史分母 | 明細顯示 |
|---|---|---|
| 學生轉班／離班 | 保留 | 標示 Former member，不改寫原 Class Snapshot |
| Student 進入 Recycle Bin | 保留 | 顯示 Deleted student，名字隱藏；恢復後重新顯示授權範圍內資料 |
| 隱私永久刪除 | 保留派送總數；表現統計視聚合方案驗證狀態 | 清除身份、個別結果、逐題答案及關聯；不再顯示明細列。尚未驗證匿名聚合方案時，相關切片的表現統計顯示 Privacy protected |
| Class／School／Zone 軟刪除 | 保留 | A-52 只讀顯示 Snapshot 名稱並標示 Archived scope |
📤 Export Trophy CSV
導出目的為比較各班 Trophy 完成度，因此每列代表一個 Exam × Challenge × Class 聚合，不提供逐學生導出。套用目前頁面篩選，固定欄位如下：
csv
exam_id,source_version,exam_name,challenge_id,zone_id,school_id,class_id,class_name,assigned,completed,completion_rate,avg_score,pass_count,pass_rate,privacy_suppressed- Admin 只可導出管轄 Zone；Super Admin 可導出目前選定範圍。伺服器端必須重新驗權，不信任前端 Filter。
- CSV 不包含學生明細列、姓名、School Student ID、Email、學生 internal UUID、逐題答案、個別完成時間、個別分數或語音；第一階段逐學生追蹤沿用 A-22 → A-11 或既有授權分析頁，不依賴尚未實作的 A-52 下鑽。
- 隱私顯示閘門： 不能把
Assigned >= 5當成已匿名的證明。若其他學生的明細仍可見，總分減去已知分數就可能推算被刪者；同理，放大到 School／Zone 也不能自動解除限制。匿名聚合與差分抑制方案驗證前，含永久刪除貢獻的切片一律不返回 Completed、Completion、Avg. Score、Pass Count／Rate 等表現值，privacy_suppressed=true。此規則同樣覆蓋 T-01／T-40／T-42 的摘要、最高／最低分、逐題統計及 T-43 底部聚合。 - 每次導出寫入 Audit Log：操作者、角色、時間、Exam、篩選範圍、列數與結果；不得由 A-52 繞過 A-90 取得研究／語音資料。
- 建立與下載時均重驗角色、當前 Zone Scope 和資料刪除狀態，下載只供建立者使用。非同步檔案與 15 分鐘連結是後續候選，不為本次新增工作平台；未支援的大範圍應提示縮小範圍，不產生不完整報表。連結過期或撤銷不能刪除已下載到使用者電腦的副本。
⚙️ 狀態管理
| 狀態 | 畫面表現 |
|---|---|
| 無派送 | KPI 顯示 Assigned = 0，其餘為 —；提示「This exam has not been assigned in this scope.」 |
| 有派送、無完成 | Completion = 0 / N (0%)；分數與 Pass Rate 顯示 — |
| 部分完成 | 同時顯示 Completed、In Progress、Not Started／Expired，分母固定 |
| 權限改變 | 立即停止顯示與導出，返回 A-50 並提示存取權已變更 |
| 導出中 | 按鈕禁用並顯示進度；重複點擊不得建立重複工作 |
🔎 邏輯自我檢查
- 口徑一致： A-50、A-52、T-40、T-42 使用同一 Snapshot 與 Effective Result 定義。
- 歷史穩定： 轉班、離班或組織軟刪除不會重算既有派送分母。
- 隱私隔離： 營運 CSV 只提供校務必要欄位，研究／語音導出仍由 A-90 且僅限 Super Admin。
- Section 一致： Listening／Reading 僅為同一 Exam 的內容段落，不產生兩個完成度或兩份 Result。