# 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 # 網站圖標 │ ├── 📁 src/ # 原始碼目錄 │ ├── 📁 app/ # Next.js App Router │ │ ├── (auth)/ # 認證相關頁面組 │ │ │ ├── login/ # 登入頁面 │ │ │ ├── register/ # 註冊頁面 │ │ │ └── forgot-password/ # 忘記密碼 │ │ │ │ │ ├── (dashboard)/ # 儀表板頁面組 │ │ │ ├── dashboard/ # 主儀表板 │ │ │ ├── flashcards/ # 詞卡管理 │ │ │ ├── review/ # 複習系統 │ │ │ ├── stats/ # 統計分析 │ │ │ └── settings/ # 設定頁面 │ │ │ │ │ ├── api/ # API 路由 │ │ │ ├── auth/ # 認證 API │ │ │ ├── flashcards/ # 詞卡 API │ │ │ ├── ai/ # AI 生成 API │ │ │ ├── stats/ # 統計 API │ │ │ └── tags/ # 標籤 API │ │ │ │ │ ├── layout.tsx # 根佈局 │ │ ├── page.tsx # 首頁 │ │ ├── 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） - 方括號 `[]` 用於動態路由 ### /src/components 可重用的 React 組件。 **組織原則**： - `ui/`: shadcn/ui 基礎組件 - `layout/`: 頁面佈局組件 - 業務組件按功能分組 ### /src/lib 不含 React 的純 JavaScript/TypeScript 工具。 **內容**： - 第三方服務配置 - 工具函數 - 常數定義 ### /src/hooks 自定義 React Hooks。 **命名規範**： - 以 `use` 開頭 - 描述性命名 ### /src/types TypeScript 類型定義。 **組織方式**： - 按領域分組 - 共享類型放在對應檔案 ### /src/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` ## 開發工作流程 1. **功能開發**：在對應的功能資料夾中開發 2. **組件提取**：將可重用部分提取到 `/components` 3. **類型定義**：在 `/types` 中定義共享類型 4. **測試編寫**：在 `/tests` 中編寫對應測試 5. **文檔更新**：在 `/docs` 中更新相關文檔