Skip to content

feat: use the region hosts and the redundancy the backend now has - #671

Open
whes1015 wants to merge 6 commits into
mainfrom
feat/region-pinned-hosts
Open

whes1015 wants to merge 6 commits into
mainfrom
feat/region-pinned-hosts

Conversation

@whes1015

@whes1015 whes1015 commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

這個 PR 做了什麼

後端這個月把三件事做完了:雷達/QPESUMS/DPM 的資料複製到東京與台南兩區、notify/location 改成「台南 primary + 東京 307 熱備援」、並替底圖與對時準備了分區主機。App 還停在舊假設上——三個圖層釘死台南、底圖與對時走不分區的裸名稱——所以這個 PR 把客戶端接上去,並把「每個端點家族到底有沒有備援」寫成 api.md 的一節、以及伺服器狀態頁看得出來的一張表。

15 個端點家族裡,改動前只有 7 個跟著區域容錯(跨出台灣的只有 5 個);改動後 10 個、跨國 8 個。剩下 5 個是真的只有一份資料(衛星、風場、氣象 v5、事件),不是還沒接。

程式

  • 圖層(lib/features/weather/data/frame_tile_api.dart、lib/features/disaster_map/data/disaster_map_api.dart):FrameTileApi 的 list/tile tier 由 static const 改成依 path 決定的 getter,radar 與 qpesums 走 coreApi/coreStatic,衛星與風場維持 coreExclusiveApi/coreStaticExclusive(後端只有一份,指過去只會把區域故障變成空白圖層)。DisasterMapApi 的 DPM 由 coreStaticExclusive 改 coreStatic。
  • 底圖與 OSM(lib/shared/map/、lib/core/network/api_region.dart):新增 staticLbOrigin(LbRegion),basemapOriginTileUrl/terrainOriginTileUrl/gsiOriginTileUrl/gsiSourceProperties/terrainSourceProps 由常數改為吃 region 的函式。region 來自 RegionSelection:BaseMap.build 用 watch(改區時 style 換到另一台),MapScaffold 的預熱器、GSI overlay 與 basemap_overlay_sync 用 read。_styleCache 的鍵多了 region,etag_interceptor.isBasemapPbf 改成前綴比對(舊快取列還是裸主機)。
  • 內附種子(lib/shared/map/basemap_seeder.dart):這一項不是順手改的——種子資料列是用樣板產生的 URL 當鍵,釘區之後 MapLibre 改抓 static.lb-<region>,原本的種子列就永遠不會命中,離線首啟會沒有底圖。所以 BasemapSeeder 現在收 region,種在選定區的樣板下;換區之後另一台由網路補。
  • 對時(lib/core/realtime/http_time_source.dart、lib/bootstrap.dart、ios/DPIPWidgets/WidgetHTTPTimeSource.swift):defaultHosts 由 ['api.lb.exptech.dev'] 改為依選定區順序產生(hostsFor(regions.lbOrder)),bootstrap 傳入。不再用裸名的理由是量出來的:同一天對四台 lb-* 讀 /ntp,有兩台的讀數比對後慢 15.7 秒,而裸名是由 Cloudflare 決定你問到哪一台。iOS widget 沒有區碼設定,固定 tpe1 → khh1。
  • notify/location(lib/features/notification/data/notify_api.dart、lib/core/geo/location_api.dart、lib/core/network/dio_client.dart):沒有改 tier。tnn1 是 primary,tyo1 只是導回它的替代節點;把 tier 改成區域備援會讓 standby 被當成等價來源,寫入路徑就分岔了。改的是把這件事寫清楚,並用一個測試釘住「Dio 預設跟隨 307,且 3xx 不會落到 validateStatus」。
  • 伺服器狀態頁(lib/features/status/presentation/pages/server_status_page.dart、lib/core/network/endpoint_health.dart):支援矩陣追平現實(Core API 的 TYO1 有 RTS、雷達、QPESUMS;Core Static 的 TYO1 不再整欄不支援),新增第五種 cell 狀態「熱備援」(⇄ 圖示)。順手修兩個真的會記錯的分類:EndpointService.ofPath 只認 /api/v2/trem/rts,但歷史實際走 /api/v3/trem/rts,所以 RTS 歷史的健康一直被記成 other;測站是 /resource/station,從來沒被歸到 tremStation。

