A-33-O Import Upload Center
畫面用途
使用者： Admin / Super Admin
960:5029 ↗node-698-2843 (A-30 同頁面子視圖；含 Structure Import / Vocabulary Bundle Import 子變體) 🔗 ↗在系統地圖中查看關係 ↗
閱讀完整規格 ↓- P1新增 +1移除 −0
第一版式樣草案 · Markdown 來源：04-App畫面-管理員.mdGitHub 版本尚未推送；目前以本機手冊為準
取圖紀錄： QL APP，2026-10-18，版本
2410774734466577464；節點 960:5029 。學生 2x／Web 1x。圖片是目前設計稿，文字為 APlus 首版目標規格。
數據導入中心
🎨 Figma: node-698-2843 (A-30 同頁面子視圖；含 Structure Import / Vocabulary Bundle Import 子變體) 🔗
🎯 核心功能
使用者： Admin / Super Admin
作為 A-30 與 A-33 之間的橋樑，此頁面提供標準的 CSV/ZIP 範本下載，並允許管理員選擇特定的導入模式。這是確保數據格式正確的第一道關卡。
🧱 畫面結構
| 區域 | 說明 |
|---|---|
| Header | APlus Admin Course Management > Import Center, [👤] |
| Sidebar | < Back to Course Management |
| Import Tabs | [Structure Import] / [Vocabulary Bundle Import] Tab 切換 |
| Download | Template 下載按鈕 |
| Upload Area | Drag & Drop 區域 |
| System Logic | 當前模式的關鍵操作警示 |
| Action | [Analyze & Preview >] / [Unpack & Preview >] 按鈕 |
📦 區塊說明
| 區塊 | 元件 | 功能與行為 |
|---|---|---|
| Import Tabs | Tab Switcher | 核心導航。切換後，下方「範本下載」與「上傳邏輯」同步更新。 |
| Download | Template Link | Structure: 提供 CSV 範本。Vocabulary: 提供包含目錄結構的 ZIP 範本。 |
| Upload Area | Dropzone | Structure: 僅限 .csv。Vocabulary: 僅限 .zip。若格式不符，邊框變紅並報錯。 |
| System Logic | Info Box | 針對當前 Tab 提供關鍵的操作警示，防止管理員「空降」單字到不存在的架構中。 |
| Action | Primary Button | 點擊後進入 A-33 Preview。後端會根據當前 Tab 選擇不同的解析引擎。 |
⚙️ 導入類型的邏輯差異
Structure Import (架構導入)
- 用途： 建立或擴充 Category > Level > Session。
- 邏輯： 系統會掃描 category_id, level_code, session_id。
- 預覽重心： 是否有重複的 ID？是否有新的 Level 需要手動調整開關？
Vocabulary Import (內容導入)
- 用途： 新增或修改英文 Word／Phrase／Sentence、中文釋義、圖片／音訊與既有 QA 屬性。學生端不顯示拼音或音標。
- 邏輯： 必須先有架構，否則單字會找不到對應的「房間」。
- 預覽重心： 哪些單字是 New？哪些單字已存在需要 Update？媒體文件是否缺失？
📊 Structure Import 格式規格
下列是 APlus 首版候選格式，保留 Category → Level → Session 關聯。CORE／CORE_L1 是示例，正式代碼、排序與 Session 數須依耶加課程表確認；不等同 FAD／FLD／FPG 的正式映射。
| 欄位名稱 (Column) | 必填 | 說明 | 範例 |
|---|---|---|---|
| category_id | 是 | 課程分類識別碼 | CORE |
| category_name | 是 | 分類顯示名稱 | English Core |
| level_code | 是 | 課程級別識別碼 | CORE_L1 |
| level_name | 是 | 課程級別顯示名稱 | English Core Level 1 |
| session_id | 是 | 級別內單元識別碼 | 1-1 |
| session_name | 是 | 單元名稱 | Greetings |
CSV 範本內容
csv
category_id,category_name,level_code,level_name,session_id,session_name
CORE,English Core,CORE_L1,English Core Level 1,1-1,Greetings
CORE,English Core,CORE_L1,English Core Level 1,1-2,Numbers
CORE,English Core,CORE_L2,English Core Level 2,1-1,My School📊 Vocabulary Import 格式規格
ZIP 壓縮包結構規範
text
vocabulary_bundle.zip
├── vocabulary.csv
├── images/
└── audio/vocabulary.csv 首版候選欄位
此表是待工程核定的 APlus 匯入契約，不代表既有解析程式已支援。原 Nihao「拼音」「筆順GIF」不列入新格式；「英文翻譯」改成中文釋義，學習內容本身為英文。若工程需讀舊檔，另確認轉換規則，不讓舊欄位重新成為必填。
| 欄位名稱 (Column) | 必填 | 說明 | 範例 |
|---|---|---|---|
| category_id | 是 | 已存在的課程分類 | CORE |
| level_code | 是 | 已存在的級別 | CORE_L1 |
| session_id | 是 | 級別內單元 | 1-1 |
| language | 是 | 英語學習內容 | en |
| content_type | 是 | Word／Phrase／Sentence | Word |
| english_content | 是 | 英文目標內容 | five |
| chinese_meaning | 否 | 繁體中文釋義，是否逐項必填待教材確認 | 五 |
| image_file | 依題型 | 圖片檔名，圖片不得用文字直接透露答案 | number_5.png |
| audio_file | 依題型 | 英文標準音訊 | five.mp3 |
| is_qa | 是 | 是否使用既有快問快答題型 | false |
| qa_question | QA 時 | 英文固定題庫問句 | How many are there? |
| qa_audio_file | QA 時 | 問句英文音訊 | how_many.mp3 |
| alternative_answers | 否 | 可接受英文答案，分隔規則待匯入器確認 | There are five. |
CSV 範本內容
csv
category_id,level_code,session_id,language,content_type,english_content,chinese_meaning,image_file,audio_file,is_qa,qa_question,qa_audio_file,alternative_answers
CORE,CORE_L1,1-1,en,Word,five,五,number_5.png,five.mp3,false,,,
CORE,CORE_L1,1-1,en,Sentence,There are five.,有五個,number_5.png,there_are_five.mp3,true,How many are there?,how_many.mp3,Five.首版不顯示音標，因此不新增必填音標欄位；音素／重音診斷也不據此視為已接入。上述格式須以真實教材樣本通過匯入、預覽與學生題型驗收後才定稿。
💡 導入注意事項 (Expert Tips)
- 檔案編碼： 務必使用 UTF-8 (帶 BOM) 格式儲存 CSV，確保英文與繁中釋義均正確顯示。
- 媒體路徑對應： CSV 內只需填寫「檔名」，系統會自動解壓 ZIP 並去對應文件夾尋找：/images/ 存放圖片，/audio/ 存放所有音檔，首版課程媒體只使用 /images/ 與 /audio/；舊 CSV/schema 拼音欄位／筆順等舊欄位不作為學生端學習內容。
- 依賴關係 (關鍵)： 必須先導入 Structure 建立對應的 category_id, level_code 與 session_id，再導入 Vocabulary Bundle。
- 更新與跳過邏輯： 單字更新：若系統已存在相同 english_content + content_type 的單字，導入時會比對其他欄位，若有變動則標記為 UPDATE。架構跳過：若 ID 已存在則標記為 SKIP，不會覆蓋已有的架構名稱。
- 媒體缺失檢查： 系統在 A-33 預覽時，會自動校驗 ZIP 內的文件夾。若 CSV 中寫了檔名但在文件夾中找不到文件，會標記為 MISSING MEDIA 警告，不可導入。
🔁 完整交互路徑
- 進入： 在 A-30 點擊頂部的 [⤒ Bulk Import] 按鈕。
- 選擇與上傳 (A-33-O)： 選擇導入類型 → 下載 Template → 拖入填寫好的文件 → 點擊 Analyze & Preview。
- 校驗預覽 (A-33)： 查看 NEW, SKIP, UPDATE, ERROR 狀態 → 確認無誤後點擊 Confirm。
- 完成： 系統返回 A-32 (單字列表)，顯示剛剛導入的新內容。
🔎 邏輯自我檢查
- 安全優先： 透過 SKIP 邏輯保護架構不被意外修改，透過 ERROR 攔截無效的單字歸屬。
- 媒體閉環： ZIP 解包校驗解決了以前「數據導入成功但圖片顯示 404」的痛點。
- 層級對應： 加入了 category_id 的顯示，確保管理員不會把 EK 的單字錯入到 ES 的 Level 裡。