409 lines
14 KiB
Markdown
409 lines
14 KiB
Markdown
# 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（待優化）
|
||
- **虛擬列表**：大量數據渲染優化（待實作） |