範例與 mock server

離線文件包與本網站附帶可執行的最小範例：Node 與 Python 各一個，對著一個內附的 mock server 跑。

mock server 是什麼、不是什麼

是	不是
一個本機 HTTP 伺服器，回應形狀依照 OpenAPI	真實的 LightUp 環境
用來驗證你的 client 程式、錯誤處理與重試邏輯	授權、限流或效能的模擬
合成資料	任何真實租戶或客戶的資料

mock server 不簽 token。 它發的是不透明的假字串（mock.at.…），只是為了讓範例能跑完整條流程。正式環境的 token 是 ES256 簽章的 at+jwt，會經過完整驗證。對 mock 跑通不代表對正式環境跑得通——授權、開通與資源政策都不在 mock 的範圍內。

範例做什麼

兩個範例做同一件事，方便對照：

用 client_credentials 換 token（機器流程）
GET /v1/me — 確認這張 token 代表誰
GET /v1/persons/{personId}/extensions/{extensionId} — 讀 metadata 與 ETag
PUT 一筆還不存在的，帶 If-None-Match: * — 建立（201）
再建立一次 — 409 already_exists，第一筆沒有被覆蓋
不帶任何前置條件標頭 — 428 precondition_required
PUT 既有那一筆，帶 If-Match — 更新（200）
示範三種可預期的拒絕：
- 401：用一張壞 token
- 403：用一張沒有寫入能力的 token
- 409 revision_conflict：用過期的 If-Match 寫入
讀一個本租戶沒有關係的 person — 404（不是 403；見錯誤的 404 折疊）
從衝突復原：重讀 → 合併 → 帶新的 ETag 重送
模擬管理員停用這支整合 — 下一個請求就是 403 client_disabled，同一張 token 不用等過期

跑起來

# 在 examples/ 目錄下
cp .env.example .env          # 合成設定，可直接用

# Node
node mock-server/server.js &  # 另一個終端機也可以
node node/run.js

# Python
python3 python/run.py

.env.example 裡只有合成值。真實憑證請放在部署環境的 secret 管理，不要寫進任何檔案。

驗證範例與契約一致

範例不是手寫的示意 snippet，它們有測試：

npm test          # Node：範例流程 + 回應對 OpenAPI schema 驗證
pytest            # Python：同一條流程

測試會檢查：範例呼叫的每一個路徑都存在於 OpenAPI（包含 /oauth2/token）；mock 的回應通過 OpenAPI schema 驗證；範例宣稱會發生的 201／401／403／404／409／428 真的發生；token 端點回的是 OAuth 的 TokenError 而不是 Problem。契約改了而範例沒跟上，測試就會紅。