A-23 Bulk Import Specification
內容依原始規格呈現 · 查看 Markdown 來源 ↗需具備倉庫查看權限
班級批量導入規格
🎨 Figma: node-722-7676 (A-20/A-21/A-23 共用) 🔗
🎯 功能定位
使用者： Admin / Super Admin
A-23 提供管理員大批量建立「班級」的自動化方案。透過上傳預定義的 CSV 模板，系統能自動校驗行政歸屬（校區與學校）與教學維度（年級與 Level）的合法性，並在 A-20 列表中心批量生成班級條目。
🧱 畫面結構（以彈窗 Modal 形式呈現）
| 區域 | 說明 |
|---|---|
| Header | Import Classes, [X] 關閉按鈕 |
| Step 1 | Download Template: [📥 Download Class CSV Template] |
| Step 2 | Upload File: Drag & Drop 區域 或 [Browse Files] |
| Step 3 | Validation Preview: 自動校驗結果, Error Log |
📦 區塊說明
| 區塊 | 元件 | 目的 | 行為 | 狀態 | 備註 |
|---|---|---|---|---|---|
| Template | Download Button | 提供標準格式 | 點擊下載 Class_Template.csv | Normal | 包含 Grade 與 Level 的有效值枚舉 |
| Upload | Drag & Drop | 接收 CSV 檔案 | 拖拽上傳，限制 2MB | Active | 僅接受 .csv 檔案 |
| Validation | Result Box | 數據合規性預檢 | 系統自動核對 Zone/School/ID 衝突 | Pre-check | 錯誤行需修正後方可全量導入 |
| Error Log | List View | 定位錯誤 | 顯示具體行號與邏輯錯誤原因 | Warning | 例如：校區與學校不匹配 |
| Action | Start Import | 執行寫入 | 點擊將驗證通過的班級存入 A-20 | Disabled | 若有 Critical Error 則禁用 |
📥 CSV 模板規格 (Class_Import_Template.csv)
📋 模板表頭與範例
class_id,class_name,zone_name,school_name,category_id,level_code,status📑 欄位定義
| 欄位名稱 | 必填 | 說明 | 範例值 |
|---|---|---|---|
| class_id | 是 | 系統唯一標識，不可重複 | C2026-A01 |
| class_name | 是 | 班級顯示名稱 | Grade 2 - Class A |
| zone_name | 是 | 所屬校區 (手動輸入) | North Zone |
| school_name | 是 | 所屬學校 (手動輸入) | Nihao Primary 01 |
| category_id | 是 | 課程 1 級分類 | NH |
| level_code | 是 | 教學難度 Level | Level 3 |
| status | 否 | 初始狀態，默認 Active | Active / Inactive |
🔁 交互流程圖
正在載入流程圖…
⚙️ 狀態管理
| 狀態 | 觸發條件 | 畫面表現 |
|---|---|---|
| 權限拒絕 | School Admin 上傳非管轄學校 | 校驗階段報錯 Permission Denied |
| 數據完整性錯誤 | class_id 已存在 | Error Log 顯示重複 ID |
| 層級不匹配 | school_name 不歸屬 zone_name | Error Log 顯示關聯錯誤 |
| 異步處理 | 導入數量 > 100 筆 | 前端顯示進度條，防止 UI 鎖死 |
| 部分成功 | 支援忽略錯誤行導入正確行 | 需管理員勾選確認 |
🔎 邏輯自我檢查
- 層級對應關係： 後端校驗必須確保 school_name 確實歸屬於 zone_name。
- 與 A-12 的連動： A-12 用戶導入時使用的 class_ids 必須在此頁面預先建立。
- 重複導入處理： 若管理員重複上傳同一個檔案，系統應識別 class_id 已存在並阻止重複寫入。
- 字符校驗： class_name 應支援特殊字符（如橫槓、空格），但長度需限制在 50 字元內。