系統模型設計#

本文檔詳細說明水球軟體學院複刻專案的所有資料模型（Entity Models），包括核心課程系統和道館挑戰系統。

模型總覽#

系統共包含 16 個核心實體模型，分為以下模組：

🎓 基礎系統模型#

1. User（用戶）#

用途： 用戶帳號、認證系統（含 OAuth）與遊戲化系統

實體類： tw.waterballsa.academy.entity.User

欄位說明#

核心業務邏輯#

// 經驗值增加時自動升級
public void addExp(int expToAdd) {
    this.exp += expToAdd;
    updateLevel();  // 自動重算等級
}

// 等級計算邏輯（基於固定門檻陣列）
private void updateLevel() {
    int[] thresholds = {0, 200, 500, 1500, 3000, 5000, ...};
    for (int i = thresholds.length - 1; i >= 0; i--) {
        if (this.exp >= thresholds[i]) {
            this.level = i + 1;
            break;
        }
    }
}

關聯關係#

• 1:N → MissionProgress（學習進度）
• 1:N → CourseEnrollment（購課記錄）
• 1:N → Submission（作業提交）
• 1:N → UserSkill（技能等級）

索引#

• UNIQUE INDEX on email
• INDEX on googleId

2. Course（課程）#

用途： 課程基本資訊（名稱、價格、講師等）

實體類： tw.waterballsa.academy.entity.Course

欄位說明#

關聯關係#

• 1:N → Chapter（章節，級聯刪除）
• 1:N → CourseEnrollment（購課記錄）

業務規則#

• 刪除課程時，所有章節和任務將被級聯刪除（CascadeType.ALL）
• enabledFeatures 儲存在關聯表 course_features

3. Chapter（章節）#

用途： 課程章節（組織課程結構）

實體類： tw.waterballsa.academy.entity.Chapter

欄位說明#

關聯關係#

• N:1 → Course（所屬課程）
• 1:N → Mission（任務單元，級聯刪除）
• 1:N → Gym（道館，級聯刪除）

業務規則#

• orderIndex 決定章節顯示順序
• 刪除章節時，所有任務和道館將被級聯刪除

4. Mission（任務單元）#

用途： 學習單元（影片/文章/問卷）

實體類： tw.waterballsa.academy.entity.Mission

相關枚舉： MissionType（VIDEO, ARTICLE, SURVEY）

欄位說明#

關聯關係#

• N:1 → Chapter（所屬章節）
• 1:N → MissionProgress（用戶進度）

業務規則#

• 免費預覽規則：isFreePreview=true 的任務無需購課即可觀看
• 獎勵領取規則：進度達 80% 才可領取 exp 獎勵（參見 MissionService:130）
• 類型限制：
  • VIDEO：通常有 videoUrl
  • ARTICLE/SURVEY：使用 content 欄位

5. MissionProgress（學習進度）#

用途： 用戶學習進度追蹤

實體類： tw.waterballsa.academy.entity.MissionProgress

欄位說明#

唯一性約束#

@UniqueConstraint(columnNames = {"user_id", "mission_id"})

每個用戶對每個任務只有一條進度記錄。

核心業務邏輯#

// 更新進度（只能增加，不能減少）
public void updateProgress(int newProgress) {
    int cappedProgress = Math.min(100, newProgress);
    if (cappedProgress > this.progress) {
        this.progress = cappedProgress;
    }
    if (this.progress >= 100 && !this.completed) {
        this.completed = true;
        this.completedAt = LocalDateTime.now();
    }
    this.updatedAt = LocalDateTime.now();
}

關聯關係#

• N:1 → User（用戶）
• N:1 → Mission（任務）

6. CourseEnrollment（購課記錄）#

用途： 用戶購課記錄（含免費、付費、贈送）

實體類： tw.waterballsa.academy.entity.CourseEnrollment

相關枚舉：

• EnrollmentType（FREE, PURCHASED, GIFTED）
• PaymentStatus（PENDING, COMPLETED, CANCELLED）

欄位說明#

唯一性約束#

@UniqueConstraint(columnNames = {"user_id", "course_id"})

同一用戶不可重複購買同一課程。

業務規則#

• 免費課程：自動設為 FREE 類型，無需支付
• 付費課程：須完成付款流程（測試模式下自動通過）
• 贈送課程：由管理員手動指定為 GIFTED

🏋️ 道館系統模型#

7. Gym（道館）#

用途： 道館（包含多個挑戰任務）

實體類： tw.waterballsa.academy.entity.Gym

相關枚舉：

• GymCategory（WHITE, BLACK）
• GymDifficulty（BEGINNER, INTERMEDIATE, ADVANCED, EXPERT, MASTER）

欄位說明#

關聯關係#

• N:1 → Chapter（所屬章節）
• 1:N → GymPrerequisite（前置課程要求）
• 1:N → Challenge（挑戰任務）

8. GymPrerequisite（前置課程）#

用途： 道館的前置課程要求

實體類： tw.waterballsa.academy.entity.GymPrerequisite

欄位說明#

業務規則#

• 用戶必須完成所有前置任務才能挑戰道館
• 如果 requireRewardClaimed=true，還需領取該任務的經驗值獎勵

9. Challenge（挑戰任務）#

用途： 挑戰任務（速戰速決/實戰演練）

實體類： tw.waterballsa.academy.entity.Challenge

相關枚舉： ChallengeType（INSTANT, PRACTICAL）

欄位說明#

關聯關係#

