更新日志：版本、契約變更與遷移指引
內容層 API 的版本記錄與變更政策：近期版本事實（v4.8→v4.9.1）、契約變更的三級分類（兼容增量/行爲變更/破壞性）、遷移指引的固定格式，以及「怎麼訂閱變更」的機器可讀入口。
更新日志是 API 提供方的信用記錄：改了什麼、什麼時候改的、你需要做什麼——三問都有答案的日志才是日志，只有版本號的叫計數。本頁記錄內容層 API 的近期版本事實與變更政策，機器可讀的版本入口是 GET /api/health（version/build 字段實時可查）。本文屬於開發者中心欄目；契約全貌在API 參考總覽。
近期版本記錄（事實口徑，可在 health/審計面對照）
| 版本 | 變更摘要 | 契約影響 |
|---|---|---|
| v4.9.1 | 行情數值字段幫助顯式 null（POST/PUT /api/admin/markets）：無實測數據存 NULL 而非 0；控制臺行情表 null 顯示「—」 | 兼容增量：公開 /api/markets 響應中 price 等字段可能爲 null——數值消費方需判空（此前無 null 行） |
| v4.9.0 | 雷達頁共享控制臺會話（免二次登入）；管理端新增 GET /api/admin/credentials-status（憑據輪換狀態，無明文）；docs 端點數改由註冊表注入（=56，單一事實來源） | 兼容增量：新端點 + 文案數字修正（73→56 爲勘誤，舊數字從未對應真實註冊表） |
| v4.8.2 | 管理端文章列表 SELECT 補 primary_kw/cta 字段（修復六維統計恆 4/6） | 兼容增量：列表響應字段補全 |
| v4.8.1 | 內容頁 aria 全鏈路補全；課時頁 pager 規格化（rel=prev/next）；課程頁章節導航 | 無 API 影響（渲染層） |
| v4.8.0 及更早 | 草稿預覽令牌化（axs_* 會話 + no-store/noindex）、內容體檢 stats 字段、批量發布動作、題庫獨立端點（/api/admin/quiz）等 | 見各版本當期公告 |
記錄紀律：只寫可驗證的事實（health 的版本號、審計日志的動作、端點註冊表的數字）——「性能提升 200%」這類無對照口徑的句子不進本頁。
變更政策：三級分類
- L1 兼容增量（加端點/加字段/加可選參數）：隨版本直接上線，日志記錄——調用方無需動作（前提：你忽略未知字段，見總覽的兼容承諾節）；
- L2 行爲變更（同字段語義調整/默認值變化，如 v4.9.1 的 null 語義）：提前在本頁公告 + 控制臺橫幅，給≥2 周對照期；受影響面（哪些端點哪些字段）逐項列出；
- L3 破壞性變更（刪端點/改字段類型/收緊鑑權）：原則上不發生；確需發生時提前≥90 天公告 + 雙軌過渡期（新舊並行）+ 逐調用方的遷移指引——v1 公開契約至今零 L3 變更，這是要維持的記錄。
遷移指引的固定格式
每次 L2/L3 變更的指引都按四段寫（歷史指引同格式可溯）：①變了什麼（端點/字段/行爲，前後對照代碼塊）；②誰會受影響（按調用模式列出，如「對 price 直接 .toFixed() 的前端代碼」）；③怎麼改（最小 diff 示例）；④怎麼驗證改對了（可復制的斷言命令）。示例（v4.9.1 的 null 語義）：
# ①變了什麼：/api/markets 的 price/change_* 可能爲 null（此前恆爲數字）
# ②誰受影響：對數值字段直接運算/格式化的消費方
# ③怎麼改：判空分支
# 舊: const label = "$" + m.price.toFixed(2)
# 新: const label = m.price == null ? "待實測" : "$" + m.price.toFixed(2)
# ④驗證：
curl -s https://axionserve-portal.aeronest-global.workers.dev/api/markets | python3 -c "
import json,sys; rows=json.load(sys.stdin)
nulls=[r['symbol'] for r in rows if r.get('price') is None]
print('null 價錢的 symbol 數:', len(nulls))" # 你的 UI 對這個數字都應顯示「待實測」而非 $0兩個真實案例：契約演進長什麼樣
- 案例一（勘誤型，v4.9.0）：docs 頁文案曾寫「73 個 API 端點」，與端點註冊表實數不符——修復方式不是改數字，而是把數字改爲從註冊表注入（單一事實來源），文案與數據從此不可能漂移。啓示：數字類文案的正確形態是「生成」不是「手寫」；
- 案例二（語義型，v4.9.1）：行情 price 字段從「恆爲數字（無數據存 0）」變爲「可爲 null（無實測即 null）」——0 是編造的實測值，null 才是誠實的未知。影響面：對 price 直接格式化的消費方需要判空分支（遷移模板見上文）。這是 L2 行爲變更的標準處理：公告 + 影響面清單 + 對照期 + 驗證命令。
訂閱變更：機器可讀入口
- 輪詢 health：
GET /api/health的 version/build 變化 = 有新部署（ETag 條件請求，成本近零——模板在Webhook 與事件）； - 本頁 RSS 化：站點 feed（/feed.xml 類端點）覆蓋內容更新；本頁重大變更會同步發布一篇 articles 類公告（可被 feed 捕獲）；
- 控制臺公告：L2 級以上的變更在控制臺頂部橫幅提示（登入即見）。
版本語義與部署形態
本站版本號爲 v4.x.y 三段式：x 段對應架構級演進（含數據庫遷移與渲染層重構的裏程碑版本），y 段對應功能批次（一輪迭代的補丁集，如 v4.9.0 的三項功能），修訂位對應單點修復與語義微調（如 v4.9.1 的 null 幫助）。部署形態是單文件 Worker + 構建標籤：每次部署的產物哈希寫入 x-axion-build 響應頭，與本頁版本記錄一一對應——你在任何響應頭裏看到的 build 值，都能在本頁找到它屬於哪個版本、改了什麼。這個對應關系是可驗證性的最小閉環：版本號說謊容易，構建哈希對不上就難了。
給對接方的三條建議
- 把 health 檢查放進你的 CI：每天一次，version 變化時自動跑你的集成測試——契約漂移在當天發現而不是用戶投訴時；
- 錯誤碼分支寫全：40xxx（改參數）、401xx/403xx（查令牌）、429xx（退避）、5xx（重試）——四類分支齊全的客戶端對任何變更都有基本韌性；
- 記錄你依賴的行爲：把「我依賴列表按 published_at 倒序」這類隱性依賴寫進你的測試斷言——變更公告再完善，也不如你自己的斷言先紅。
相關文檔：API 參考總覽 · Webhook 與事件 · SDK 與庫。調試臺 /docs 實時反映當前版本端點面；欄目首頁回開發者中心。