dramaling-vocab-learning/web-mvp-master-plan.md

# LinguaForge 網頁版 MVP 完整開發計劃

## 🎯 計劃概覽

**開發週期**：6 週（42天）
**每日工時**：6-8 小時
**總預算**：NT$ 5,000
**目標**：100 個測試用戶，40% 7日留存率
**技術棧**：Next.js + TypeScript + Supabase + Tailwind CSS

## 📊 為什麼選擇網頁版？

| 優勢 | 具體效益 |
|------|---------|
| **成本極低** | 省 86% (NT$ 30,000) |
| **開發快速** | 省 50% 時間 (6週) |
| **即時部署** | 改完即上線 |
| **SEO 優勢** | 免費自然流量 |
| **零門檻** | 用戶無需下載 |

## 🏗️ 技術架構決策

### 核心技術棧
```typescript
{
  // 前端框架
  "framework": "Next.js 14", // App Router + Server Components
  "language": "TypeScript",  // 類型安全
  "styling": "Tailwind CSS", // 快速開發
  "ui": "shadcn/ui",        // 美觀免費元件

  // 狀態管理
  "state": "Zustand",       // 輕量簡單
  "fetching": "TanStack Query", // 強大的資料管理

  // 後端服務
  "database": "Supabase",   // PostgreSQL + Realtime
  "auth": "Supabase Auth",  // 完整認證系統
  "storage": "Supabase Storage", // 檔案儲存

  // AI 服務
  "ai": "Gemini API",       // 詞卡生成

  // 部署
  "hosting": "Vercel",      // 免費額度充足
  "analytics": "Vercel Analytics" // 內建分析
}
```

## 📅 6週開發時程表

### 🚀 Week 0: 準備週（開始前）

#### Day -3 到 Day 0
```yaml
目標: 環境準備與規劃完成
任務:
  Day -3:
    ✓ 申請 Gemini API Key
    ✓ 註冊 Supabase 帳號
    ✓ 註冊 Vercel 帳號
    ✓ 安裝開發工具

  Day -2:
    ✓ 設計資料庫架構
    ✓ 規劃 API 端點
    ✓ 準備 UI 設計參考

  Day -1:
    ✓ 建立 GitHub repo
    ✓ 初始化專案
    ✓ 部署測試

產出:
  - 開發環境就緒
  - 空白專案已部署
```

### 📱 Week 1: 基礎架構

#### Day 1-2: 專案設置
```typescript
任務清單:
□ Next.js 專案初始化
□ TypeScript 配置
□ Tailwind CSS 設置
□ shadcn/ui 安裝
□ 基礎路由架構
□ Layout 元件

// 預期檔案結構
app/
├── (auth)/
│   ├── login/page.tsx
│   └── register/page.tsx
├── (dashboard)/
│   ├── layout.tsx
│   └── page.tsx
└── layout.tsx
```

#### Day 3-4: 認證系統
```typescript
任務清單:
□ Supabase 整合
□ 註冊功能
□ 登入功能
□ 登出功能
□ Protected Routes
□ 用戶 Context

關鍵程式碼:
// lib/supabase/client.ts
export const supabase = createClient(url, anonKey)

// hooks/useAuth.ts
export function useAuth() {
  // 認證邏輯
}
```

#### Day 5: 部署與測試
```yaml
任務清單:
□ Vercel 部署設置
□ 環境變數配置
□ 基礎 CI/CD
□ 測試認證流程
□ 修復問題

里程碑: 可註冊登入的網站上線 ✅
```

### 🤖 Week 2: AI 核心功能

#### Day 6-7: Gemini API 整合
```typescript
任務清單:
□ API Route 設置
□ Gemini 服務封裝
□ Prompt 工程
□ 錯誤處理
□ Rate Limiting

// app/api/gemini/route.ts
export async function POST(request: Request) {
  // Gemini API 呼叫邏輯
}
```

#### Day 8-9: 詞卡生成介面
```typescript
任務清單:
□ 句子輸入元件
□ 單字選擇功能
□ 生成按鈕與載入狀態
□ 結果顯示卡片
□ 錯誤提示

頁面路徑:
app/(dashboard)/generate/page.tsx
```

#### Day 10: 詞卡儲存
```yaml
任務清單:
□ Supabase 資料表建立
□ 儲存 API
□ 詞卡列表頁面
□ 詞卡詳情頁面

里程碑: AI 生成功能完成 ✅
```

### 📚 Week 3: 詞卡管理與複習

#### Day 11-12: CRUD 功能
```typescript
任務清單:
□ 詞卡列表 API
□ 分頁功能
□ 搜尋功能
□ 編輯功能
□ 刪除功能

使用 TanStack Query:
// hooks/useCards.ts
export function useCards() {
  return useQuery({
    queryKey: ['cards'],
    queryFn: fetchCards
  })
}
```

#### Day 13-14: SM-2 複習演算法
```typescript
任務清單:
□ 演算法實作
□ 複習排程計算
□ 今日複習 API
□ 複習介面
□ 評分功能

// lib/algorithms/sm2.ts
export function calculateNextReview() {
  // SM-2 邏輯
}
```

#### Day 15: 學習統計
```yaml
任務清單:
□ 統計 API
□ 儀表板頁面
□ 進度圖表
□ 學習連續天數

里程碑: 核心功能完成 ✅
```

### 🎨 Week 4: UI/UX 優化

#### Day 16-17: 響應式設計
```css
任務清單:
□ 手機版優化
□ 平板適配
□ 桌面版完善
□ 導航優化
□ 觸控優化

斷點設計:
- Mobile: < 640px
- Tablet: 640px - 1024px
- Desktop: > 1024px
```

#### Day 18-19: 使用體驗提升
```typescript
任務清單:
□ 載入骨架屏
□ 錯誤邊界
□ 404 頁面
□ 動畫效果
□ 鍵盤快捷鍵

// 使用 Framer Motion
import { motion } from 'framer-motion'
```

#### Day 20-21: PWA 功能
```yaml
任務清單:
□ Service Worker
□ Manifest.json
□ 離線快取
□ 安裝提示
□ 推播通知準備

里程碑: PWA 功能就緒 ✅
```

### 🧪 Week 5: 測試與優化

#### Day 22-23: 功能測試
```typescript
任務清單:
□ 單元測試撰寫
□ E2E 測試 (Playwright)
□ 手動測試清單
□ Bug 修復
□ 邊界案例處理

測試覆蓋:
- 認證流程
- AI 生成
- 複習系統
- 資料 CRUD
```

#### Day 24-25: 效能優化
```yaml
任務清單:
□ Lighthouse 評分優化
□ 圖片優化
□ Code Splitting
□ API 快取策略
□ Database 索引

目標指標:
- Performance: > 90
- Accessibility: > 95
- Best Practices: > 95
- SEO: > 100
```

#### Day 26-27: 安全性檢查
```typescript
任務清單:
□ API Rate Limiting
□ Input Validation
□ XSS 防護
□ SQL Injection 防護
□ 環境變數檢查

// middleware.ts
export function middleware(request: NextRequest) {
  // Rate limiting 邏輯
}
```

### 🚀 Week 6: 發布與推廣

#### Day 28-29: 發布準備
```yaml
任務清單:
□ 生產環境配置
□ 網域設置
□ SSL 憑證
□ 備份策略
□ 監控設置

網域選擇:
- linguaforge.com
- linguaforge.app
- linguaforge.tw
```

#### Day 30-31: 內測啟動
```yaml
任務清單:
□ 邀請 Beta 用戶
□ 意見收集表單
□ 快速修復
□ 文檔撰寫
□ 使用教學

目標:
- 20 個內測用戶
- 收集 10+ 回饋
```

#### Day 32-33: 公開發布
```yaml
任務清單:
□ ProductHunt 發布
□ 社群媒體宣傳
□ Reddit 分享
□ FB 社團推廣
□ SEO 優化

推廣管道:
- PTT: TOEIC/Language 版
- FB: 英文學習社團
- Dcard: 語言版
```

## 💰 預算控制（6週）

### 成本明細
```yaml
必要支出:
  Gemini API 測試: NT$ 500
  網域名稱 (.com): NT$ 400
  總計: NT$ 900

可選支出:
  Logo 設計 (Fiverr): NT$ 500
  廣告測試: NT$ 1,000
  總計: NT$ 1,500

最大預算: NT$ 2,400
```

### 免費資源運用
```yaml
完全免費:
  - Vercel: 免費額度 (100GB 頻寬/月)
  - Supabase: 免費版 (500MB DB, 1GB 儲存)
  - GitHub: 私有 repo
  - Gemini: 免費額度 (60 QPM)
  - shadcn/ui: 開源元件
  - Tailwind CSS: 開源
```

## 🎯 關鍵里程碑檢查點

### Week 1 結束
- [ ] 用戶可以註冊/登入
- [ ] 網站已部署上線
- **決策點**: 技術可行性確認

### Week 2 結束
- [ ] AI 生成功能運作
- [ ] 可儲存詞卡
- **決策點**: 核心價值驗證

### Week 3 結束
- [ ] 完整 CRUD 功能
- [ ] 複習系統運作
- **決策點**: MVP 功能完整性

### Week 4 結束
- [ ] 響應式設計完成
- [ ] PWA 功能就緒
- **決策點**: 用戶體驗達標

### Week 5 結束
- [ ] 所有測試通過
- [ ] 效能指標達標
- **決策點**: 品質標準確認

### Week 6 結束
- [ ] 100+ 用戶註冊
- [ ] 40%+ 留存率
- **決策點**: 市場驗證

