535 lines
10 KiB
Markdown
535 lines
10 KiB
Markdown
# LinguaForge MVP 功能規格書
|
||
|
||
## 1. 產品概述
|
||
|
||
**產品名稱**：LinguaForge MVP
|
||
**版本**：0.1.0
|
||
**目標用戶**：想要高效學習英文詞彙的台灣用戶
|
||
**核心價值**：AI 自動生成個人化詞卡 + 科學化間隔複習
|
||
|
||
## 2. 用戶故事 (User Stories)
|
||
|
||
### 2.1 核心用戶故事（P0 - 必做）
|
||
|
||
```gherkin
|
||
Feature: 用戶註冊與登入
|
||
As a 新用戶
|
||
I want to 創建帳號並登入
|
||
So that 我可以保存我的學習進度
|
||
|
||
Scenario: Email 註冊
|
||
Given 我是新用戶
|
||
When 我輸入 email 和密碼
|
||
Then 系統創建帳號並自動登入
|
||
|
||
Feature: AI 詞卡生成
|
||
As a 用戶
|
||
I want to 從句子中生成詞卡
|
||
So that 我可以學習新單字
|
||
|
||
Scenario: 生成詞卡
|
||
Given 我輸入一個英文句子
|
||
When 我選擇要學習的單字
|
||
Then AI 生成包含定義和例句的詞卡
|
||
|
||
Feature: 間隔重複複習
|
||
As a 用戶
|
||
I want to 按照科學方法複習
|
||
So that 我可以長期記住單字
|
||
|
||
Scenario: 每日複習
|
||
Given 我有待複習的詞卡
|
||
When 我打開 App
|
||
Then 我看到今日需要複習的詞卡列表
|
||
```
|
||
|
||
### 2.2 次要用戶故事（P1 - 可選）
|
||
|
||
```gherkin
|
||
Feature: 學習統計
|
||
As a 用戶
|
||
I want to 查看我的學習進度
|
||
So that 我可以了解學習成效
|
||
|
||
Feature: 詞卡管理
|
||
As a 用戶
|
||
I want to 管理我的詞卡
|
||
So that 我可以整理學習內容
|
||
```
|
||
|
||
## 3. 功能規格詳述
|
||
|
||
### 3.1 用戶系統
|
||
|
||
#### 註冊流程
|
||
```yaml
|
||
輸入欄位:
|
||
- Email (必填，驗證格式)
|
||
- 密碼 (必填，最少 8 字元)
|
||
- 暱稱 (選填)
|
||
|
||
流程:
|
||
1. 用戶填寫表單
|
||
2. 前端驗證
|
||
3. 發送到 Firebase Auth
|
||
4. 創建 Supabase 用戶資料
|
||
5. 自動登入
|
||
6. 導向首頁
|
||
|
||
錯誤處理:
|
||
- Email 已存在
|
||
- 密碼太弱
|
||
- 網路錯誤
|
||
```
|
||
|
||
#### 登入流程
|
||
```yaml
|
||
輸入欄位:
|
||
- Email
|
||
- 密碼
|
||
|
||
功能:
|
||
- 記住我 (選項)
|
||
- 忘記密碼 (連結)
|
||
|
||
流程:
|
||
1. 輸入憑證
|
||
2. Firebase Auth 驗證
|
||
3. 取得 Token
|
||
4. 載入用戶資料
|
||
5. 導向首頁
|
||
```
|
||
|
||
### 3.2 AI 詞卡生成
|
||
|
||
#### 生成介面
|
||
```yaml
|
||
步驟一: 輸入句子
|
||
- 文字輸入框 (最多 200 字元)
|
||
- 範例句子提示
|
||
- 清除按鈕
|
||
|
||
步驟二: 選擇單字
|
||
- 自動標記可選單字
|
||
- 點擊選擇 (最多 5 個)
|
||
- 已選單字列表
|
||
|
||
步驟三: 生成詞卡
|
||
- 生成按鈕
|
||
- 載入動畫 (預估 3-5 秒)
|
||
- 錯誤重試
|
||
|
||
步驟四: 預覽確認
|
||
- 顯示生成結果
|
||
- 編輯選項
|
||
- 儲存/放棄
|
||
```
|
||
|
||
#### 詞卡資料結構
|
||
```json
|
||
{
|
||
"id": "uuid",
|
||
"word": "abandon",
|
||
"pronunciation": "/əˈbændən/",
|
||
"definition": "停止支持或照顧；放棄",
|
||
"partOfSpeech": "verb",
|
||
"examples": [
|
||
{
|
||
"english": "He abandoned his car in the snow.",
|
||
"chinese": "他把車遺棄在雪地裡。"
|
||
}
|
||
],
|
||
"sourceSentence": "原始句子",
|
||
"difficulty": "intermediate",
|
||
"createdAt": "2024-01-15T10:00:00Z",
|
||
"nextReviewDate": "2024-01-16T10:00:00Z",
|
||
"reviewCount": 0,
|
||
"easinessFactor": 2.5
|
||
}
|
||
```
|
||
|
||
### 3.3 複習系統
|
||
|
||
#### 複習流程
|
||
```yaml
|
||
進入複習:
|
||
- 顯示待複習數量
|
||
- 開始複習按鈕
|
||
|
||
複習介面:
|
||
第一步: 顯示單字
|
||
- 單字
|
||
- 發音
|
||
- 思考時間
|
||
|
||
第二步: 顯示答案
|
||
- 翻轉卡片動畫
|
||
- 完整定義
|
||
- 例句
|
||
|
||
第三步: 自評難度
|
||
- 完全不記得 (1)
|
||
- 有點印象 (2)
|
||
- 想了一下 (3)
|
||
- 記得 (4)
|
||
- 非常熟悉 (5)
|
||
|
||
第四步: 下一張
|
||
- 更新複習時間
|
||
- 載入下張詞卡
|
||
```
|
||
|
||
#### SM-2 演算法實現
|
||
```typescript
|
||
interface ReviewResult {
|
||
quality: number; // 1-5
|
||
easinessFactor: number;
|
||
interval: number;
|
||
repetition: number;
|
||
}
|
||
|
||
function calculateNextReview(
|
||
quality: number,
|
||
currentEF: number,
|
||
currentInterval: number,
|
||
repetitions: number
|
||
): ReviewResult {
|
||
let newEF = currentEF;
|
||
let newInterval = currentInterval;
|
||
let newRepetitions = repetitions;
|
||
|
||
if (quality < 3) {
|
||
// 重置
|
||
newInterval = 1;
|
||
newRepetitions = 0;
|
||
} else {
|
||
// 計算新 EF
|
||
newEF = currentEF + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02));
|
||
newEF = Math.max(1.3, newEF);
|
||
|
||
// 計算間隔
|
||
if (repetitions === 0) {
|
||
newInterval = 1;
|
||
} else if (repetitions === 1) {
|
||
newInterval = 6;
|
||
} else {
|
||
newInterval = Math.round(currentInterval * newEF);
|
||
}
|
||
newRepetitions++;
|
||
}
|
||
|
||
return {
|
||
quality,
|
||
easinessFactor: newEF,
|
||
interval: newInterval,
|
||
repetition: newRepetitions
|
||
};
|
||
}
|
||
```
|
||
|
||
### 3.4 詞卡管理
|
||
|
||
#### 列表檢視
|
||
```yaml
|
||
顯示內容:
|
||
- 詞卡列表 (分頁，每頁 20)
|
||
- 搜尋框
|
||
- 排序選項 (新到舊/舊到新/字母)
|
||
- 篩選 (全部/待複習/已掌握)
|
||
|
||
詞卡項目:
|
||
- 單字
|
||
- 定義摘要
|
||
- 下次複習時間
|
||
- 掌握程度圖示
|
||
```
|
||
|
||
#### 詞卡詳情
|
||
```yaml
|
||
顯示內容:
|
||
- 完整單字資訊
|
||
- 學習歷史
|
||
- 編輯按鈕
|
||
- 刪除按鈕
|
||
|
||
編輯功能:
|
||
- 修改定義
|
||
- 修改例句
|
||
- 重設複習進度
|
||
```
|
||
|
||
### 3.5 學習統計
|
||
|
||
#### 儀表板
|
||
```yaml
|
||
今日數據:
|
||
- 新增詞卡數
|
||
- 複習詞卡數
|
||
- 正確率
|
||
- 學習時間
|
||
|
||
總體統計:
|
||
- 總詞卡數
|
||
- 連續學習天數
|
||
- 本週學習時間
|
||
- 掌握程度分布
|
||
|
||
視覺化:
|
||
- 7 日學習趨勢圖
|
||
- 詞彙掌握度圓餅圖
|
||
```
|
||
|
||
## 4. UI/UX 規格
|
||
|
||
### 4.1 設計系統
|
||
|
||
#### 顏色規範
|
||
```yaml
|
||
主色:
|
||
primary: #4F46E5 (靛藍)
|
||
primaryDark: #3730A3
|
||
primaryLight: #818CF8
|
||
|
||
輔助色:
|
||
success: #10B981 (綠)
|
||
warning: #F59E0B (橙)
|
||
error: #EF4444 (紅)
|
||
info: #3B82F6 (藍)
|
||
|
||
中性色:
|
||
background: #F9FAFB
|
||
surface: #FFFFFF
|
||
text: #111827
|
||
textSecondary: #6B7280
|
||
border: #E5E7EB
|
||
```
|
||
|
||
#### 字體規範
|
||
```yaml
|
||
標題:
|
||
H1: 28px, bold
|
||
H2: 24px, semibold
|
||
H3: 20px, semibold
|
||
|
||
內文:
|
||
body: 16px, regular
|
||
caption: 14px, regular
|
||
small: 12px, regular
|
||
|
||
按鈕:
|
||
button: 16px, medium
|
||
```
|
||
|
||
### 4.2 主要畫面
|
||
|
||
#### 首頁
|
||
```
|
||
┌────────────────────┐
|
||
│ LinguaForge │
|
||
├────────────────────┤
|
||
│ 歡迎回來，用戶! │
|
||
│ │
|
||
│ 今日待複習: 15 │
|
||
│ [開始複習] │
|
||
│ │
|
||
│ 快速操作: │
|
||
│ [+ 新增詞卡] │
|
||
│ │
|
||
│ 學習統計 │
|
||
│ 連續 7 天 🔥 │
|
||
│ 本週 120 詞 │
|
||
└────────────────────┘
|
||
[首頁][詞卡][統計][我]
|
||
```
|
||
|
||
#### 詞卡生成
|
||
```
|
||
┌────────────────────┐
|
||
│ 新增詞卡 │
|
||
├────────────────────┤
|
||
│ 輸入句子: │
|
||
│ ┌────────────────┐ │
|
||
│ │ │ │
|
||
│ └────────────────┘ │
|
||
│ │
|
||
│ 選擇單字: │
|
||
│ [word1][word2] │
|
||
│ │
|
||
│ [生成詞卡] │
|
||
└────────────────────┘
|
||
```
|
||
|
||
## 5. 資料庫設計
|
||
|
||
### 5.1 資料表結構
|
||
|
||
#### users 表
|
||
```sql
|
||
CREATE TABLE users (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
email VARCHAR(255) UNIQUE NOT NULL,
|
||
nickname VARCHAR(50),
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
last_login TIMESTAMP,
|
||
preferences JSONB DEFAULT '{}'
|
||
);
|
||
```
|
||
|
||
#### cards 表
|
||
```sql
|
||
CREATE TABLE cards (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
|
||
word VARCHAR(100) NOT NULL,
|
||
pronunciation VARCHAR(100),
|
||
definition TEXT NOT NULL,
|
||
part_of_speech VARCHAR(20),
|
||
examples JSONB DEFAULT '[]',
|
||
source_sentence TEXT,
|
||
difficulty VARCHAR(20),
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW(),
|
||
|
||
-- 複習相關
|
||
next_review_date TIMESTAMP DEFAULT NOW(),
|
||
easiness_factor DECIMAL(3,2) DEFAULT 2.5,
|
||
interval_days INTEGER DEFAULT 0,
|
||
repetition_count INTEGER DEFAULT 0,
|
||
|
||
INDEX idx_user_review (user_id, next_review_date)
|
||
);
|
||
```
|
||
|
||
#### review_logs 表
|
||
```sql
|
||
CREATE TABLE review_logs (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
card_id UUID REFERENCES cards(id) ON DELETE CASCADE,
|
||
user_id UUID REFERENCES users(id) ON DELETE CASCADE,
|
||
quality INTEGER CHECK (quality BETWEEN 1 AND 5),
|
||
reviewed_at TIMESTAMP DEFAULT NOW(),
|
||
time_spent INTEGER, -- 秒數
|
||
|
||
INDEX idx_user_date (user_id, reviewed_at)
|
||
);
|
||
```
|
||
|
||
## 6. API 規格
|
||
|
||
### 6.1 端點列表
|
||
|
||
```yaml
|
||
認證相關:
|
||
POST /auth/register - 註冊
|
||
POST /auth/login - 登入
|
||
POST /auth/logout - 登出
|
||
POST /auth/refresh - 更新 token
|
||
|
||
詞卡相關:
|
||
GET /cards - 取得詞卡列表
|
||
POST /cards - 新增詞卡
|
||
GET /cards/:id - 取得單一詞卡
|
||
PUT /cards/:id - 更新詞卡
|
||
DELETE /cards/:id - 刪除詞卡
|
||
POST /cards/generate - AI 生成詞卡
|
||
|
||
複習相關:
|
||
GET /review/today - 今日待複習
|
||
POST /review/submit - 提交複習結果
|
||
|
||
統計相關:
|
||
GET /stats/summary - 學習統計摘要
|
||
GET /stats/history - 歷史記錄
|
||
```
|
||
|
||
### 6.2 Gemini API 呼叫規格
|
||
|
||
#### Request
|
||
```javascript
|
||
const prompt = `
|
||
你是一個英語教學助手。請根據以下句子和目標單字，生成詞彙學習卡片。
|
||
|
||
句子：${sentence}
|
||
目標單字：${targetWord}
|
||
|
||
請以 JSON 格式返回：
|
||
{
|
||
"word": "單字",
|
||
"pronunciation": "IPA 音標",
|
||
"definition": "中文定義",
|
||
"partOfSpeech": "詞性",
|
||
"examples": [
|
||
{
|
||
"english": "英文例句",
|
||
"chinese": "中文翻譯"
|
||
}
|
||
],
|
||
"difficulty": "beginner/intermediate/advanced"
|
||
}
|
||
`;
|
||
|
||
const response = await geminiAPI.generateContent(prompt);
|
||
```
|
||
|
||
## 7. 效能需求
|
||
|
||
### 7.1 回應時間
|
||
- 頁面載入：< 2 秒
|
||
- API 回應：< 1 秒
|
||
- AI 生成：< 5 秒
|
||
- 資料庫查詢：< 100ms
|
||
|
||
### 7.2 容量規劃
|
||
- 單用戶詞卡上限：1000 張
|
||
- 每日 API 呼叫：100 次/用戶
|
||
- 圖片大小：< 500KB
|
||
- App 大小：< 50MB
|
||
|
||
## 8. 測試需求
|
||
|
||
### 8.1 功能測試
|
||
- [ ] 註冊流程完整測試
|
||
- [ ] 登入各種情境
|
||
- [ ] AI 生成 20+ 測試案例
|
||
- [ ] 複習演算法驗證
|
||
- [ ] 資料 CRUD 操作
|
||
|
||
### 8.2 相容性測試
|
||
- [ ] iOS 14+
|
||
- [ ] Android 8+
|
||
- [ ] 各種螢幕尺寸
|
||
- [ ] 橫豎屏切換
|
||
|
||
### 8.3 效能測試
|
||
- [ ] 1000 張詞卡載入
|
||
- [ ] 離線模式
|
||
- [ ] 記憶體使用
|
||
- [ ] 電池消耗
|
||
|
||
## 9. 成功指標
|
||
|
||
### 9.1 技術指標
|
||
- 崩潰率 < 1%
|
||
- 冷啟動 < 3 秒
|
||
- API 成功率 > 99%
|
||
|
||
### 9.2 產品指標
|
||
- D1 留存 > 60%
|
||
- D7 留存 > 40%
|
||
- 日均使用 > 10 分鐘
|
||
- 每用戶日均新增 > 3 詞卡
|
||
|
||
## 10. 未來擴展預留
|
||
|
||
### 10.1 Phase 2 功能
|
||
- 語音評估
|
||
- 訂閱系統
|
||
- 社群分享
|
||
- 詞卡分類
|
||
- 學習計劃
|
||
|
||
### 10.2 技術預留
|
||
- 多語言架構
|
||
- 主題切換架構
|
||
- 插件系統架構
|
||
- A/B 測試框架 |