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