階段 25-2 ｜寵物系統引導

assets/lang/en.json

@@ -347,6 +347,9 @@
   }
   ,
   "tutorial": {
+    "pet_intro": "Pets can be obtained through gacha; they are your strongest allies",
+    "pet_ticket_info": "You can now earn gacha tickets from daily quests",
+    "pet_ticket_reward": "You received 10 Pet Gacha Tickets!",
     "tap_hippo": "Tap the Hippo to earn Meme Points. Let's reach 10 points!",
     "open_mainline": "Open the Mainline Quest",
     "mainline_story": "Follow the Mainline to help Hippo become the Meme King",

assets/lang/jp.json

@@ -344,6 +344,9 @@
   }
   ,
   "tutorial": {
+    "pet_intro": "ペットはガチャで入手できます。最強の相棒です",
+    "pet_ticket_info": "これからはデイリーミッションでガチャチケットを獲得できます",
+    "pet_ticket_reward": "ペットガチャチケットを10枚獲得！",
     "tap_hippo": "カバをタップしてミームポイントを獲得。まずは10ポイント貯めましょう！",
     "open_mainline": "メインクエストを開く",
     "mainline_story": "主線に沿ってカバをミーム王にしよう",

assets/lang/ko.json

@@ -344,6 +344,9 @@
   }
   ,
   "tutorial": {
+    "pet_intro": "펫은 가챠로 얻을 수 있어요. 가장 든든한 동료입니다",
+    "pet_ticket_info": "이제 일일 미션에서 가챠 티켓을 받을 수 있어요",
+    "pet_ticket_reward": "펫 가챠 티켓 10장을 획득!",
     "tap_hippo": "하마를 탭하여 밈 포인트를 모아봐요. 우선 10포인트를 달성해요!",
     "open_mainline": "메인 퀘스트 열기",
     "mainline_story": "주선을 따라 하마를 밈의 왕으로",

assets/lang/zh.json

@@ -339,6 +339,9 @@
     "daily_locked": "今日已完成，請明日再來！"
   },
   "tutorial": {
+    "pet_intro": "寵物可以靠抽卡獲取，寵物是你最強力的夥伴",
+    "pet_ticket_info": "現在開始可以通過每日任務獲得抽獎券",
+    "pet_ticket_reward": "獲得 10 張寵物抽獎券！",
     "tap_hippo": "點擊角色可以獲得迷因點數，我們先累積 10 個迷因點數！",
     "open_mainline": "點擊主線任務首頁",
     "mainline_story": "隨著主線任務發展，河馬寶寶可以成為迷因王",
@@ -354,4 +357,4 @@
     "manga": "點擊以繼續",
     "next": "下一步"
   }
-}
+}

docs/step25-2/spec.md

