A-12-A User Bulk Import Specification
內容依原始規格呈現 · 查看 Markdown 來源 ↗需具備倉庫查看權限
用戶批量導入規格
🎯 功能定位
使用者： Admin (Student/Teacher templates), Super Admin (All templates including Admin)
A-12-A 為管理員提供大批量帳號生成的解決方案。透過上傳標準化的 CSV 檔案，一次性完成數百名學生或老師的資料錄入。系統將自動校驗數據格式與唯一性，並執行預設安全策略（初始密碼設定與首登強制改密）。
🧱 畫面結構（以彈窗 Modal 形式呈現）
| 區域 | 說明 |
|---|---|
| Header | Nihao 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,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 | |
| gender | 是 | Male | |
| birthday | 是 | 2016-08-15 | |
| 是 | xiaoming@nh.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 | 是 | t1@nh.com;t2@nh.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。 |
| m.wang@nh.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.chen@nh.com | 是 | 管理員登入帳號，全系統唯一。 | |
| admin_level | ZoneAdmin | 是 | ZoneAdmin / SuperAdmin。 |
| dept | 教務處 | 是 | 所屬行政管理部門。 |
| school | 第二小學;第三小學 | 是 | 負責的學校，名稱須存在於 A-14。多個請用 ; 隔開。 |
| zone | 台中校區;台北校區 | 是 | 負責的校區，名稱須存在於 A-14。多個請用 ; 隔開。 |
🔁 交互流程圖
正在載入流程圖…
⚙️ 狀態管理
| 狀態 | 觸發條件 | 畫面表現 |
|---|---|---|
| 正常 | 頁面載入完成 | 顯示三步驟流程 |
| 上傳中 | CSV 上傳進行中 | Progress Bar 顯示進度 |
| 校驗中 | 系統解析 CSV | Loading Spinner |
| 校驗通過 | 所有行有效 | [Start Import] 按鈕可用 |
| 校驗錯誤 | 存在 Error 行 | [Start Import] 按鈕禁用，錯誤行標紅 |
| 導入中 | 數據寫入進行中 | Progress Bar + 禁用所有操作 |
| 導入完成 | 寫入成功 | 顯示 Import Report |
| 權限拒絕 | Zone Admin 上傳 Admin CSV | 報錯並拒絕導入 |
🔎 邏輯自我檢查
- 唯一性校驗： email 在全系統內必須唯一，導入時若衝突需明確指出衝突的行號。
- 數據聯動： Student 模板中的 teacher_emails 必須在系統中已有對應的 Teacher 帳號，否則標註為 Warning。
- 管理員創建限制： 已明確區分超級與普通管理員的創建邏輯，防止權限提權 (Privilege Escalation)。
- 多選處理： class_ids (所屬班級) 欄位支持分號分隔，以便學生可以同時歸屬於多個教學單元。
- 密碼生成與強制引導： 數據寫入後，後端自動格式化 birthday (YYYYMMDD) 存入 password 字段（經 Hash 加密）。force_password_reset 標籤設為 true。