A-12-A User Bulk Import Specification
- P1新增 +1移除 −0
第一版式樣草案 · Markdown 來源：04-App畫面-管理員.mdGitHub 版本尚未推送；目前以本機手冊為準
取圖紀錄： QL APP，2026-10-18，版本
2410774734466577464；節點 770:2765 。學生 2x／Web 1x。圖片是目前設計稿，文字為 APlus 首版目標規格。 圖片範圍： 本節包含獨立浮層或選定的元件變體，並非完整底頁。以對應節點確認角色及狀態，尚待設計驗收。
用戶批量導入規格
🎯 功能定位
使用者： Admin (Student/Teacher templates), Super Admin (All templates including Admin)
A-12-A 為管理員提供大批量帳號生成的解決方案。透過上傳標準化的 CSV 檔案，一次性完成數百名學生或老師的資料錄入。系統將自動校驗數據格式與唯一性，並執行預設安全策略（初始密碼設定與首登強制改密）。
🧱 畫面結構（以彈窗 Modal 形式呈現）
| 區域 | 說明 |
|---|---|
| Header | APlus Admin Dashboard > User Management > Bulk Import, [🔔], [👤] |
| Step 1: Download Template | [📥 Student Template], [📥 Teacher Template], [📥 Admin Template] 按鈕 |
| Step 2: Upload CSV | Drag & Drop 區域 或 [Select File] 按鈕 |
| Step 3: Validation Preview | 狀態表格：Status, Row, Email, Error Message |
📦 區塊說明（表格）
| 區塊 | 元件 | 目的 | 行為 | 備註 |
|---|---|---|---|---|
| Template | Download Buttons | 提供標準格式 | 點擊下載對應角色的 CSV 模板 | 分為學生版、老師版、管理員版 |
| Dropzone | File Uploader | 接收用戶檔案 | 拖拽或點擊選擇 CSV 檔案 | 限制大小 5MB，僅限 .csv 格式 |
| Validation | Result Indicator | 即時反饋數據品質 | 系統自動掃描重複 Email 或格式錯誤 | 若有錯誤，[Start Import] 按鈕禁用 |
| Error Log | Text Area | 指出具體錯誤位置 | 列出行號與錯誤原因 | 方便用戶修改後重新上傳 |
| Action | Start Import | 執行數據寫入 | 點擊將校驗通過的數據存入數據庫 | 成功後彈出導入報告頁面 |
📥 CSV 文件格式規格 (CSV Specification)
1. Student 學生批量導入模板 (A-12-A-T1)
此模板包含兩位家長的聯絡資訊欄位；Parent 1 為主要聯絡人，Parent 2 為備用聯絡人。生日欄位僅作帳號資料，不用於產生或展示初始密碼。
📥 CSV 表頭 (CSV Header)
role,name,display_name,school_student_id,gender,birthday,email,parent1_name,parent1_email,parent1_phone,parent2_name,parent2_email,parent2_phone,class_ids,teacher_emails,formal_school_name,formal_grade,formal_class,academy_school,academy_zone,enrollment_session📋 欄位詳細定義
| 區塊 | 欄位 Header | 必填 | 範例 |
|---|---|---|---|
| 基本資訊 | role | 是 | Student |
| name | 是 | 張小明 | |
| display_name | 是 | David | |
| school_student_id | 否 | SCH-000123 | |
| gender | 是 | Male | |
| birthday | 是 | 2016-08-15（固定格式 YYYY-MM-DD） | |
| 是 | student@example.com | ||
| 家長 1 | parent1_name | 是 | 張大華 |
| parent1_email | 是 | dh.zhang@mail.com | |
| parent1_phone | 是 | 0912345678 | |
| 家長 2 | parent2_name | 否 | 李美玲 |
| parent2_email | 否 | ml.lee@mail.com | |
| parent2_phone | 否 | 0987654321 | |
| 校外學籍 | formal_school_name | 是 | 第一國小 |
| formal_grade | 是 | 2 | |
| formal_class | 是 | A | |
| 補習校配置 | class_ids | 是 | C101;C102 |
| teacher_emails | 否 | teacher1@example.com;teacher2@example.com（舊模板相容欄位；以班級老師設定為準） | |
| academy_school | 是 | 文府總校 | |
| academy_zone | 是 | 文府總校 | |
| enrollment_session | 是 | 3-1 |
2. Teacher 老師批量導入模板 (A-12-A-T2)
適用於新進教師入職或跨校區師資調度。
📥 模板表頭 (CSV Header)
role,name,gender,birthday,email,phone,staff_id,title,dept,subjects,school,zone📋 欄位詳細定義
| 欄位名稱 (Header) | 範例數據 | 必填 | 說明 |
|---|---|---|---|
| role | Teacher | 是 | 固定填寫 Teacher。 |
| name | 王美麗 | 是 | 老師真實姓名。 |
| gender | Female | 是 | 僅限 Male 或 Female。 |
| birthday | 1985-03-12 | 是 | 格式 YYYY-MM-DD。 |
| teacher@example.com | 是 | 老師登入帳號，全系統唯一。 | |
| phone | +886 912-345-678 | 否 | 老師聯絡電話。 |
| staff_id | T-2026-088 | 否 | 學校內部的員工管理編號（如無則留空）。 |
| title | Senior Teacher | 否 | 老師的專業職稱。 |
| dept | 語文部 | 是 | 老師所屬的行政或教學部門。 |
| subjects | 基礎漢語;進階閱讀 | 是 | 教授科目，多個請用半形分號 ( ; ) 隔開。 |
| school | 文府總校;龍華校 | 是 | 老師所屬學校，名稱必須與 A-14 設定完全一致，可設置多個。 |
| zone | 文府總校;龍華校 | 是 | 老師所屬校區，名稱必須與 A-14 設定完全一致，可設置多個。 |
3. Admin 管理員批量導入模板 (A-12-A-T3)
適用於各分校普通管理員的快速生成。只有 SuperAdmin 可以使用，其他角色不可。
📥 模板表頭 (CSV Header)
role,name,gender,birthday,email,admin_level,dept,school,zone📋 欄位詳細定義
| 欄位名稱 (Header) | 範例數據 | 必填 | 說明 |
|---|---|---|---|
| role | Admin | 是 | 固定填寫 Admin。 |
| name | 陳運營 | 是 | 管理員真實姓名。 |
| gender | Male | 是 | 僅限 Male 或 Female。 |
| birthday | 1990-11-20 | 是 | 格式 YYYY-MM-DD。 |
| admin@example.com | 是 | 管理員登入帳號，全系統唯一。 | |
| admin_level | ZoneAdmin | 是 | ZoneAdmin / SuperAdmin。 |
| dept | 教務處 | 是 | 所屬行政管理部門。 |
| school | 龍華校;左新校 | 是 | 負責的學校，名稱須存在於 A-14。多個請用 ; 隔開。 |
| zone | 龍華校;文府總校 | 是 | 負責的校區，名稱須存在於 A-14。多個請用 ; 隔開。 |
Birthday 共用校驗規則（A-12／A-12-A）
- 輸入必須嚴格符合
^\d{4}-\d{2}-\d{2}$，並且是有效的 Gregorian calendar 日期；例如2016-02-29有效，2019-02-29、2016-13-01、16-8-5均為 Critical Error。 - Birthday 以 Date-only 保存與比較，不附加時間或時區，也不得因伺服器／用戶端時區轉換而前後偏移一天。
- 日期不得晚於帳號建立當天；未來日期回報
BIRTHDAY_IN_FUTURE。Student 不在產品目標 6–12 歲範圍時回報BIRTHDAY_OUTSIDE_TARGET_RANGEWarning，需管理員確認並寫入 Audit，但不因轉學、留級等合理情境直接阻斷。 - 生日日期依格式與日期有效性校驗；不得轉換或串接為初始密碼。
🔁 交互流程圖
正在載入流程圖…
⚙️ 狀態管理
| 狀態 | 觸發條件 | 畫面表現 |
|---|---|---|
| 正常 | 頁面載入完成 | 顯示三步驟流程 |
| 上傳中 | CSV 上傳進行中 | Progress Bar 顯示進度 |
| 校驗中 | 系統解析 CSV | Loading Spinner |
| 校驗通過 | 所有行有效 | [Start Import] 按鈕可用 |
| 校驗錯誤 | 存在 Error 行 | [Start Import] 按鈕禁用，錯誤行標紅 |
| 導入中 | 數據寫入進行中 | Progress Bar + 禁用所有操作 |
| 導入完成 | 寫入成功 | 顯示 Import Report |
| 權限拒絕 | Zone Admin 上傳 Admin CSV | 報錯並拒絕導入 |
🔎 邏輯自我檢查
- 唯一性校驗： email 在全系統內必須唯一，導入時若衝突需明確指出衝突的行號。
- 數據聯動： Student 模板中的
teacher_emails是舊模板相容欄位，不作為教師存取權限來源。若有填寫，系統需核對老師是否存在及是否已分配至class_ids；不一致時標註 Warning，實際權限以 A-21／A-23 的班級老師關聯為準。 - 管理員創建限制： 已明確區分超級與普通管理員的創建邏輯，防止權限提權 (Privilege Escalation)。
- 多選處理： class_ids (所屬班級) 欄位支持分號分隔，以便學生可以同時歸屬於多個教學單元。
- 密碼生成與強制引導： 數據寫入後，後端自動格式化 birthday (YYYYMMDD) 存入 password 字段（經 Hash 加密）。force_password_reset 標籤設為 true。