先記住：User Story 描述價值，API 還要對齊資料、錯誤與副作用。
需要深入時：再寫 OpenAPI。

User Story 說明目的，還沒說清楚協定

「身為會員，我希望使用優惠券，以便知道折扣後應付金額。」
但後端仍不知道輸入什麼、回傳什麼，前端也不知道失敗怎麼顯示。

User Story 是起點。
要變成可串接的介面，還需要規則、資料語意、回應與錯誤的約定。
OpenAPI 能描述 HTTP API 的操作、參數、schema 與回應，適合把部分契約寫成可共享的形式。

先問這支操作會不會改變大局

「驗證優惠券」可能只是試算，也可能保留一個使用名額。
兩者的副作用不同，逾時後可不可以重送也不同。

因此我會先問：這次操作是否改寫資源？會消耗券嗎？
重新呼叫是否產生額外效果？如果建立訂單需要冪等鍵，鍵的範圍、保存時間與重送語意都必須由雙方確認。
前端不能因為需要恢復流程，就擅自假設有查詢訂單狀態的端點。
可以提出需求，但要留在契約提案區。

從畫面需要反推契約問題

教學案例先提出這些資訊需求：
購物車識別或內容版本、優惠代碼、完整報價、有效期限，以及可供使用者理解的失敗分類。
每個欄位都要補語意。
例如 version 是單調遞增數字、內容雜湊，還是不可解讀的 token？
前端應比較相等還是大小？若沒有約定，就不能自行假設。

錯誤也不能只有一個 message。
穩定的機器可讀分類方便分流；使用者文案則依產品與語系處理。
HTTP 狀態與業務錯誤的組合，必須以實際契約為準。

把驗收一起交出去

我會提供三個示例給後端討論：
有效券回傳同版本報價；
不適用券回傳明確拒絕且不消耗使用次數；
購物車版本已變則要求重新報價。

如果第三種並非後端的實作方式，就共同討論替代機制。
前端的貢獻不是替後端決定內部架構，而是指出畫面需要哪種保證，才能不向使用者傳遞錯誤訊息。
完成後把規格與 Mock 對齊，避免測試永遠使用一份比正式 API 更理想的資料。

可以交給 AI 的 Prompt

請把這則 User Story 整理成 API 契約討論稿。列出輸入、回應、欄位語意、錯誤分類、副作用、重試條件與版本一致性問題。區分已確認與提案；沒有來源的路徑標為待定。再提供正常、業務拒絕與版本衝突的驗收情境，不自行宣稱後端支援。

這段用 SA 把使用者價值連到可觀察的協定。
輸出若只有漂亮 JSON，卻沒有說明金額與錯誤的意義那還是不夠。

今日練習與筆記

選一支每天都在用的 API，試著說明它是否有副作用、null 意義與逾時後的處理。
如果說不清楚，就找到了下一次契約討論的切入點。
接著把分析能力用到競品觀察與技術選型，但會先分清楚看得到的證據和看不到的內部設計。