jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-vocab-learning/docs/01_requirement/technical-requirements.md

3.5 KiB
Raw Blame History

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 主要資料表

-- 用戶表
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 環境變數

# 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 優化
  • 非同步處理