# DramaLing 專案資料夾結構指南 ## 完整目錄結構 ``` dramaling-vocab-learning/ ├── 📁 .claude/ # Claude AI 配置 │ └── CLAUDE.md # AI 助手指引文件 │ ├── 📁 .github/ # GitHub 配置 │ └── workflows/ # GitHub Actions │ ├── ci.yml # CI 流程 │ └── deploy.yml # 部署流程 │ ├── 📁 docs/ # 專案文檔 │ ├── 00_starter/ # 啟動文檔 │ ├── 01_requirement/ # 需求文檔 │ ├── 02_design/ # 設計文檔 │ ├── 03_development/ # 開發文檔 │ ├── 04_testing/ # 測試文檔 │ ├── 05_deployment/ # 部署文檔 │ └── 06_project-management/ # 專案管理 │ ├── 📁 public/ # 靜態資源 │ ├── images/ # 圖片資源 │ ├── fonts/ # 字體檔案 │ └── favicon.ico # 網站圖標 │ ├── 📁 app/ # Next.js App Router (根目錄) │ ├── login/ # 登入頁面 │ ├── register/ # 註冊頁面 │ ├── dashboard/ # 主儀表板 │ ├── flashcards/ # 詞卡管理 │ ├── learn/ # 學習頁面（複習系統） │ ├── generate/ # AI 生成詞卡頁面 │ │ │ │ ├── api/ # API 路由 │ │ ├── auth/ # 認證 API │ │ ├── flashcards/ # 詞卡 API │ │ ├── ai/ # AI 生成 API │ │ ├── stats/ # 統計 API │ │ └── tags/ # 標籤 API │ │ │ ├── layout.tsx # 根佈局 │ ├── page.tsx # 首頁（Landing Page） │ ├── globals.css # 全域樣式 │ └── not-found.tsx # 404 頁面 │ │ ├── 📁 components/ # React 組件（根目錄） │ │ ├── ui/ # UI 基礎組件 │ │ │ ├── button.tsx │ │ │ ├── card.tsx │ │ │ ├── dialog.tsx │ │ │ ├── input.tsx │ │ │ ├── label.tsx │ │ │ ├── select.tsx │ │ │ ├── separator.tsx │ │ │ ├── skeleton.tsx │ │ │ ├── toast.tsx │ │ │ └── ... │ │ │ │ │ ├── layout/ # 佈局組件 │ │ │ ├── header.tsx # 頁首 │ │ │ ├── sidebar.tsx # 側邊欄 │ │ │ ├── footer.tsx # 頁尾 │ │ │ └── navigation.tsx # 導航 │ │ │ │ │ ├── flashcard/ # 詞卡相關組件 │ │ │ ├── flashcard-item.tsx │ │ │ ├── flashcard-list.tsx │ │ │ ├── flashcard-form.tsx │ │ │ └── flashcard-review.tsx │ │ │ │ │ ├── auth/ # 認證組件 │ │ │ ├── login-form.tsx │ │ │ ├── register-form.tsx │ │ │ └── auth-guard.tsx │ │ │ │ │ └── providers/ # Context Providers │ │ ├── auth-provider.tsx │ │ ├── theme-provider.tsx │ │ └── query-provider.tsx │ │ ├── 📁 lib/ # 工具函數庫（根目錄） │ │ ├── supabase/ # Supabase 配置 │ │ │ ├── client.ts # 客戶端 │ │ │ ├── server.ts # 伺服器端 │ │ │ └── admin.ts # 管理員客戶端 │ │ │ │ │ ├── ai/ # AI 相關 │ │ │ ├── gemini.ts # Gemini 配置 │ │ │ └── prompts.ts # Prompt 模板 │ │ │ │ │ ├── utils/ # 工具函數 │ │ │ ├── cn.ts # Class names │ │ │ ├── format.ts # 格式化函數 │ │ │ ├── validation.ts # 驗證函數 │ │ │ └── sm2.ts # SM-2 演算法 │ │ │ │ └── constants.ts # 常數定義 │ ├── 📁 hooks/ # 自定義 Hooks（根目錄） │ ├── use-auth.ts # 認證 Hook │ ├── use-flashcards.ts # 詞卡 Hook │ ├── use-toast.ts # Toast Hook │ └── use-debounce.ts # 防抖 Hook │ ├── 📁 types/ # TypeScript 類型（根目錄） │ ├── database.ts # 資料庫類型 │ ├── flashcard.ts # 詞卡類型 │ ├── user.ts # 用戶類型 │ ├── api.ts # API 類型 │ └── supabase.ts # Supabase 類型 │ ├── 📁 store/ # 狀態管理（根目錄） │ ├── auth-store.ts # 認證狀態 │ ├── flashcard-store.ts # 詞卡狀態 │ └── ui-store.ts # UI 狀態 │ ├── 📁 tests/ # 測試檔案 │ ├── unit/ # 單元測試 │ ├── integration/ # 整合測試 │ └── e2e/ # E2E 測試 │ ├── 📁 scripts/ # 腳本檔案 │ ├── seed.ts # 資料播種 │ ├── migrate.ts # 資料庫遷移 │ └── backup.ts # 備份腳本 │ ├── 📄 配置檔案 ├── .env.local # 環境變數（本地） ├── .env.example # 環境變數範例 ├── .eslintrc.json # ESLint 配置 ├── .gitignore # Git 忽略檔案 ├── .prettierrc # Prettier 配置 ├── components.json # shadcn/ui 配置 ├── middleware.ts # Next.js 中間件 ├── next-env.d.ts # Next.js 類型定義 ├── next.config.mjs # Next.js 配置 ├── package.json # 專案依賴 ├── postcss.config.mjs # PostCSS 配置 ├── tailwind.config.ts # Tailwind 配置 ├── tsconfig.json # TypeScript 配置 └── vercel.json # Vercel 配置 ``` ## 專案結構說明（根據實際實作） > **注意**: 本專案將主要程式碼放置在根目錄而非 `/src` 資料夾中 ## 資料夾用途說明 ### /app Next.js 13+ App Router 的核心目錄，包含所有頁面和 API 路由。位於專案根目錄。 **命名規範**： - 使用小寫和連字符 - 括號 `()` 用於路由分組（不影響 URL） - 方括號 `[]` 用於動態路由 **實際實作檔案**： - `page.tsx`: 首頁 Landing Page - `layout.tsx`: 根佈局，包含全站基本設定 - `login/page.tsx`: 登入頁面 - `register/page.tsx`: 註冊頁面 - `dashboard/page.tsx`: 儀表板頁面 - `flashcards/page.tsx`: 詞卡管理頁面 - `learn/page.tsx`: 學習頁面（多種測驗模式） - `generate/page.tsx`: AI 生成詞卡頁面 ### /components 可重用的 React 組件，位於專案根目錄。 **組織原則**： - `ui/`: shadcn/ui 基礎組件（使用 shadcn/ui 自動生成） - 業務組件按功能分組（待實作） - 佈局組件整合在頁面中 **實際實作組件**： - 目前組件邏輯直接整合在各頁面檔案中 - 使用 React Hooks 管理狀態（useState, useEffect） - 採用 Tailwind CSS 進行樣式設計 ### /lib 不含 React 的純 JavaScript/TypeScript 工具，位於專案根目錄。 **內容**： - `utils.ts`: 工具函數（如 cn 函數） - 第三方服務配置（待實作） - 常數定義（待實作） ### /hooks 自定義 React Hooks（待實作）。 **命名規範**： - 以 `use` 開頭 - 描述性命名 ### /types TypeScript 類型定義（待實作）。 **組織方式**： - 按領域分組 - 共享類型放在對應檔案 ### /store Zustand 狀態管理（待實作）。 **設計原則**： - 按功能領域分割 - 保持狀態最小化 ## 檔案命名規範 ### 組件檔案 ``` - PascalCase: UserProfile.tsx - 組件相關: user-profile.module.css ``` ### 工具函數 ``` - camelCase: formatDate.ts - 測試檔案: formatDate.test.ts ``` ### 類型定義 ``` - PascalCase: User.ts - 介面: IUser, IUserProps ``` ### API 路由 ``` - 資料夾: kebab-case - 檔案: route.ts ``` ## Import 順序建議 ```typescript // 1. React/Next.js import React from 'react' import { useRouter } from 'next/navigation' // 2. 第三方庫 import { z } from 'zod' import { useQuery } from '@tanstack/react-query' // 3. 內部組件 import { Button } from '@/components/ui/button' import { FlashCard } from '@/components/flashcard' // 4. 工具函數 import { cn } from '@/lib/utils' import { formatDate } from '@/lib/format' // 5. 類型 import type { User } from '@/types/user' // 6. 樣式 import styles from './styles.module.css' ``` ## 最佳實踐 ### 1. 組件組織 - 相關組件放在同一資料夾 - 共享組件放在 `/components/ui` - 頁面特定組件可放在頁面資料夾內 ### 2. API 路由 - RESTful 命名 - 使用適當的 HTTP 方法 - 錯誤處理標準化 ### 3. 狀態管理 - 優先使用 React 內建狀態 - 全域狀態使用 Zustand - 服務器狀態使用 React Query ### 4. 類型安全 - 所有組件都要有類型定義 - 使用 `type` 而非 `interface`（除非需要擴展） - 避免使用 `any` ### 5. 程式碼分割 - 使用動態導入大型組件 - 路由級別的程式碼分割 - 優化 bundle 大小 ## 環境配置 ### 必要的環境變數 ```env # Supabase NEXT_PUBLIC_SUPABASE_URL= NEXT_PUBLIC_SUPABASE_ANON_KEY= SUPABASE_SERVICE_ROLE_KEY= # Gemini AI GEMINI_API_KEY= # App NEXT_PUBLIC_APP_URL= ``` ### Git 忽略規則 確保以下檔案不被提交： - `.env.local` - `node_modules/` - `.next/` - `*.log` ## 實際頁面結構（已實作） ### 公開頁面 - `/` - 首頁（Landing Page）：產品介紹、功能展示、CTA - `/login` - 登入頁面 - `/register` - 註冊頁面 ### 認證後頁面 - `/dashboard` - 儀表板：學習統計、進度追蹤、快速操作 - `/flashcards` - 詞卡管理：卡組列表、詞卡瀏覽、收藏管理、錯誤回報 - `/learn` - 學習頁面：多種學習模式（翻卡、選擇題、填空、聽力、口說） - `/generate` - AI 生成：文本輸入、智能萃取、批量生成詞卡 ### 頁面特色功能 #### Dashboard 頁面 (`/app/dashboard/page.tsx`) - 學習統計卡片（總詞卡、連續天數、正確率、今日進度） - 最近學習詞彙列表 - 卡組進度展示 - 學習趨勢圖表 - 頂部導航列：包含 DramaLing 標題和頁面切換 - 歡迎區塊：快速操作按鈕（開始學習、AI 生成） - 標籤式內容切換：最近學習、我的卡組、學習統計 #### Flashcards 頁面 (`/app/flashcards/page.tsx`) - 多標籤頁切換（我的卡組、所有詞卡、收藏、錯誤回報） - 智能檢測功能（AI 檢查詞卡內容正確性） - 批量操作支援 - 卡組管理（進度追蹤、標籤分類） - 搜尋過濾功能：支援關鍵字搜尋和標籤篩選 - 錯誤回報管理：顯示待處理錯誤數量和一鍵檢測 - 統計卡片：顯示總詞卡數、已掌握、待複習等數據 - 智能檢測模態框：檢測詞卡內容並提供修正建議 #### Learn 頁面 (`/app/learn/page.tsx`) - 五種學習模式切換： - 翻卡模式：點擊翻轉查看答案，包含難度評分 - 選擇題模式：根據定義選擇正確翻譯 - 填空題模式：根據例句圖片填入正確詞彙 - 聽力測試：聽音頻選擇正確單字 - 口說測試：錄音練習發音 - 進度條顯示：實時顯示學習進度 - 難度評分系統：三級評分（完全不記得、有點困難、很簡單） - 例句圖片支援：可點擊放大查看 - 錯誤回報功能：每種模式都有回報按鈕 - 詞卡導航：上一個/下一個按鈕 - 模態框功能：圖片放大顯示、錯誤回報表單 #### Generate 頁面 (`/app/generate/page.tsx`) - 兩種輸入模式（手動輸入、影劇截圖） - 兩種萃取方式（詞彙萃取、智能萃取） - 批量生成控制（5-20 個詞卡，使用滑桿調整） - 預覽和編輯生成結果： - 完整詞卡資訊展示（翻譯、定義、同義詞、反義詞） - 原始例句和 AI 生成例句對比 - 例句圖片預覽（可點擊放大） - CEFR 難度等級標記 - 用戶限制提示（免費/訂閱） - 生成過程動畫：載入旋轉圖標 - 詞卡編輯和刪除功能 - 批量保存到卡組 ## 開發工作流程 1. **功能開發**：在 `/app` 對應的頁面資料夾中開發 2. **組件提取**：將可重用部分提取到 `/components` 3. **樣式管理**：使用 Tailwind CSS + shadcn/ui 組件 4. **狀態管理**：頁面內使用 React State，跨頁面考慮 Zustand 5. **類型定義**：在 `/types` 中定義共享類型（待實作） 6. **API 整合**：在 `/app/api` 實作後端邏輯（待實作） 7. **文檔更新**：在 `/docs` 中更新相關文檔 ## 前端實作技術細節 ### 狀態管理模式 - **頁面級狀態**：使用 `useState` 管理本地狀態 - **模態框控制**：布林狀態控制顯示/隱藏 - **表單處理**：受控組件模式，實時更新輸入值 - **列表渲染**：使用 `map` 函數動態生成組件 ### UI 互動設計 - **響應式設計**：使用 Tailwind 響應式前綴（sm:, md:, lg:） - **過渡動畫**：`transition-*` 類別實現平滑過渡 - **載入狀態**：按鈕禁用、旋轉動畫、骨架屏 - **錯誤處理**：條件渲染錯誤訊息和提示 ### 組件通信 - **Props 傳遞**：父子組件間數據傳遞 - **事件處理**：onClick、onChange 等事件綁定 - **條件渲染**：三元運算符和邏輯與運算符 ### 效能優化考量 - **懶加載**：圖片和大型組件的延遲載入（待實作） - **記憶化**：使用 useMemo、useCallback（待優化） - **虛擬列表**：大量數據渲染優化（待實作）