14 KiB
14 KiB
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 Pagelayout.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 順序建議
// 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 大小
環境配置
必要的環境變數
# 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.localnode_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 難度等級標記
- 用戶限制提示（免費/訂閱）
- 生成過程動畫：載入旋轉圖標
- 詞卡編輯和刪除功能
- 批量保存到卡組
開發工作流程
- 功能開發：在
/app對應的頁面資料夾中開發 - 組件提取：將可重用部分提取到
/components - 樣式管理：使用 Tailwind CSS + shadcn/ui 組件
- 狀態管理：頁面內使用 React State，跨頁面考慮 Zustand
- 類型定義：在
/types中定義共享類型（待實作） - API 整合：在
/app/api實作後端邏輯（待實作） - 文檔更新：在
/docs中更新相關文檔
前端實作技術細節
狀態管理模式
- 頁面級狀態：使用
useState管理本地狀態 - 模態框控制：布林狀態控制顯示/隱藏
- 表單處理：受控組件模式，實時更新輸入值
- 列表渲染：使用
map函數動態生成組件
UI 互動設計
- 響應式設計：使用 Tailwind 響應式前綴（sm:, md:, lg:）
- 過渡動畫：
transition-*類別實現平滑過渡 - 載入狀態：按鈕禁用、旋轉動畫、骨架屏
- 錯誤處理：條件渲染錯誤訊息和提示
組件通信
- Props 傳遞：父子組件間數據傳遞
- 事件處理：onClick、onChange 等事件綁定
- 條件渲染：三元運算符和邏輯與運算符
效能優化考量
- 懶加載：圖片和大型組件的延遲載入（待實作）
- 記憶化：使用 useMemo、useCallback（待優化）
- 虛擬列表：大量數據渲染優化（待實作）