A-23 Bulk Import Specification
- P1新增 +1移除 −0
第一版式樣草案 · Markdown 來源：04-App畫面-管理員.mdGitHub 版本尚未推送；目前以本機手冊為準
取圖紀錄： QL APP，2026-10-18，版本
2410774734466577464；節點 746:1449 。學生 2x／Web 1x。圖片是目前設計稿，文字為 APlus 首版目標規格。 圖片範圍： 本節包含獨立浮層或選定的元件變體，並非完整底頁。以對應節點確認角色及狀態，尚待設計驗收。
班級批量導入規格
🎨 Figma: node-722-7676 (A-20/A-21/A-23 共用) 🔗
🎯 功能定位
使用者： Admin / Super Admin
A-23 提供管理員大批量建立「班級」並分配老師的自動化方案。透過上傳預定義的 CSV 模板，系統能自動校驗行政歸屬（校區與學校）、教學維度（Category 與 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_Import_Template_v2.csv | Normal | 包含 Category、Level、Status 的有效值與老師欄位說明 |
| Upload | Drag & Drop | 接收 CSV 檔案 | 拖拽上傳，限制 2MB | Active | 僅接受 .csv 檔案 |
| Validation | Result Box | 數據合規性預檢 | 系統自動核對 Zone／School／ID、老師與 Status | Pre-check | 錯誤行需修正後方可全量導入 |
| Error Log | List View | 定位錯誤 | 顯示具體行號與邏輯錯誤原因 | Warning | 例如：校區與學校不匹配 |
| Action | Start Import | 執行寫入 | 零 Critical Error 時，點擊將整份已驗證檔案寫入 A-20 | Disabled | 任一行有 Critical Error 即禁用；不支援跳過錯誤行 |
📥 CSV 模板規格 (Class_Import_Template_v2.csv)
範例中的 Zone、School、Class 與 Email 均為示意資料。填表前須刪除或替換範例列，並從 A-21 的有效選項取得實際 category_id 與 level_code；此檔可供填寫，不是能直接匯入任意環境的成功 Fixture。
📋 模板表頭與範例
class_id,class_name,zone_name,school_name,category_id,level_code,teacher_emails,status📑 欄位定義
| 欄位名稱 | 必填 | 說明 | 範例值 |
|---|---|---|---|
| class_id | 是 | 系統唯一標識，不可重複 | C2026-A01 |
| class_name | 是 | 班級顯示名稱 | English Core Class A |
| zone_name | 是 | 所屬校區 (手動輸入) | 文府總校（示例；行政層級待確認） |
| school_name | 是 | 所屬學校 (手動輸入) | 耶加文府校區（示例） |
| category_id | 是 | 課程 1 級分類 | NH |
| level_code | 是 | 教學難度 Level | Level 3 |
| teacher_emails | 否 | 班級老師 Email；多位使用半形分號 ; 分隔。每位老師必須存在、具 Teacher 角色，並符合 A-21 共用指派資格；Admin 限管轄 Zone，同 School 僅為搜尋偏好 | teacher1@example.com;teacher2@example.com |
| status | 否 | 只接受 Active 或 Inactive；去除前後空白後為空時採用 Active | Active |
🔄 模板相容與欄位邊界
- 舊版相容： 舊 7 欄模板仍可導入，系統視為未提供
teacher_emails，不阻擋既有客戶資料。 - 老師關聯： 若
teacher_emails有值，解析成功後需寫入與 A-21 相同的班級－老師關聯；不得只把 Email 複製到學生資料。 - 錯誤級別： 老師不存在、角色不是 Teacher、超出 A-21 允許的指派範圍，或
status不是允許值時，該行為 Critical Error，不得寫入。同 Zone 跨 School 不得單獨視為錯誤。 - Status 行為：
Active／Inactive的可見性、派送、成員與歷史規則完全依 A-21「Class Status 共用語義」，Bulk Import 不得另定義一套狀態。 - 生日欄位： A-23 是班級導入，沒有也不需要生日欄位。生日只出現在 A-12／A-12-A 用戶建立流程，固定輸入格式為
YYYY-MM-DD。
🔁 交互流程圖
正在載入流程圖…
⚙️ 狀態管理
| 狀態 | 觸發條件 | 畫面表現 |
|---|---|---|
| 權限拒絕 | Admin 上傳非管轄 Zone 的班級或老師 | 校驗階段報錯 Permission Denied；與 A-21 同一判斷 |
| 數據完整性錯誤 | class_id 已存在 | Error Log 顯示重複 ID |
| 層級不匹配 | school_name 不歸屬 zone_name | Error Log 顯示關聯錯誤 |
| 老師不合法 | teacher_emails 含不存在、非 Teacher 或跨範圍帳號 | 該行標記 Critical Error，列出無效 Email |
| Status 不合法 | 值不是 Active／Inactive | 該行標記 Critical Error；空值則顯示 Defaulted to Active |
| 異步處理 | 導入數量 > 100 筆 | 前端顯示進度條，防止 UI 鎖死 |
| 寫入失敗 | 驗證通過後任一 Class 或老師關聯寫入失敗 | 整份交易回滾，不留下部分班級或孤立關聯；顯示 Import ID 與失敗原因，可修正後重試 |
🔎 邏輯自我檢查
- 層級對應關係： 後端校驗必須確保 school_name 確實歸屬於 zone_name。
- 與 A-12 的連動： A-12 用戶導入時使用的 class_ids 必須在此頁面預先建立。
- 重複導入處理： 若管理員重複上傳同一個檔案，系統應識別 class_id 已存在並阻止重複寫入。
- 字符校驗： class_name 應支援特殊字符（如橫槓、空格），但長度需限制在 50 字元內。
- 老師權限一致： A-21 手動設定與 A-23 批量設定必須操作同一份班級－老師關聯，教師端 T-01 的可見班級結果應一致。
- 模板可理解性： 下載檔需附一行可刪除的範例資料與 Data Dictionary，明確寫出
teacher_emails分隔符、Status 枚舉及 A-23 不含生日。 - 交易與重試： A-23 採整份 Atomic Import；任何 Critical Error 或寫入失敗都不得部分成功。每次嘗試寫入 Import Audit（Import ID、檔案 Checksum、操作者、總行數、結果與錯誤摘要）；相同 Checksum 的成功檔案再次上傳顯示 Already Imported，相同
class_id但內容不同仍為 Critical Error。