文件

  • api.md:多活表補齊雷達/QPESUMS 的 list 與 tile、DPM 的 tile 與三個詳情;雷達/QPESUMS/DPM/海嘯四節從「沒多活」搬到多活區(tier 與主機改成 coreApi/coreStatic、{tyo1,tnn1}),並說明 tile 由 MapLibre 直接抓、換台是「選定區優先的一台」而不是逐塊重試。底圖節改「lbStatic,依選定區釘一台」加「釘選沒有自動換台」;種子說明補「種在選定區的樣板下」。/ntp 節與開頭那條 bare-host 說明改成區域主機+hostsFor(regions.lbOrder)。notify/location 補熱備援(307 導回 tnn1)。curl 表換成 2026-11-20 的 API/static 雙表與與前次的差異。
  • ARCHITECTURE.md:Networking 段寫明「備援是 tier 的屬性,不是 feature 的」,並列出兩個表達不了的例外(底圖釘選、notify 熱備援);Calibrated time 段的 /ntp 改區域主機、說明 bare 名為何退役。

測試

  • 新增 test/core/network/dio_redirect_test.dart:本機 HttpServer 回 307 指到 /notify/primary,確認 createDio().get 跟過去、只打一次主路徑(307 是實測到的狀態碼,不是 301)。
  • 新增 endpoint_health_test.dart 的 ofPath follows the families that moved off the exclusive tiers;server_status_page_test.dart 加「Core API 的 TYO1 對 location/notify 顯示熱備援」、圖例測試改成五種狀態。
  • 地圖相關的 widget 測試補 ChangeNotifierProvider<RegionSelection>(base_map_tab_test、map_scaffold_test、map_page_test、report_detail_page_test、report_replay_page_test、home_map_backdrop_widget_test、home_page_test);basemap_seeder_test/basemap_seed_test 的 URL 改由 basemapOriginTileUrl(region) 產生,後者改成比對路徑而不是主機。
  • home_map_backdrop_widget_test 的 native view 假物件改成只回報一次建立:style 依 region 重建時,第二次 onPlatformViewCreated 會讓 maplibre fork 的 _controller.complete 丟 Bad state: Future already completed。

沒做的

  • 衛星、風場、氣象 v5、事件(api-1)沒有備援可言,App 也沒有假裝有。
  • 沒有做「依延遲自動選區」;選區仍由使用者決定,這個 PR 只是讓每一條請求都老實跟著它。
  • 沒有在實機或模擬器上看過畫面。iOS 模擬器測試在這台機器上跑不起來(見「怎麼驗」),所以狀態頁的 ⇄ cell、圖例與底圖換區都是靠 widget 測試驗的。

相關 issue

沒有對應的 issue。

怎麼驗

  • tool/check.sh → all gates passed(3827 tests,11 skipped)
  • tool/dev/analyze.sh → No issues found!
  • tool/check/commits.sh origin/main..HEAD → commit gate: 6 commit(s) OK
  • 本機的 tool/dev/test_ios.sh 跑不起來(DTServiceHubClient failed to bless service hub、The test runner hung before establishing connection,一條測試都沒跑到),所以 ios/RunnerTests 是在 CI 上驗的:iOS job 的 Test (ios/RunnerTests) 與 WidgetFixtureUITests 都過了,WidgetHTTPTimeSourceTests 的兩個 host 斷言在裡面。
  • 主機行為是用 curl 對 api.lb-{tpe1,khh1}、api.core-{tyo1,tnn1}、api-1 與兩台 static 打同一組路徑驗的(看狀態碼與 x-served-by),不是靠文件推論。
  • 安全關鍵的部分:這個 PR 沒有動 EEW 推估、警報門檻或通知內容,動的是「請求打到哪一台」。時鐘那段沒有放寬驗證——讀數仍然要與回應的 Date 標頭對得上,換台只是換一台來讀。

檢查清單

  • tool/check/commits.sh origin/main..HEAD 通過
  • 一個 commit 一件事(6 則:圖層、底圖、對時、熱備援 UI、健康分類、文件)
  • flutter analyze 與 flutter test 通過(透過 tool/dev/analyze.sh、tool/check.sh)
  • 新的使用者可見字串走 AppLocalizations(statusLegendStandby,12 個語系)
  • CI 全部通過:build 13m13s、Android 35m49s、iOS 56m10s、code-review、codecov/project、codecov/patch 全部 pass,Instrumented skipped
  • UI 用的是既有 token(Icons.swap_horiz + colorScheme.tertiary,沿用同一張卡片與圖例樣式);深色模式沒有截圖可附,因為沒有跑起來的模擬器

@codecov

codecov Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 90.36145% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.67%. Comparing base (3b1020d) to head (5e90387).

Files with missing lines Patch % Lines
lib/bootstrap.dart 0.00% 5 Missing ⚠️
lib/core/network/etag_interceptor.dart 66.66% 1 Missing ⚠️
lib/core/realtime/http_time_source.dart 75.00% 1 Missing ⚠️
lib/shared/map/map_scaffold.dart 95.23% 1 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 lowrt added this to the v27.1 milestone Nov 20, 2026

