Skip to content

docs(api): QPESUMS in seconds, trend range works, radar no-store - #678

Merged
whes1015 merged 1 commit into
mainfrom
docs/api-md-refresh
Nov 20, 2026
Merged

whes1015 merged 1 commit into
mainfrom
docs/api-md-refresh

Conversation

@whes1015

Copy link
Copy Markdown
Member

這個 PR 做了什麼

把 api.md 三個與伺服器實際行為對不上的描述改成 2026-11-16 的實測結果。三處都是「文件說的和後端做的不一樣」,不是新功能,所以沒有動任何程式碼。

改動內容(只有 api.md,+11/−10):

  1. QPESUMS 時間清單是秒,不是毫秒。 原文寫 [baseMs, Δ, …]、{ms} 用 13 位數;實際上清單是 Unix 秒(每 600 秒一筆),tile 路徑的 {sec} 是 10 位數,送 13 位數毫秒會回 500。同時註明 framesFromList 原樣使用清單的值,所以 App 的既有行為不受影響。
  2. 氣象 ?range 已經生效。 原文有一整段說「後端忽略 range 參數、7d 等同 24 小時」(2026-08-02 的實測),現在 trend/{id}?range=7d 會回 "range":"7d" 與 168 筆逐時資料;不帶參數仍是 24 小時、24 筆。改成「已生效」並保留舊觀測的時間點,讓之後的人看得出這是後端補上的。
  3. 雷達 tile 的 Cache-Control 是 no-store,不是 max-age=300。 實測是 no-store 加弱 ETag,重新驗證回 304;文件原本寫的快取策略會讓人以為可以省掉 revalidation。

沒有做的事:

  • 雷達/QPESUMS 章節標題上的 core-tnn1 沒有改。後端已經把這兩個家族複製到 tyo1,但那是 PR feat: use the region hosts and the redundancy the backend now has #671 的內容,這裡只修與伺服器行為有關的事實,不搶它的範圍。
  • api.md 的 curl 表仍是 2026-08-02 的版本,沒有重跑(這份 PR 只改三個已重測過的段落)。

相關 issue

沒有對應的 issue。這三點是 2026-11-16 實際打伺服器時發現文件與行為不符,直接修文件。

怎麼驗

  • 對照 2026-11-16 的實測:
    • GET /api/v2/tiles/qpesums/list → 清單值是 10 位數秒;把同一個 tile 的 {sec} 換成 13 位數毫秒 → 500。
    • GET /api/v5/meteor/weather/trend/{id}?range=7d → "range":"7d"、168 筆;不帶 range → "range":"24h"、24 筆。
    • GET 任一 radar tile → Cache-Control: no-store +弱 ETag;帶 If-None-Match 重驗證 → 304。
  • git diff origin/main..HEAD -- api.md 只有這三段(見上方統計),沒有碰到其他章節的內容。

檢查清單

  • tool/check/commits.sh origin/main..HEAD 通過(commit gate: 1 commit(s) OK)
  • 一個 commit 一件事(三個實測更正,同一份文件的同一個目的)
  • tool/dev/analyze.sh 乾淨(本 PR 沒動 Dart,仍跑過)
  • 沒有新的使用者可見字串
  • CI 全部通過 —— 見 checks
  • 沒有 UI 變更

Checked against the live endpoints on 2026-11-16: the QPESUMS list and tile path use 10-digit seconds (milliseconds return 500; framesFromList passes the values through, so the app is unaffected), trend/{id}?range=7d now returns 168 hourly rows, and radar tiles send Cache-Control: no-store with a weak ETag.
@whes1015
whes1015 merged commit fbbab92 into main Nov 20, 2026
3 of 4 checks passed
@whes1015
whes1015 deleted the docs/api-md-refresh branch November 20, 2026 19:36
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.

1 participant