---
id: REQ-ios-notification-image
group_id: ai-magic-editor
type: Requirement
feature: ios-notification-image
---

<!-- info-section -->
> status: Reviewed
> update_date: 2025-09-30
> summary_context: 讓 iOS App 在背景或關閉時收到推播通知可以顯示圖片

<!-- id: sec-root -->
# 需求文件 (Requirement): iOS Push Notification 圖片顯示

<!-- id: sec-goal-context -->
### 1. 核心目標與背景 (Goal & Context)

<!-- id: blk-goal, type: list -->
**目標 (Goal)**
  - 讓 iOS App 的 Push Notification 支援圖片顯示功能，提升通知的視覺效果與資訊傳達能力。

<!-- id: blk-user-story, type: list -->
**使用者故事 (User Story)**
  - 身為一個 App 使用者，我想要在收到推播通知時看到圖片，以便更清楚了解通知內容。

<!-- id: blk-context-desc, type: list -->
**背景說明**
  - 後端 `REQ-push-notification-api` 已支援發送包含 Image URL 的 FCM payload
  - iOS App 目前已整合 Firebase Messaging，但尚未實作圖片顯示功能
  - iOS 系統需要透過 Notification Service Extension 來下載並附加圖片到通知內容

<!-- id: sec-functional-scope -->
### 2. 功能與邊界定義 (Functional Scope)

<!-- id: blk-func-req-list, type: list -->
**功能規格 (Functional Requirements)**
  - 當後端 FCM payload 包含 `image` URL 且 App 處於背景或關閉狀態時，通知必須顯示該圖片
  - 支援常見圖片格式：PNG, JPG, GIF
  - 圖片顯示在通知內容中（使用 iOS 系統預設的 Rich Notification 樣式）
  - 圖片下載失敗或超時時，退回顯示純文字通知（不阻斷通知發送）
  - 實作 Notification Service Extension 來處理圖片下載與附加

<!-- id: blk-out-of-scope-list, type: list -->
**範圍外 (Out of Scope)**
  - App 在前景時的圖片通知支援（保持現有行為，未來需求確認後再開發）
  - 自訂 Notification UI（Notification Content Extension）
  - 通知互動按鈕（Action buttons）
  - 影片或其他多媒體格式支援
  - 本地圖片支援（只處理遠端 URL）
  - 通知歷史記錄功能
  - 圖片快取機制（每次重新下載）

<!-- id: sec-non-functional -->
### 3. 非功能規格與限制 (Non-Functional Requirements & Constraints)

<!-- id: blk-non-func-req-list, type: list -->
**非功能規格 (Non-Functional Requirements)**
  - **效能**: 圖片下載超時限制為 5 秒，超時後退回純文字通知
  - **相容性**: 支援 iOS 14.0 以上版本（與 App 最低支援版本一致）
  - **可靠性**: 圖片處理失敗不影響通知本身的正常顯示
  - **安全性**: 只接受 HTTPS 圖片 URL

<!-- id: blk-tech-constraints-list, type: list -->
**技術限制**
  - 圖片大小遵循 iOS 系統限制（< 10MB）
  - Notification Service Extension 有 30 秒執行時間限制
  - Service Extension 只在 App 非前景狀態時被系統調用
  - 需要設定 FCM payload 的 `mutable-content: 1` 才能觸發 Service Extension

<!-- id: sec-use-cases -->
### 4. 使用場景與驗收標準 (Use Cases & Acceptance)

<!-- id: blk-use-cases-list, type: list -->
**使用場景 (Use Cases)**
  - 用戶將 App 切換到背景，後端發送帶有產品圖片的促銷通知，用戶在通知中心看到圖文並茂的通知
  - App 完全關閉時，用戶收到包含活動海報的推播，下拉通知後看到完整圖片
  - 圖片 URL 失效或網路不佳時，用戶仍能收到純文字通知，不會遺漏重要資訊
  - 用戶正在使用 App（前景），收到推播時顯示純文字 banner（現有行為不變）

<!-- id: blk-acceptance-list, type: list -->
**驗收標準 (Acceptance Criteria)**
  - App 在背景或關閉狀態時，收到包含有效 `image` URL 的推播，通知必須顯示圖片
  - 圖片下載成功後，通知樣式為 Rich Notification（可展開查看完整圖片）
  - 圖片下載失敗或超過 5 秒超時，通知退回顯示純文字（標題 + 訊息）
  - 只接受 HTTPS 圖片 URL，HTTP URL 視為無效並退回純文字通知
  - App 在前景時，通知行為與現有實作一致（不顯示圖片）
  - 測試圖片格式：PNG, JPG, GIF 皆可正常顯示
  - 後端無需更改 API，沿用現有 FCM payload 格式（需確認 `mutable-content: 1` 設定）