@whes1015 whes1015 left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

看過 head c08bd0c。CI 都過了,但有幾處要改,先別合。

  1. lib/core/network/endpoint_health.dart:74 與 :152:即時串流是 SseMux 的 /api/v1/sse(ApiPaths.sse),ApiClient.openStream 在 api_client.dart:254 用這條 path 記健康。ofPath 沒有這條,會落到 other。原本 allOfPath 會讓一條連線同時更新 EEW 與 RTS 兩列,方法跟「shared realtime stream」測試一起被刪了,狀態頁這兩列不會再動。請把 /api/v1/sse 記回 eew 與 rts,並把測試加回來。
  2. api.md:154:EarthquakeApi.openEewSse、:155 的 openTremSse 程式裡沒有。現在是同一條 SseMux,/api/v1/sse,topic 為 eq.eew.v1 與 trem.rts.v1。表後「RTS 走 /api/v1/trem/sse」那段也要改。ARCHITECTURE.md 把 SseMux「一條連線兩個 topic」刪掉了,跟程式不符,請補回來。
  3. api.md:262:getRestroomDetail 與 :263 的 getShelterDetail 寫成 coreStaticExclusive、只釘 static.core-tnn1。DisasterMapApi._detail 三支都走 _tier = coreStatic,上面的層級表也寫 DPM 詳情是 coreStatic。這兩列請改成跟程式一樣。
  4. api.md:530:「App 仍釘在 tnn1、App 未跟上」跟這支 PR 相反。雷達、QPESUMS、DPM 已經改走 coreApi/coreStatic。請改成 App 已跟上;衛星、風場、氣象 v5 仍是單點再另外寫。
  5. api.md:121(還有 :128、:295、:430)與 dio_client.dart、NotifyApi、狀態頁熱備援註解都寫 301;同一份文件的實測表 :505、:509、:533 寫 core-tyo1 回 307。301 會被當永久轉址快取,307 不會,不能混用。請跟實測對齊,dio_redirect_test 也改測實際的狀態碼。

Agent 代 whes1015 審核(Discord !YuYu1015 要求)

Comment thread lib/core/network/endpoint_health.dart Outdated
s.lastSuccess = _now();
s.state = EndpointState.healthy;
}
final key = _keyOf(EndpointService.ofPath(path), tier, hostUrl);

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

即時串流走 SseMux 的 ApiPaths.sse(/api/v1/sse),ApiClient.openStream 會把這條 path 傳進來。ofPath 沒有這條,第 74 行會落到 other。這裡原本用 allOfPath,一條連線同時更新 EEW 與 RTS 兩列;方法跟測試一起被刪了,狀態頁這兩列就不會再動。請讓 /api/v1/sse 同時記到 eew 和 rts,並把那組測試加回來。

Comment thread api.md Outdated
| 類別.方法 | 路徑 | 層級 | 主機(容錯順序 = 選定區域優先) |
|---|---|---|---|
| `SseMux.lb` | `/api/v1/sse?topics=…[&mode=live]` | `lbApi` | `api.lb-{tpe1,khh1}.exptech.dev` |
| `EarthquakeApi.openEewSse` | `/api/v2/eq/eew?sse=1&compress=1` | `lbApi` | `api.lb-{tpe1,khh1}.exptech.dev` |

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

EarthquakeApi.openEewSse、下一行的 openTremSse 在程式裡都不存在。現在的即時連線是 SseMux:/api/v1/sse,topic 為 eq.eew.v1 與 trem.rts.v1。這列和後面「RTS 走 /api/v1/trem/sse」那段請改成實際的類別、路徑和 topic。

Comment thread api.md Outdated
|---|---|---|---|
| `DisasterMapApi.tileUrl` | `/api/v2/tiles/dpm/{layer}/{z}/{x}/{y}.mvt` | `coreStatic` | `static.core-{tyo1,tnn1}.exptech.dev` |
| `DisasterMapApi.getAedDetail` | `/api/v2/tiles/dpm/aed/{id}` | `coreStatic` | `static.core-{tyo1,tnn1}.exptech.dev` |
| `DisasterMapApi.getRestroomDetail` | `/api/v2/tiles/dpm/restroom/{id}` | `coreStaticExclusive` | `static.core-tnn1.exptech.dev` |

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

getRestroomDetail 和下一行的 getShelterDetail 寫成 coreStaticExclusive、只釘 static.core-tnn1。DisasterMapApi._detail 三支(含 AED)都用同一個 _tier = coreStatic。上面的層級表也寫 DPM 詳情是 coreStatic。這兩列請改成跟程式一樣。

Comment thread api.md Outdated
### 與 2026-08-02 的差異

