官方使用手冊

教師儀表板
使用手冊

本手冊說明如何設定帳號權限、建立班級分組、讓每位老師只能看見並互動 自己班級的學生，確保師生資料隔離與安全。

閱讀時間：約15分鐘
最後更新：2025-04-23
版本：v1.0
系統架構總覽
Section 1
整體資料結構關係圖
┌─────────────────────────────────────────────────────┐
│                   users 資料表                       │
│  ┌─────────────┐      ┌─────────────┐               │
│  │ role=admin  │      │role=full_   │               │
│  │ （管理員）   │      │access（老師）│               │
│  └──────┬──────┘      └──────┬──────┘               │
│         │                   │                       │
│         ▼                   ▼                       │
│  ┌──────────────────────────────────┐               │
│  │        class_groups 資料表        │               │
│  │   teacher_id ──► 老師的 user.id  │               │
│  │   student_ids ──► [學生ID列表]   │               │
│  └──────────────────┬───────────────┘               │
│                     │                               │
│                     ▼                               │
│  ┌─────────────────────────────────┐                │
│  │  users (role=study_zone/oral)   │                │
│  │        學生帳號                  │                │
│  └─────────────────────────────────┘                │
└─────────────────────────────────────────────────────┘

資料流：
老師登入 → 讀取 class_groups（teacher_id = 自己）
        → 只看到自己班級的 student_ids
        → 只查詢這些學生的 activity_log / student_progress
        → 只發送訊息給這些學生
💡
核心設計原則 老師的資料隔離是透過 class_groups.teacher_id 來實現的。 每位老師登入後，系統只查詢 teacher_id = 自己ID 的班級， 再從班級的 student_ids 清單取出學生，確保老師看不到其他班級的資料。
涉及的五張資料表
資料表用途關聯欄位
users所有帳號（管理員、老師、學生）id, role
class_groups班級定義，記錄哪位老師帶哪些學生teacher_id → users.id
student_progress學生學習進度（streak、分數等）id = users.id
activity_log每次學習活動的詳細紀錄student_id → users.id
teacher_messages老師發送給學生的訊息teacher_id, target_id
weekly_tasks老師設定的本週學習任務teacher_id, class_id
角色與權限設計
Section 2
⚙️ admin
系統管理員
負責建立所有帳號、設定班級、指派老師。通常是學校英文組長或系統負責人。
建立/刪除所有帳號
查看全部學生資料
建立/編輯班級
指派老師到班級
存取教師儀表板
存取管理員後台
🎓 full_access
老師
英文老師，只能看到並互動自己班級的學生。不能看到其他老師的班級。
存取教師儀表板
查看自己班級學生
發送訊息給自己學生
設定本週任務
匯出自己班報告
存取管理員後台
📚 study_zone
國高中學生
使用 student.html 學習平台的學生。只能看到自己的學習紀錄，不能看其他人的。
進入學習專區
接收老師訊息
查看自己進度
教師儀表板
管理員後台
看其他學生資料
🎤 oral_practice
口說練習學生
只能使用口說對話功能（chat.html）的學生，通常是口說加強班或一對一練習。
進入 AI 對話頁面
接收老師訊息
學習專區（需另外開放）
教師儀表板
管理員後台
功能權限矩陣
功能 admin full_access
(老師)		 study_zone
(學生)		 oral_practice
(學生)
🎓 教師儀表板（自己班級）✅✅——
📊 查看全部班級資料✅———
💬 發訊息給自己學生✅✅——
📢 全校廣播訊息✅———
✅ 發布本週任務✅✅——
📥 匯出 CSV 報告✅⚡ 自班——
⚙️ 管理員後台✅———
👤 建立/刪除帳號✅———
📚 學習專區✅✅✅—
🎤 口說對話✅✅—✅
📨 接收老師訊息——✅✅
⚡ 部分權限：只能操作自己負責的班級資料
第一步：建立帳號
Section 3 · 由管理員操作
⚠️
需要管理員操作 以下步驟需以 admin 角色登入後，進入「管理員後台」(admin.html) 才能執行。
1
建立老師帳號
在管理員後台新增帳號，角色選擇 full_access。
帳號設定範例：
帳號（username）：teacher_wang
顯示名稱（display_name）：王大明老師
密碼：設定初始密碼（建議之後請老師自行更改）
角色（role）：full_access ← 這個是老師的角色
狀態（status）：active
💡 角色說明
老師的角色是 full_access，不是 admin。
admin 只給系統管理員（通常是英文組長或資訊老師）。
一個學校可以有多位老師（full_access），但 admin 建議只有 1~2 人。
2
建立學生帳號
每位學生建立一個帳號，角色選擇 study_zone（學習專區）或 oral_practice（口說練習）。
帳號設定範例（學生）：
帳號（username）：student_b11001 ← 建議用學號
顯示名稱（display_name）：陳小明
密碼：初始密碼（如生日 0915 或學號後4碼）
角色（role）：study_zone ← 一般學生
狀態（status）：active
備注（note）：高一忠班 座號01 ← 方便管理
📋
批量建立帳號技巧 如果有 30 位學生，可以用統一格式：
帳號：b11001 ~ b11030（班級+座號）
初始密碼：統一設為 wayne123，學生首次登入後自行更改
備注欄：填入班級座號，方便之後設定班級時查找
3
記錄每位老師和學生的系統 ID
建立帳號後，系統會自動產生唯一 ID（UUID格式）。這個 ID 是之後設定班級時的關鍵。
如何找到 ID：
1. 在管理員後台，點選該帳號的「詳情」
2. 或透過 API 查詢：GET tables/users?search=teacher_wang
3. 找到 "id" 欄位，如：
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