@@ -0,0 +1,121 @@
+# 📄 Step 25-2 規格書（寵物系統引導）
+
+---
+
+## 1. 階段目標
+- 新增「寵物系統引導」：逐步高亮並限制點擊範圍。
+- 引導流程需持久化，支援中途退出後重開 App 從斷點繼續。
+- 完成後不再觸發（除非玩家手動重置存檔）。
+- 所有提示文字需支援 **i18n**。
+- 完成引導後，給予玩家 10 張寵物抽獎券並跳出通知。
+
+---
+
+## 2. 功能需求
+
+### 2.1 教學流程控制
+- 教學狀態存於 `tutorial_pet_step`。
+- 每步包含：
+  - `focusTarget`（UI 元件 ID）
+  - `overlay`（高亮＋遮罩）
+  - `instruction_key`（多語文字）
+  - `action`（觸發條件）
+- 步驟完成 → 更新 `tutorial_pet_step = nextStep`。
+- 完成全部 → 記錄 `tutorial_pet_completed=true`。
+
+### 2.2 教學步驟（完整 4 步）
+1. **寵物頁面**  
+   - Focus：nav 寵物按鈕。  
+   - Instruction：`pet_intro`。  
+   - 等待 1 秒後顯示【下一步】。  
+2. **返回首頁**  
+   - Focus：nav 首頁按鈕。  
+   - Instruction：`back_home`。  
+3. **首頁顯示抽獎券**  
+   - Focus：首頁寵物抽獎券顯示區域。  
+   - Instruction：`pet_ticket_info`。  
+   - 等待 1 秒後顯示【下一步】。  
+4. **結束引導**  
+   - 結束教學 → 彈窗提示「獲得 10 張寵物抽獎券」→ 更新玩家狀態，實際新增 10 張。
+
+### 2.3 UI/UX
+- 遮罩：半透明黑，僅允許 focus 元件可操作。
+- 說明文字：顯示於 focus 區域附近；多語系切換。
+- 按鈕：【下一步】淡入動畫。
+
+### 2.4 狀態儲存
+```json
+{
+  "tutorial_pet": {
+    "step": 0,
+    "completed": false,
+    "rewardGiven": false
+  }
+}
+````
+
+* `step=0`：未開始；完成第 N 步 → 記錄 `step=N`。
+* `completed=true`：流程完成，App 重啟不再觸發。
+* `rewardGiven=true`：已發放 10 張抽獎券，避免重複。
+
+### 2.5 i18n（示例）
+
+```json
+{
+  "tutorial.pet_intro": {
+    "zh": "寵物可以靠抽卡獲取，寵物是你最強力的夥伴",
+    "en": "Pets can be obtained through gacha, they are your strongest allies"
+  },
+  "tutorial.back_home": {
+    "zh": "返回首頁",
+    "en": "Return to Home"
+  },
+  "tutorial.pet_ticket_info": {
+    "zh": "現在開始可以通過每日任務獲得抽獎券",
+    "en": "You can now earn gacha tickets from daily quests"
+  },
+  "tutorial.pet_ticket_reward": {
+    "zh": "獲得 10 張寵物抽獎券！",
+    "en": "You received 10 Pet Gacha Tickets!"
+  }
+}
+```
+
+---
+
+## 3. 驗收標準
+
+* ✅ 完成主線第三章 → 自動觸發寵物引導流程。
+* ✅ 引導進度可持久化：退出 App 後重開 → 從中斷步驟繼續。
+* ✅ 流程完成後，`tutorial_pet.completed=true`，重啟不再觸發。
+* ✅ 每個步驟僅允許操作指定 focus 元件，其他區域無效。
+* ✅ 引導結束時彈窗通知並正確發放 10 張抽獎券。
+* ✅ i18n 正常顯示：不同語言模式下文字正確。
+
+---
+
+## 4. 實例化需求測試案例
+
+### 測試案例 1：完整流程
+
+* **Given** 完成主線第三章
+* **When** 依指示走完 4 步
+* **Then** 教學結束並領取 10 張寵物抽獎券
+
+### 測試案例 2：中途退出
+
+* **Given** 進行到步驟 2
+* **When** 關閉 App 再次打開
+* **Then** 教學從步驟 2 繼續
+
+### 測試案例 3：重置存檔
+
+* **Given** 教學已完成
+* **When** 重置存檔
+* **Then** 教學重新觸發，從步驟 0 開始
+
+### 測試案例 4：重複領取防護
+
+* **Given** 教學完成並已領取獎勵
+* **When** 再次啟動 App
+* **Then** 不會重複給予抽獎券

lib/services/daily_mission_service.dart

@@ -32,12 +32,16 @@ class DailyMissionService {
       _tapTargetOverride = tapTargetOverride;
 
   double _tapTarget() {
-    if (_tapTargetOverride != null) return _tapTargetOverride.toDouble();
+    if (_tapTargetOverride != null) {
+      return _tapTargetOverride.toDouble();
+    }
     final v = ConfigService().getValue(
       'game.daily_mission.tap_target',
       defaultValue: 50,
     );
-    if (v is num) return v.toDouble();
+    if (v is num) {
+      return v.toDouble();
+    }
     return 50.0;
   }
 
@@ -185,7 +189,9 @@ class DailyMissionService {
 
   /// 處理資源獲得事件（B類任務進度）
   GameState onEarnPoints(GameState state, double delta) {
-    if (delta <= 0) return state;
+    if (delta <= 0) {
+      return state;
+    }
 
     final s0 = ensureDailyMissionBlock(state);
     final mission = s0.dailyMission!;
@@ -263,7 +269,9 @@ class DailyMissionService {
 
   /// 取得指定序號的獎勵點數
   double getRewardForIndex(int index) {
-    if (index < 1 || index > _rewardSequence.length) return 0.0;
+    if (index < 1 || index > _rewardSequence.length) {
+      return 0.0;
+    }
     return _rewardSequence[index - 1].toDouble();
   }