10 KiB
10 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 # 網站圖標
│
├── 📁 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 順序建議
// 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
開發工作流程
- 功能開發：在對應的功能資料夾中開發
- 組件提取：將可重用部分提取到
/components - 類型定義：在
/types中定義共享類型 - 測試編寫：在
/tests中編寫對應測試 - 文檔更新：在
/docs中更新相關文檔