📌 建議：把老師和學生的 ID 記在試算表上，
方便後續建立班級時使用。
第二步：設定班級分組
Section 4 · 由管理員操作

班級設定儲存在 class_groups 資料表。每個班級記錄「哪位老師」負責「哪些學生」， 這是實現老師資料隔離的關鍵。

建立班級的方法（透過 Admin 後台）
A
開啟管理員後台 → 班級管理
登入後進入 admin.html，找到「班級管理」區塊（若尚未有此頁面，可使用 API 直接建立）
直接透過 API 建立班級（推薦方式）
// 建立高一忠班（透過瀏覽器 Console 或 Postman） fetch('tables/class_groups', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ id: 'class_senior1A', // 自訂班級ID（英數字） class_name: '高一忠班', grade: 'senior1', teacher_id: '老師的UUID', // ← 填入老師的 users.id teacher_name: '王大明老師', student_ids: [ // ← 填入所有學生的 users.id '學生A的UUID', '學生B的UUID', '學生C的UUID' ], description: '113學年度高一忠班英文', is_active: true }) });
✅
完成後效果 老師 teacher_wang 登入教師儀表板後，班級下拉選單只會出現「高一忠班」， 學生清單也只顯示 student_ids 中列出的學生。
grade 年級代碼對照表
代碼說明對應課程
elementary國小elementary.html 國小英語學習樂園
junior1國中一年級student.html（國中模式）
junior2國中二年級student.html（國中模式）
junior3國中三年級（會考）student.html（國中模式）
senior1高中一年級student.html（高中模式）
senior2高中二年級student.html（高中模式）
senior3高中三年級（學測）student.html（高中模式）
📌 實際案例：一位老師帶兩個班
老師：林美慧老師（teacher_lin）
負責班級一：高二仁班（30名學生）
負責班級二：高二義班（28名學生）

建立兩筆 class_groups：
→ class_senior2B：teacher_id = teacher_lin 的ID，student_ids = [30個學生ID]
→ class_senior2C：teacher_id = teacher_lin 的ID，student_ids = [28個學生ID]

林老師登入後，班級選單出現「高二仁班」、「高二義班」兩個選項。
第三步：綁定師生關係
Section 5
完整資料設定流程
admin 建立
老師帳號
admin 建立
學生帳號
記錄所有人
的 ID
建立
class_groups
填入
teacher_id
填入
student_ids
老師登入
儀表板
只看到
自己的班級
只能互動
自己的學生
新增學生到現有班級（學期中轉班）
// 取得現有班級資料，再加入新學生 // 步驟一：取得目前的 student_ids const r = await fetch('tables/class_groups/class_senior1A'); const cls = await r.json(); const currentIds = cls.student_ids || []; // 步驟二：加入新學生 const newIds = [...currentIds, '新學生的UUID']; // 步驟三：更新班級 fetch('tables/class_groups/class_senior1A', { method: 'PATCH', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ student_ids: newIds }) });
從班級移除學生（轉班、退學）
// 移除特定學生的 ID const newIds = currentIds.filter(id => id !== '要移除的學生UUID'); fetch('tables/class_groups/class_senior1A', { method: 'PATCH', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ student_ids: newIds }) }); // ⚠️ 注意：移除學生只是把他從班級移出 // 不會刪除學生的帳號或學習紀錄
權限隔離機制說明
Section 6 · 技術說明
teacher.html 隔離機制（程式碼說明）
// teacher.html 登入後的資料載入流程： // 1. 取得登入老師的 ID const sess = getSession(); const teacherId = sess.id; // 老師自己的 ID // 2. 只載入「自己負責」的班級 const r = await fetch(`tables/class_groups?limit=50`); const allClasses = await r.json(); // 3. 過濾：只保留 teacher_id = 自己的班級 const myClasses = allClasses.data.filter(c => c.teacher_id === teacherId); // ↑ 其他老師的班級在這裡被過濾掉了 // 4. 從自己的班級取出學生ID清單 const myStudentIds = myClasses.flatMap(c => c.student_ids); // 5. 只查詢這些學生的資料 const allUsers = await fetch('tables/users?limit=200'); const myStudents = allUsers.data.filter(u => myStudentIds.includes(u.id)); // ↑ 其他班級的學生在這裡被過濾掉了 // 結論：老師只能看到 myStudents 這份清單
⚠️
重要：這是前端過濾，不是後端權限控制 目前的隔離機制是在前端 JavaScript 進行過濾。技術上，有能力的人可以透過瀏覽器直接呼叫 API 取得其他班級資料。 如果需要完整的後端權限控制，需要在遷移到 GCP 後使用 Firebase Rules 或 Cloud Functions 實作。 對於學校內部使用，前端隔離已足夠。
admin 與老師看到的差異
功能admin 看到老師（full_access）看到
班級選單全校所有班級只有自己的班級
學生清單全校所有學生只有自己班級的學生
訊息發送對象全校學生 + 全班廣播只有自己班級的學生
學習紀錄全校學習紀錄只有自己學生的紀錄
報告匯出全校報告只有自己班級報告
任務發布全校 / 指定班級只限自己的班級
班級總覽操作說明
Section 7
儀表板各區塊說明
區塊說明更新頻率
班級學生人數class_groups.student_ids 的總數即時
本週活躍人數7天內有 last_study_date 紀錄的學生數重新整理時更新
全班平均分數student_progress.total_score 的平均值重新整理時更新
需要關注學生超過3天沒有學習紀錄的學生（紅色警示）重新整理時更新
每日學習人數本週每天的學習人數趨勢（Bar 圖）重新整理時更新
積分排行榜本班學生 total_score 降冪排列重新整理時更新
模組使用分布文法/單字/閱讀等各模組使用比例圓餅圖重新整理時更新
需要關注的學生警示
🔴 從未使用
帳號建立後從未登入，可能需要告知學生帳號資訊或確認帳號是否正確
⚠️ 超過3天未學習
近期沒有學習紀錄，建議發送「學習提醒」訊息給該學生
發送訊息給學生
Section 8
五種訊息類型說明
類型適用情境建議用語
💪 加油鼓勵 學生最近分數下滑、許久未登入 「這週加油哦！每天練習10分鐘就夠了！」
⭐ 讚美表揚 學生本週進步、達成任務、連續學習 「你這週的文法進步好多！繼續保持！」
📢 學習提醒 考試前、重要單元、定期學習提醒 「下週考時態，記得多練習完成式！」
📋 任務指派 搭配本週任務功能使用，告知任務內容 「本週任務已發布，請完成5次文法練習！」
📌 公告通知 班級公告、系統維護、課程異動 「本週四無課，請提前完成本週學習進度。」
發送訊息步驟
1
選擇發送對象
「全班廣播」：發給自己班級的所有學生
「個別學生」：從下拉選單選擇特定學生（只顯示自己班級的學生）
2
填寫訊息內容
選擇訊息類型 → 填入標題 → 填入內容 → 選擇表情符號 → 設定到期日（可選）
3
學生何時看到？
學生下次登入 student.html 後，約 2 秒後右側會自動彈出訊息通知面板。 學生點「已讀」後，訊息不再出現。
💡
快速發送提醒：從警示清單直接發送 在「班級總覽」的「需要關注的學生」區塊，每位學生右側都有「發送提醒」按鈕， 點擊後會自動切換到「發送訊息」頁面並帶入該學生，省去手動選擇的步驟。
設定本週任務
Section 9
任務設定欄位說明
欄位說明範例
任務標題學生看到的任務名稱本週文法衝刺！
任務說明詳細描述任務要求請完成「時態」和「被動語態」各一次練習
指定模組限定哪個學習模組（可選「任意模組」）grammar（文法）
目標次數學生需完成幾次練習5 次
目標分數每次練習需達到的分數70 分以上
開始日任務開始日期2025-04-28（週一）
截止日任務截止日期2025-05-04（週日）
指定班級只有此班級的學生需完成高一忠班
📌 設定範例：學測衝刺任務
標題：「學測最後衝刺！本週閱讀任務」
說明：「請完成學測閱讀測驗練習，每次需達70分以上，本週至少完成3次。加油！」
模組：閱讀（reading）
目標次數：3 次  |  目標分數：70 分
期間：2025-04-28 ～ 2025-05-04
班級：高三甲班
✅
建議搭配訊息功能使用 發布任務後，同時發送一則「📋 任務指派」類型的訊息給學生， 讓學生登入時立即看到任務通知，提高完成率。
匯出學習報告
Section 10
CSV 匯出內容說明
CSV 欄位順序： 姓名, 帳號, 累計分數, 單字量, 連續天數, 等級, 上次學習日期 範例資料： 陳小明, b11001, 1580, 45, 7, senior, 2025-04-23 林大華, b11002, 820, 28, 3, junior, 2025-04-21 王美玲, b11003, 2100, 67, 14, senior, 2025-04-23
如何使用匯出的 CSV
  • 用 Excel 或 Google Sheets 開啟（注意選 UTF-8 編碼，避免中文亂碼）
  • 依「累計分數」排序，了解班級整體程度分布
  • 找出「上次學習日期」超過一週的學生，進行個別輔導
  • 作為學期平時成績的參考依據
  • 每月固定匯出一次，追蹤全班進步趨勢