- **雷達、QPESUMS、DPM 已經複製到 `tyo1`**:list、tile、DPM 詳情都是真的第二個
origin(`x-served-by: core-tyo1`,ETag 與 tnn1 不同)。App 仍釘在 tnn1,

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「App 仍釘在 tnn1、所以這是後端已就緒、App 未跟上」跟這支 PR 相反。雷達、QPESUMS、DPM 的 list/tile/詳情已經改走區域層級。請改成 App 已跟上;衛星、風場、氣象 v5 仍是單點再另外寫。

Comment thread api.md Outdated
| `/api/v2/tiles/qpesums/list` | 404 | 404 | **200** | 200 | 404 |
| `/api/v2/tiles/wind/gfs/list` | 404 | 404 | 404 | 200 | 404 |
| `/api/v5/meteor/weather/list` | 404 | 404 | 404 | 200 | 404 |
| `/api/v2/notify/{token}` | 404 | 404 | 307 | 401 | 429 |

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

這格實測 core-tyo1 的 notify 是 307,第 509、533 行也寫 307。同一份文件第 121、128、295、430 行,以及 dio_client.dart、NotifyApi、狀態頁熱備援註解都寫 301。301 會被當永久轉址快取,307 不會。請跟這張實測表對齊,dio_redirect_test 也改測實際的狀態碼。

@whes1015
whes1015 force-pushed the feat/region-pinned-hosts branch from c08bd0c to 1773e23 Compare November 20, 2026 06:21
Platform: all

New(zh-Hant): 雷達、QPESUMS 與災害地圖的圖層不再固定向台南要圖,選東京時直接由東京供應
New(en-US): radar, QPESUMS and disaster-map layers are served by the core region you picked instead of always asking Tainan
Platform: all

Optimization(zh-Hant): 底圖、地形與 OSM 圖層改由你選的區域供應,並把內附離線底圖種在同一台
Optimization(en-US): the basemap, terrain and OSM layers come from the region you picked, with the bundled offline tiles seeded under the same host
Platform: all

Optimization(zh-Hant): HTTPS 對時改問你所在區域的節點,不再交給 Cloudflare 平衡到可能慢 15 秒的後端
Optimization(en-US): the HTTPS clock fallback asks your region's node instead of letting Cloudflare balance it onto a node that may be 15 seconds behind
Platform: all

Fix(zh-Hant): 伺服器狀態頁的即時震度與測站列不再一直空白——歷史路徑與測站 CSV 現在記到正確的服務
Fix(en-US): the RTS and station rows on the server-status screen stop sitting blank — the history path and the station CSV are filed under the service they belong to
Platform: all

New(zh-Hant): 伺服器狀態頁分得出「熱備援」:備援節點平常把寫入導回主節點,只有異常才接手
New(en-US): the server-status screen tells a hot standby apart: the standby node redirects writes to the primary until it has to take over
@whes1015
whes1015 force-pushed the feat/region-pinned-hosts branch from 1773e23 to 5e90387 Compare November 20, 2026 06:30

@whes1015 whes1015 left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

看過 head 5e90387。上次的程式問題都改了,CI 也都過了(codecov、iOS、Android、build、changes、code-review;Instrumented skipped)。文件還有要改的,先別合。這是你自己的 PR,不能核准。

已對上:

  • lib/core/network/endpoint_health.dart:84:/api/v1/sse 經 allOfPath 同時記 eew 與 rts,the shared realtime stream 測試在。
  • api.md 改成 SseMux.lb 的 /api/v1/sse,openEewSse/openTremSse、/api/v1/trem/sse 都拿掉了。ARCHITECTURE.md 補回一條連線、多個 topic。
  • 廁所、避難所詳情跟 AED 一樣是 coreStatic。
  • 雷達/QPESUMS/DPM 寫成 App 已換成 coreApi/coreStatic;衛星、風場、氣象 v5 仍單點。
  • 301 都改成 307,dio_redirect_test 用 HttpStatus.temporaryRedirect。

還要改:

  1. api.md:195:海嘯那段寫成「coreApi(多活)而非 coreApi」。搬段落時把 coreExclusiveApi 蓋掉了,句子自己打自己。改回「而非 coreExclusiveApi」。
  2. api.md:232:底圖種子那句換行掉了 >,「主機名下…」跑出引用,下一行又接回去。補回 >。
  3. api.md:97:事件名只寫了 trem.rts.v1。EEW 的 topic 是 eq.eew.v1,請一起寫上。
  4. api.md:447:結尾還在講 ?sse=1。現在的串流是 /api/v1/sse?topics=,上面那張表也是這條。?sse=1 請改掉,不然跟表對不上。

Agent 代 whes1015 審核(Discord !YuYu1015 要求)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants