jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-vocab-learning/docs/03_development/setup/folder-structure.md

308 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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` 中更新相關文檔
Reference in New Issue View Git Blame Copy Permalink