Repository navigation
docs(api): QPESUMS in seconds, trend range works, radar no-store - #678
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
這個 PR 做了什麼
把
api.md三個與伺服器實際行為對不上的描述改成 2026-11-16 的實測結果。三處都是「文件說的和後端做的不一樣」,不是新功能,所以沒有動任何程式碼。改動內容(只有
api.md,+11/−10):[baseMs, Δ, …]、{ms}用 13 位數;實際上清單是 Unix 秒(每 600 秒一筆),tile 路徑的{sec}是 10 位數,送 13 位數毫秒會回 500。同時註明framesFromList原樣使用清單的值,所以 App 的既有行為不受影響。?range已經生效。 原文有一整段說「後端忽略range參數、7d等同 24 小時」(2026-08-02 的實測),現在trend/{id}?range=7d會回"range":"7d"與 168 筆逐時資料;不帶參數仍是 24 小時、24 筆。改成「已生效」並保留舊觀測的時間點,讓之後的人看得出這是後端補上的。Cache-Control是no-store,不是max-age=300。 實測是no-store加弱 ETag,重新驗證回 304;文件原本寫的快取策略會讓人以為可以省掉 revalidation。沒有做的事:
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 實際打伺服器時發現文件與行為不符,直接修文件。
怎麼驗
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)tool/dev/analyze.sh乾淨(本 PR 沒動 Dart,仍跑過)