[YinCheng0106]

這個 PR 做了什麼

建立 iOS Weather Widget 的地點目錄（location catalog）基礎架構，讓 DPIP App 可以把使用者已儲存的地點同步到 Widget App Group，供後續每個 Widget instance 的地點設定使用。

此 PR 是 Widget 開發堆疊的第二階段，只處理「地點資料如何提供給原生 Widget / Intents Extension」，不改變目前 Widget 的設定 UI，也不加入 Widget 自行抓取天氣的能力。

主要變更

• 新增 Widget location catalog schema。
• 將 DPIP 已儲存地點輸出至 App Group。
• catalog 內容包含：
  • region code
  • display name
  • administrative area name
  • latitude
  • longitude
• 僅在 saved locations 實際變更時重新發布 catalog。
• 將 catalog coordinator 接入 App lifecycle / bootstrap。
• 擴充 native snapshot writer，使 App Group 可寫入 location catalog。
• 補齊 catalog、coordinator 與 platform bridge 測試。

App Group 資料

位置：

WidgetSnapshots/location-catalog.json

目前 schema：

schemaVersion: 1

範例結構：

{
  "schemaVersion": 1,
  "locations": [
    {
      "regionCode": "242",
      "displayName": "新莊區",
      "administrativeAreaName": "新北市",
      "latitude": 25.0,
      "longitude": 121.4
    }
  ]
}

Current Location 不存入 catalog；它會由後續原生 Widget configuration 當作特殊選項提供。

行為與邊界

• saved locations 新增、移除、取代或重新排序時，catalog 會同步更新。
• 單純切換目前選取地點或 GPS 狀態，不應造成無意義的 catalog rewrite。
• coordinator 的寫入會序列化，避免快速連續變更造成舊結果覆蓋新結果。
• App 關閉 coordinator 後不應繼續發布更新。

驗證方式

建議 reviewer 優先確認：

1. App 儲存地點後，App Group 是否產生：
   WidgetSnapshots/location-catalog.json
2. JSON schema 與欄位是否符合預期。
3. 新增 / 移除 / 重新排序 saved locations 時是否正確更新。
4. 只切換 Home 選取地點時是否不會無意義重新發布。
5. native snapshot writer 是否只允許預期的 snapshot kind / destination。
6. lifecycle start / dispose 與 concurrent writes 是否安全。

相關 Dart tests 涵蓋：

• exact JSON encoding
• empty catalog
• add / remove / replace / reorder
• selection / GPS changes do not republish
• dispose behavior
• concurrent write ordering
• snapshot writer channel arguments

不包含

此 PR 不包含：

• Widget configuration UI
• 每個 Widget instance 的獨立地點選擇
• per-location weather snapshot cache
• Widget native weather fetch
• CoreLocation
• WidgetKit background refresh
• Medium / Large Widget
• 預報 UI

以上功能由後續 PR 分階段處理。

PR Stack

依賴：

• feat(weather): add iOS current weather widget foundation #576 feat/ios-widget-current-weather

後續：

• feat/ios-widget-intent-configuration
  • per-widget location configuration
  • Intent Extension
  • per-location snapshot cache
• feat/ios-widget-weather-refresh
  • native weather fetch
  • Widget self-refresh（開發中）

此 PR 目前以 stacked PR 方式建立，base 是 feat/ios-widget-current-weather。待父 PR 合併後再 rebase / retarget 到 main。

檢查清單

• Location catalog schema 與 App Group write path 已建立
• Saved locations change detection 已建立
• Lifecycle wiring 已建立
• Catalog / coordinator / writer tests 已加入
• 父 PR feat(weather): add iOS current weather widget foundation #576 合併後 rebase / retarget 到 main
• 合併前重新執行 repository gates

[codecov]

Codecov Report

❌ Patch coverage is 91.07143% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 66.43%. Comparing base (fcd37d2) to head (580a042).
⚠️ Report is 19 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/app/app.dart	0.00%	3 Missing ⚠️
lib/bootstrap.dart	0.00%	2 Missing ⚠️

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[lowrt]

LGTM

The merge-base changed after approval.