資料表欄位完整說明
Section 11 · 技術參考
users — 帳號資料表
欄位名稱類型說明必填
idtext系統自動產生的唯一ID（UUID）自動
usernametext登入帳號（建議用學號，如 b11001）必填
password_hashtextSHA-256 加密後的密碼（由系統處理）必填
display_nametext顯示名稱（中文名字）必填
roletext角色：admin / full_access / study_zone / oral_practice必填
statustext帳號狀態：active / suspended必填
emailtext電子郵件（選填）選填
avatar_keytext頭像設定（study/daily/admin）選填
last_logindatetime最後登入時間（系統自動更新）自動
login_countnumber累計登入次數（系統自動累加）自動
notetext管理員備注（如：高一忠班 座號01）選填
class_groups — 班級資料表（最重要）
欄位名稱類型說明必填
idtext班級唯一ID（自訂，如 class_senior1A）⭐ 關鍵
class_nametext班級名稱（如：高一忠班）必填
gradetext年級代碼（見 Section 4）必填
teacher_idtext⭐ 老師的 users.id（這決定哪位老師管這個班）⭐ 關鍵
teacher_nametext老師顯示名稱（方便查看）必填
student_idsarray⭐ 學生 users.id 的陣列（這決定老師看哪些學生）⭐ 關鍵
descriptiontext班級說明（如：113學年度高一英文）選填
is_activebool是否啟用（false=停用，學期結束後設為 false）必填
activity_log — 學習活動記錄（自動產生）
欄位名稱說明
student_id學生的 users.id
student_name學生顯示名稱
module模組：grammar / vocab / reading / listening / exam / music / game / chat
action動作：start（開始）/ complete（完成）/ score（得分）/ login（登入）
topic題目或活動名稱（如：時態綜合、Shape of You）
score本次得分
max_score滿分
duration_sec學習時長（秒）
log_date記錄日期 YYYY-MM-DD
ℹ️
此資料表由學生端 student.html 自動寫入，管理員和老師無需手動操作。
常見問題 FAQ
Section 12
❓ 老師登入後看不到任何學生？
原因：class_groups 沒有設定，或 teacher_id 填錯了。
解法：
  1. 確認 class_groups 資料表有該老師的班級記錄
  2. 確認 teacher_id 填的是老師的 users.id（UUID格式），不是 username
  3. 確認 is_active = true
  4. 請老師重新登入，或按「重新整理」按鈕
