給老師使用的教學管理平台：課程、數位遊戲、AI 出題、學生管理、行事曆、即時課堂互動、成效報表，並支援多位老師共用同一個工作區。前端是 Next.js（App Router），後端資料庫、驗證、即時通訊全部走 Supabase；另有一個獨立部署的遊戲引擎子專案（game-engine/），透過 Vercel 的 Multi-Zones rewrite 掛在同一個網域的 /games 底下。
這份 README 是依照目前實際的程式碼結構重新整理的（原本的版本內容已經過時，例如引用不存在的 .env.example、只提到 lesson-ordering 這一項小功能）。
專案結構
這是一個 monorepo，包含兩個各自獨立部署的 Next.js 專案：
mind-ai-tutor/
├── app/ # 主站（教師端）— App Router 頁面與 API routes
│ ├── components/ # 共用 React 元件（ui/ 為 shadcn 風格基礎元件）
│ ├── contexts/ # React Context（語系、行事曆）
│ └── hooks/ # 共用 hooks
├── lib/ # 非 UI 的共用邏輯：Supabase client、Gemini、翻譯字串、匯出工具等
├── types/ # 型別定義（Supabase 產生的型別、第三方套件宣告）
├── supabase/ # 所有資料庫 SQL，見下方「資料庫設定」
│ ├── migrations/ # 新的增量 migration（依時間戳記命名）
│ └── scripts/ # 較早期、手動在 SQL Editor 執行的 SQL 與其測試
├── public/ # 靜態資源（品牌圖、字型、pdf.js worker、模型檔）
├── docs/ # 設計文件、驗收紀錄、Email 樣板
├── proxy.ts # 全站身份驗證守門
├── next.config.ts # 安全性標頭（CSP 等）+ /games 的 Multi-Zones rewrite
└── game-engine/ # 獨立部署的遊戲引擎子專案，見 game-engine/README.md
game-engine/ 是完全獨立的 Next.js 專案，在 Vercel 上是另一個 Project、另一個網域，basePath 設成 /games。主站透過 next.config.ts 的 rewrites() 把 mindaitutor.com/games/* 轉發過去，讓學生感覺是同一個網站；兩邊各自有各自的 package.json、部署流程、環境變數。詳細說明見 game-engine/README.md。
核心功能
- 身份驗證：Email/密碼登入、Google OAuth、忘記密碼／重設密碼、Supabase Auth 管理
- 學生管理：學生資料、進度、出席、作業紀錄
- 課程管理（Lessons）：建立、編輯教材內容
- 數位遊戲（Digital Games）：資料驅動的遊戲引擎，關卡內容、順序、AI 助教提示詞、獎勵設定都可在教師端調整，不用改遊戲引擎程式碼
- AI 測驗（AI Quiz）：用 Gemini 產生測驗題目、練習題、學習分析，可分享公開連結讓學生作答
- 課堂即時模式（Live Session）：老師開一場即時課堂，投影片＋投票／問答／即時反應，學生用代碼加入，不需要帳號
- 行事曆（Events）：活動排程，支援標籤、狀態、優先順序篩選
- 學生反饋（Feedback）：老師與家長／學生之間的意見往來
- 活動紀錄（Activities）：系統通知與異動紀錄
- 數據分析（Reports）：學習時間分佈、完成率、學習時間軸、分類統計、AI 互動分佈
- 工作區（Team Workspace）：一個帳號可以建立/加入一個工作區，邀請其他老師共用課程與活動；既有資料預設不共用，需要老師手動選擇分享
- 系統管理（Admin）：管理員專用的後台
- 多語系：繁體中文／English 切換
- 多裝置：手機版與桌機版分開優化過的導覽/版面
技術棧
- 框架：Next.js（App Router）、React、TypeScript
- UI：Tailwind CSS、Radix UI（shadcn/ui 風格元件）、lucide-react 圖示
- 後端／資料庫：Supabase（Postgres + Auth + Row Level Security + Realtime）
- AI：Google Gemini（
@google/genai），伺服器端呼叫，API 金鑰不外流到瀏覽器
- 狀態管理：React Context、TanStack Query
- 資料視覺化：Chart.js、Recharts、Nivo
- 文件匯出：PDF（jsPDF/html2pdf）、DOCX、PPTX（pptxgenjs）、Excel（exceljs）
- 測試：Vitest + Testing Library
- 部署：Vercel（主站與
game-engine/ 各自獨立部署）
快速開始
前置需求
- Node.js 24.x（見
package.json 的 engines 欄位）
- npm（專案用的是
package-lock.json，不是 yarn/pnpm）
- 一個 Supabase 專案
安裝
git clone <repository-url>
cd mind-ai-tutor
npm install
環境變數
專案目前沒有附 .env.example，請在根目錄自行建立 .env.local，內容依需求包含：
# Supabase（必填）
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY= # 僅伺服器端使用，例如 /api/team/invite 寄邀請信
# Gemini AI（AI 測驗／學習分析等功能需要）
GEMINI_API_KEY=
GEMINI_MODEL= # 選填，未設定則用程式內建預設值
GEMINI_IMAGE_MODEL= # 選填，遊戲封面生成用
# 數位遊戲子專案（game-engine/）
NEXT_PUBLIC_GAME_ENGINE_URL= # 教師端「開始遊戲」按鈕要連去的網域
GAME_ENGINE_ORIGIN= # 選填，/games 的 rewrite 目標；未設定預設指向正式站
# 其他選填
AI_GAME_COVERS_ENABLED= # 是否開放 AI 生成遊戲封面
LIVE_PREVIEW_DIR=
SUPABASE_SERVICE_ROLE_KEY 擁有繞過 RLS 的權限，絕對不能加 NEXT_PUBLIC_ 前綴、也不能出現在任何 client component 裡。
開發
npm run dev
打開 http://localhost:3000。
測試與檢查
npm test # vitest run
npx tsc --noEmit -p . # TypeScript 型別檢查
npm run lint # next lint
npm run build # production build
資料庫設定
所有 SQL 都放在 supabase/ 底下，手動貼到 Supabase SQL Editor 執行（專案沒有接 Supabase CLI 自動部署）：
supabase/migrations/ — 新的 schema 變更一律放這裡，檔名以時間戳記開頭（例如 20261002020000_add_learning_analysis_reports.sql），照檔名順序執行。supabase/scripts/ — 較早期的 SQL。每個檔案都寫成可以重複執行（create table if not exists、create or replace function、drop policy if exists 再 create policy 之類的寫法）；inspect_*.sql、set_user_admin.sql 這類是查詢／維運用的工具腳本，不是 schema 變更。
supabase/scripts/ 裡核心表格（profiles、students、events、team workspace 等）用得到的檔案包括：
create_profiles_table.sql、create_missing_tables.sql — 基礎表格add_owner_scoping_*.sql、fix_*_rls.sql — 各表的 Row Level Securityadd_team_workspaces.sql、add_team_scoping_events.sql、fix_team_function_privileges.sql — 工作區共編功能add_live_sessions.sql、add_live_session_phase2.sql — 課堂即時模式add_ai_quizzes.sql、add_ai_quiz_sharing.sql — AI 測驗add_public_game_manifest.sql、add_game_cover_*.sql — 數位遊戲引擎（game-engine/ 讀取用）harden_game_student_data.sql、fix_ux_review_findings.sql — 安全性強化
supabase/scripts/ 裡的 .test.ts 是對應 SQL 檔的 Vitest 測試（用 PGlite 在記憶體裡執行 SQL，不連正式資料庫），例如 supabase/scripts/add_live_sessions.test.ts。
部署
主站與 game-engine/ 是 Vercel 上兩個獨立的 Project：
- 主站（這個資料夾）：Root Directory 留空，
vercel.json 裡有基本安全性標頭；更完整的 CSP 等標頭是在 next.config.ts 的 headers() 設定。
game-engine/：Vercel Root Directory 指向 game-engine/，basePath 設 /games，各自獨立網域。
主站的 next.config.ts 用 rewrites() 把 /games/* 轉發到 GAME_ENGINE_ORIGIN（未設定時預設指向正式站網址），讓兩個 Vercel 部署在使用者看起來像同一個網站。
文件
docs/ 資料夾底下有各功能的設計文件與驗收紀錄，例如 live-session-design.md（課堂即時模式）、team-workspace-design.md（工作區共編）、admin-overview.md（後台）、email-templates/（Supabase Auth 信件樣板）等，改動相關功能前建議先看一下對應文件。
授權
MIT License。