## 🛠️ 技術實作重點

### 1. 資料庫設計（Supabase）
```sql
-- 用戶表
CREATE TABLE users (
  id UUID DEFAULT auth.uid() PRIMARY KEY,
  email TEXT UNIQUE NOT NULL,
  username TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

-- 詞卡表
CREATE TABLE cards (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  word TEXT NOT NULL,
  definition TEXT NOT NULL,
  examples JSONB,
  next_review TIMESTAMP DEFAULT NOW(),
  easiness_factor DECIMAL DEFAULT 2.5,
  interval_days INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW()
);

-- RLS 政策
ALTER TABLE cards ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can only see own cards" ON cards
  FOR ALL USING (auth.uid() = user_id);
```

### 2. 關鍵元件架構
```typescript
// components/card-generator.tsx
export function CardGenerator() {
  const [sentence, setSentence] = useState('')
  const [selectedWord, setSelectedWord] = useState('')
  const { mutate: generateCard, isLoading } = useGenerateCard()

  // 元件邏輯
}

// hooks/useGenerateCard.ts
export function useGenerateCard() {
  return useMutation({
    mutationFn: async (data) => {
      const response = await fetch('/api/gemini', {
        method: 'POST',
        body: JSON.stringify(data)
      })
      return response.json()
    }
  })
}
```

### 3. PWA 配置
```javascript
// next.config.js
const withPWA = require('next-pwa')({
  dest: 'public',
  register: true,
  skipWaiting: true,
  disable: process.env.NODE_ENV === 'development'
})

module.exports = withPWA({
  // Next.js 配置
})
```

## 📈 成功指標

### 技術指標
- [ ] Lighthouse 分數 > 90
- [ ] 首次載入 < 3 秒
- [ ] API 回應 < 500ms
- [ ] 零嚴重 Bug

### 產品指標
- [ ] 100+ 註冊用戶
- [ ] 40%+ D7 留存
- [ ] 10+ 分鐘日均使用
- [ ] 50+ NPS 分數

### 商業指標
- [ ] CAC < NT$ 50
- [ ] 30%+ 付費意願
- [ ] 5+ 用戶推薦

## 🚨 風險管理

### 技術風險
| 風險 | 機率 | 對策 |
|------|------|------|
| Gemini API 不穩 | 中 | 準備 OpenAI 備案 |
| Supabase 限制 | 低 | 監控用量 |
| 效能問題 | 中 | 提前優化 |

### 時程風險
| 風險 | 機率 | 對策 |
|------|------|------|
| 功能超時 | 中 | 狠心砍功能 |
| Bug 太多 | 低 | TDD 開發 |
| 學習曲線 | 低 | 選熟悉技術 |

## 🎬 立即行動

### 今天（Day 0）
```bash
# 1. 初始化專案
npx create-next-app@latest linguaforge --typescript --tailwind --app
cd linguaforge

# 2. 安裝核心套件
npm install @supabase/supabase-js @supabase/auth-helpers-nextjs
npm install zustand @tanstack/react-query
npm install @google/generative-ai

# 3. 設置 shadcn/ui
npx shadcn-ui@latest init

# 4. 部署到 Vercel
vercel

# 完成！你的網站已經上線了
```

### 第一週檢查清單
- [ ] Day 1: 專案架構完成
- [ ] Day 2: 基礎 UI 完成
- [ ] Day 3: 認證系統完成
- [ ] Day 4: 用戶功能測試
- [ ] Day 5: 部署上線

## 💪 成功秘訣

### Do's ✅
1. **每日部署**: 每天都要部署新版本
2. **快速迭代**: 不求完美，求能用
3. **用戶優先**: 盡早收集反饋
4. **保持簡單**: 避免過度工程
5. **記錄一切**: 寫開發日誌

### Don'ts ❌
1. **不要完美主義**: MVP 夠用就好
2. **不要過度設計**: 先跑起來再說
3. **不要拖延上線**: Week 1 就要上線
4. **不要忽視反饋**: 用戶說了算
5. **不要怕失敗**: 失敗成本很低

## 📚 參考資源

### 學習資源
- [Next.js 文檔](https://nextjs.org/docs)
- [Supabase 文檔](https://supabase.com/docs)
- [shadcn/ui](https://ui.shadcn.com)
- [Tailwind CSS](https://tailwindcss.com)

### 社群支援
- Next.js Discord
- Supabase Discord
- Reddit r/nextjs
- Stack Overflow

## 🎯 最終目標

> **6 週內打造一個有 100 個活躍用戶、40% 留存率的 AI 英語學習平台！**

記住：
- 網頁版成本只要 App 的 14%
- 開發時間只要 App 的 50%
- 可以即時更新，快速迭代
- 成功後再做 App，程式碼可重用 80%

**現在就開始，6 週後見證奇蹟！🚀**