• N:1 → Gym（所屬道館）
• 1:N → ChallengeField（提交欄位定義）
• 1:N → Submission（學員提交）

業務規則#

• 速戰速決（INSTANT）：快速驗證概念理解
• 實戰演練（PRACTICAL）：完整專案實作
• 重複挑戰：repeatable=true 允許多次提交

10. ChallengeField（提交欄位定義）#

用途： 挑戰需要提交的檔案欄位

實體類： tw.waterballsa.academy.entity.ChallengeField

相關枚舉： FieldType（FILE, URL, TEXT, CODE）

欄位說明#

業務規則#

• 定義學員需要提交的內容（如：原始碼檔案、GitHub URL、說明文字）
• 驗證提交時會檢查所有 required=true 的欄位

11. Submission（作業提交）#

用途： 學員的作業提交記錄

實體類： tw.waterballsa.academy.entity.Submission

相關枚舉： SubmissionStatus（PENDING, GRADING, GRADED, REJECTED）

欄位說明#

關聯關係#

• N:1 → Challenge（所屬挑戰）
• N:1 → User（提交用戶）
• 1:N → SubmissionFile（提交檔案）
• 1:1 → GradeResult（批改結果）

狀態流轉#

PENDING → GRADING → GRADED
              ↓
          REJECTED

12. SubmissionFile（提交檔案）#

用途： 提交的檔案（支援多檔案）

實體類： tw.waterballsa.academy.entity.SubmissionFile

欄位說明#

業務規則#

• fieldKey 對應 ChallengeField.fieldKey
• 支援一個欄位上傳多個檔案

13. GradeResult（批改結果）#

用途： 老師的批改結果

實體類： tw.waterballsa.academy.entity.GradeResult

欄位說明#

關聯關係#

• 1:1 → Submission（對應提交）
• N:1 → User（批改教師）
• 1:N → SkillRating（技能評級）

14. SkillRating（技能評級）#

用途： 技能評級（6 個類別 × 34 種級別）

實體類： tw.waterballsa.academy.entity.SkillRating

相關枚舉：

• SkillCategory（熟悉設計模式的Form、區分結構與行為、游刃有餘的開發能力、需求結構化分析、抽象萃取能力、建立Well-Defined Context）
• SkillLevel（F- 到 ACE，共 34 個等級：F-, F, F+, E-, E, E+, D-, D, D+, C-, C, C+, B-, B, B+, A-, A, A+, AA-, AA, AA+, AAA-, AAA, AAA+, S-, S, S+, SS-, SS, SS+, SSS-, SSS, SSS+, ACE）

欄位說明#

業務規則#

• 每次批改可對多個技能類別進行評級
• 評級會影響用戶的 UserSkill 紀錄

15. UserSkill（用戶技能等級）#

用途： 用戶的技能等級記錄

實體類： tw.waterballsa.academy.entity.UserSkill

欄位說明#

唯一性約束#

@UniqueConstraint(columnNames = {"user_id", "category"})

業務規則#

• 用戶每個技能類別只有一條記錄
• level 為最近一次評級結果

📦 訂單系統模型#

16. Order（訂單）#

用途： 課程購買訂單

實體類： tw.waterballsa.academy.entity.Order

相關枚舉： OrderStatus（PENDING, PAID, CANCELLED, REFUNDED）

欄位說明#

關聯關係#

• N:1 → User（購買用戶）
• N:1 → Course（購買課程）

🔗 完整 ER 關係圖#

erDiagram
    User ||--o{ MissionProgress : tracks
    User ||--o{ CourseEnrollment : enrolls
    User ||--o{ Submission : submits
    User ||--o{ UserSkill : has
    User ||--o{ Order : places

    Course ||--o{ Chapter : contains
    Course ||--o{ CourseEnrollment : enrolled_by
    Course ||--o{ Order : purchased_in

    Chapter ||--o{ Mission : contains
    Chapter ||--o{ Gym : contains

    Mission ||--o{ MissionProgress : tracked_by
    Mission ||--o{ GymPrerequisite : required_by

    Gym ||--o{ GymPrerequisite : requires
    Gym ||--o{ Challenge : contains

    Challenge ||--o{ ChallengeField : defines
    Challenge ||--o{ Submission : receives

    Submission ||--o{ SubmissionFile : includes
    Submission ||--|| GradeResult : has

    GradeResult ||--o{ SkillRating : rates

💡 設計原則#

1. 資料一致性#

• 唯一性約束：防止重複記錄（如同一用戶重複購課）
• 外鍵約束：確保參照完整性
• 級聯刪除：避免孤兒資料（如刪除課程時自動刪除章節）

2. 效能優化#

• 延遲載入：使用 FetchType.LAZY 避免 N+1 查詢
• 索引策略：在常查詢欄位加索引（email, googleId 等）
• 預設值：使用 @Builder.Default 減少空值判斷

3. 擴展性#

• 枚舉管理：使用 Enum 管理有限狀態集合
• 彈性欄位：預留擴展欄位（如 metadata JSON 欄位）
• 關聯表設計：便於未來新增關係

4. 安全性#

• 密碼加密：使用 BCrypt 加密儲存
• 時間戳記：@PrePersist 和 @PreUpdate 自動管理
• 權限檢查：業務邏輯分離到 Service 層

📚 相關文檔#

• 資料庫設計 - 詳細表結構和索引策略
• 認證授權 - OAuth 和 JWT 實作
• API 文檔 - RESTful API 端點說明
• 等級經驗值規則 - 遊戲化系統設計

🔄 模型狀態總覽#