❓ 學生的學習進度沒有顯示在老師儀表板？
原因：student_progress 資料表沒有該學生的記錄。
解法：
  1. 學生需要先登入 student.html 並完成至少一次學習活動
  2. 進度每60秒自動同步一次，請等待後重試
  3. 確認學生帳號的 id 與 class_groups.student_ids 中的 ID 一致
❓ 老師發送的訊息學生沒收到？
可能原因：
  1. 學生尚未登入（訊息在下次登入後才會出現）
  2. 訊息的 target_id 填錯（確認是學生的 users.id）
  3. 訊息已過期（expire_date 已過）
  4. 學生已點「已讀」（is_read = true）
❓ 如何新增一位老師？
步驟：
  1. admin 登入 admin.html
  2. 建立新帳號，role 設為 full_access
  3. 記下新老師帳號的 users.id
  4. 建立或更新 class_groups，將 teacher_id 設為新老師的 ID
  5. 新老師即可登入 teacher.html 看到自己的班級
❓ 學期結束後如何處理舊班級？
建議做法：
  1. 將舊班級的 is_active 設為 false（不要刪除，保留歷史紀錄）
  2. 建立新學期的班級（新的 class_groups 記錄）
  3. 學生帳號保留，進度累積，不需重新建立
  4. 視需要更新學生的 class_id 對應關係
❓ 可以讓一位學生同時屬於兩個班級嗎？
可以。只需在兩個 class_groups 的 student_ids 中都加入該學生的 ID。
例如：一位學生同時在「一般英文班」和「口說加強班」，兩位老師都可以在自己的儀表板看到他。
快速設定清單
Section 13 · 學期初必做
學期初設定 Checklist
  • 建立 admin 帳號 — 系統負責人，role = admin
  • 建立老師帳號 — 每位英文老師一個帳號，role = full_access
  • 建立學生帳號 — 每位學生一個，role = study_zone，建議用學號當 username
  • 記錄所有帳號的 ID — 從 admin.html 或 API 取得 users.id（UUID格式）
  • 建立班級（class_groups） — 填入 teacher_id 和 student_ids
  • 測試老師登入 — 確認教師儀表板能看到正確班級和學生
  • 測試學生登入 — 確認能進入學習專區，完成一次練習
  • 測試訊息功能 — 老師發送測試訊息，確認學生登入後能看到
  • 發布使用說明給學生 — 告知學生帳號、密碼、登入網址
  • 設定第一週任務 — 讓學生有明確的學習目標
每週建議操作
時間操作目的
週一早上發布本週任務 + 全班鼓勵訊息設定學習目標，提高動機
週三查看班級總覽，找出未學習學生及時發提醒訊息
週五查看本週完成進度，讚美表現好的學生正向回饋，強化習慣
月底匯出 CSV 報告，記錄學習成果作為平時成績依據
🎉
設定完成！ 完成以上設定後，老師就能在教師儀表板看到自己班級學生的完整學習狀況， 並透過訊息和任務與學生互動，打造更緊密的師生學習關係。
需要協助？
如遇到問題，可聯絡系統管理員，或讓 AI 助理幫您建立帳號和設定班級。