{
  "metadata": [
    {
      "key": "id",
      "value": "REQ-ios-notification-image"
    },
    {
      "key": "group_id",
      "value": "ai-magic-editor"
    },
    {
      "key": "type",
      "value": "Requirement"
    },
    {
      "key": "feature",
      "value": "ios-notification-image"
    }
  ],
  "info": [
    {
      "key": "status",
      "value": "Reviewed"
    },
    {
      "key": "update_date",
      "value": "2025-09-30"
    },
    {
      "key": "summary_context",
      "value": "讓 iOS App 在背景或關閉時收到推播通知可以顯示圖片"
    }
  ],
  "title": "需求文件 (Requirement): iOS Push Notification 圖片顯示",
  "sections": [
    {
      "id": "sec-goal-context",
      "title": "1. 核心目標與背景 (Goal & Context)",
      "summary": null,
      "blocks": [
        {
          "id": "blk-goal",
          "type": "list",
          "title": "目標 (Goal)",
          "items": [
            "讓 iOS App 的 Push Notification 支援圖片顯示功能，提升通知的視覺效果與資訊傳達能力。"
          ]
        },
        {
          "id": "blk-user-story",
          "type": "list",
          "title": "使用者故事 (User Story)",
          "items": [
            "身為一個 App 使用者，我想要在收到推播通知時看到圖片，以便更清楚了解通知內容。"
          ]
        },
        {
          "id": "blk-context-desc",
          "type": "list",
          "title": "背景說明",
          "items": [
            "後端 `REQ-push-notification-api` 已支援發送包含 Image URL 的 FCM payload",
            "iOS App 目前已整合 Firebase Messaging，但尚未實作圖片顯示功能",
            "iOS 系統需要透過 Notification Service Extension 來下載並附加圖片到通知內容"
          ]
        }
      ],
      "children": []
    },
    {
      "id": "sec-functional-scope",
      "title": "2. 功能與邊界定義 (Functional Scope)",
      "summary": null,
      "blocks": [
        {
          "id": "blk-func-req-list",
          "type": "list",
          "title": "功能規格 (Functional Requirements)",
          "items": [
            "當後端 FCM payload 包含 `image` URL 且 App 處於背景或關閉狀態時，通知必須顯示該圖片",
            "支援常見圖片格式：PNG, JPG, GIF",
            "圖片顯示在通知內容中（使用 iOS 系統預設的 Rich Notification 樣式）",
            "圖片下載失敗或超時時，退回顯示純文字通知（不阻斷通知發送）",
            "實作 Notification Service Extension 來處理圖片下載與附加"
          ]
        },
        {
          "id": "blk-out-of-scope-list",
          "type": "list",
          "title": "範圍外 (Out of Scope)",
          "items": [
            "App 在前景時的圖片通知支援（保持現有行為，未來需求確認後再開發）",
            "自訂 Notification UI（Notification Content Extension）",
            "通知互動按鈕（Action buttons）",
            "影片或其他多媒體格式支援",
            "本地圖片支援（只處理遠端 URL）",
            "通知歷史記錄功能",
            "圖片快取機制（每次重新下載）"
          ]
        }
      ],
      "children": []
    },
    {
      "id": "sec-non-functional",
      "title": "3. 非功能規格與限制 (Non-Functional Requirements & Constraints)",
      "summary": null,
      "blocks": [
        {
          "id": "blk-non-func-req-list",
          "type": "list",
          "title": "非功能規格 (Non-Functional Requirements)",
          "items": [
            "**效能**: 圖片下載超時限制為 5 秒，超時後退回純文字通知",
            "**相容性**: 支援 iOS 14.0 以上版本（與 App 最低支援版本一致）",
            "**可靠性**: 圖片處理失敗不影響通知本身的正常顯示",
            "**安全性**: 只接受 HTTPS 圖片 URL"
          ]
        },
        {
          "id": "blk-tech-constraints-list",
          "type": "list",
          "title": "技術限制",
          "items": [
            "圖片大小遵循 iOS 系統限制（< 10MB）",
            "Notification Service Extension 有 30 秒執行時間限制",
            "Service Extension 只在 App 非前景狀態時被系統調用",
            "需要設定 FCM payload 的 `mutable-content: 1` 才能觸發 Service Extension"
          ]
        }
      ],
      "children": []
    },
    {
      "id": "sec-use-cases",
      "title": "4. 使用場景與驗收標準 (Use Cases & Acceptance)",
      "summary": null,
      "blocks": [
        {
          "id": "blk-use-cases-list",
          "type": "list",
          "title": "使用場景 (Use Cases)",
          "items": [
            "用戶將 App 切換到背景，後端發送帶有產品圖片的促銷通知，用戶在通知中心看到圖文並茂的通知",
            "App 完全關閉時，用戶收到包含活動海報的推播，下拉通知後看到完整圖片",
            "圖片 URL 失效或網路不佳時，用戶仍能收到純文字通知，不會遺漏重要資訊",
            "用戶正在使用 App（前景），收到推播時顯示純文字 banner（現有行為不變）"
          ]
        },
        {
          "id": "blk-acceptance-list",
          "type": "list",
          "title": "驗收標準 (Acceptance Criteria)",
          "items": [
            "App 在背景或關閉狀態時，收到包含有效 `image` URL 的推播，通知必須顯示圖片",
            "圖片下載成功後，通知樣式為 Rich Notification（可展開查看完整圖片）",
            "圖片下載失敗或超過 5 秒超時，通知退回顯示純文字（標題 + 訊息）",
            "只接受 HTTPS 圖片 URL，HTTP URL 視為無效並退回純文字通知",
            "App 在前景時，通知行為與現有實作一致（不顯示圖片）",
            "測試圖片格式：PNG, JPG, GIF 皆可正常顯示",
            "後端無需更改 API，沿用現有 FCM payload 格式（需確認 `mutable-content: 1` 設定）"
          ]
        }
      ],
      "children": []
    }
  ]
}