# DramaLing 技術需求規格書

## 1. 技術架構

### 1.1 前端技術棧
- **框架**: Next.js 14+ (App Router)
- **語言**: TypeScript 5+
- **樣式**: Tailwind CSS 3+
- **UI 組件**: shadcn/ui
- **狀態管理**: Zustand
- **資料獲取**: TanStack Query

### 1.2 後端技術棧
- **API Routes**: Next.js API Routes
- **資料庫**: Supabase (PostgreSQL)
- **認證**: Supabase Auth
- **檔案儲存**: Supabase Storage
- **AI 服務**: Google Gemini API

### 1.3 部署與基礎設施
- **託管**: Vercel
- **CDN**: Vercel Edge Network
- **監控**: Vercel Analytics
- **版本控制**: GitHub

## 2. 資料庫架構

### 2.1 主要資料表

```sql
-- 用戶表
users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE,
  created_at TIMESTAMP,
  updated_at TIMESTAMP
)

-- 詞卡表
flashcards (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  word VARCHAR(255),
  translation TEXT,
  context TEXT,
  example TEXT,
  difficulty INTEGER,
  created_at TIMESTAMP,
  next_review_date DATE,
  review_count INTEGER
)

-- 學習記錄表
study_sessions (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  flashcard_id UUID REFERENCES flashcards(id),
  rating INTEGER,
  studied_at TIMESTAMP
)

-- 標籤表
tags (
  id UUID PRIMARY KEY,
  name VARCHAR(100),
  user_id UUID REFERENCES users(id)
)

-- 詞卡標籤關聯表
flashcard_tags (
  flashcard_id UUID REFERENCES flashcards(id),
  tag_id UUID REFERENCES tags(id),
  PRIMARY KEY (flashcard_id, tag_id)
)
```

## 3. API 設計

### 3.1 RESTful API 端點

```
# 認證
POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/session

# 詞卡管理
GET    /api/flashcards
POST   /api/flashcards
GET    /api/flashcards/:id
PUT    /api/flashcards/:id
DELETE /api/flashcards/:id

# AI 生成
POST   /api/ai/generate-flashcard

# 學習統計
GET    /api/stats/overview
GET    /api/stats/progress
```

### 3.2 API 規格
- JSON 格式回應
- JWT Token 認證
- Rate Limiting: 100 req/min
- 錯誤處理標準化

## 4. 安全需求

### 4.1 認證與授權
- Supabase Row Level Security (RLS)
- JWT Token 過期時間: 7 天
- Refresh Token 機制

### 4.2 資料保護
- HTTPS Only
- 環境變數管理
- SQL Injection 防護
- XSS Protection Headers

### 4.3 API 安全
- CORS 設定
- Rate Limiting
- API Key 加密儲存

## 5. 效能需求

### 5.1 前端效能
- Lighthouse Score > 90
- First Contentful Paint < 1.5s
- Time to Interactive < 3s
- Code Splitting
- Image Optimization

### 5.2 後端效能
- API Response Time < 500ms
- Database Query < 100ms
- Caching Strategy (Redis/Memory)
- Connection Pooling

## 6. 開發環境需求

### 6.1 必要工具
- Node.js 18+
- npm/pnpm
- Git
- VS Code

### 6.2 環境變數
```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=
```

## 7. 測試需求

### 7.1 測試類型
- 單元測試 (Jest)
- 整合測試 (React Testing Library)
- E2E 測試 (Playwright)

### 7.2 測試覆蓋率
- 程式碼覆蓋率 > 70%
- 關鍵路徑 100% 覆蓋
- CI/CD 自動化測試

## 8. 監控與日誌

### 8.1 監控指標
- 應用程式錯誤率
- API 回應時間
- 資料庫效能
- 用戶活躍度

### 8.2 日誌管理
- 結構化日誌 (JSON)
- 日誌級別分類
- 錯誤追蹤 (Sentry)

## 9. 擴展性考量

### 9.1 橫向擴展
- Serverless 架構
- 資料庫讀寫分離
- CDN 快取策略

### 9.2 垂直擴展
- 資料庫索引優化
- Query 優化
- 非同步處理