規格差異

把兩份 .zwag 檔案並排比較，看看變了什麼、又是不是破壞性的變更。為 PR 審查而設計。

如何比較

• 點頂列的 比較（Compare）。
• 選「before」規格檔（例如 main 上的版本）。

差異面板會打開。App 裡目前的規格被視為「after」；你選的檔案是「before」。

什麼算是變更

端點

以 (method, path) 比對。存在性變更：

• 只在「before」裡 → 移除 → 破壞性。
• 只在「after」裡 → 新增 → 非破壞性。
• 兩邊都在 → 變更，再依細節分類。

細節層級的破壞性（不完全列舉；完整清單在 repo 的 docs/specs/done/2026-04-18-spec-diff.md）：

• 新增必填參數，或選填參數改成必填 → 破壞性。
• 請求內容新增，或它的型別被收窄 → 破壞性。
• 既有狀態碼的回應型別變了 → 破壞性。
• 新增選填參數、描述變更、tag 變更、新增回應狀態 → 非破壞性。

型別

以名稱比對。

• 型別被移除 而且 還被任何端點引用 → 破壞性。沒被引用的移除 → 非破壞性。
• 型別新增 → 非破壞性。
• Object：移除欄位、以必填身份新增欄位、欄位從選填 → 必填、欄位型別變更 → 破壞性。反向則為非破壞性。
• String：enum 收縮、新增或收緊 pattern、minLength 上調 / maxLength 下調 → 破壞性。
• Number：min 上調、max 下調、enum 收縮 → 破壞性。

你會看到什麼

• 標題：「N 個破壞性、M 個非破壞性 變更」。
• 兩個區塊：破壞性（紅色 chip）與 非破壞性（石板色 chip）。
• 每一列：[kind] chip + 位置（例如 POST /users）+ 一行摘要。

它不會告訴你的

• 不是完整結構化 diff — 空白與順序會被忽略。
• 沒有遷移指引。它只做分類，不建議修法。
• 一次只能比對兩份規格。
• 沒有 git 整合 — 你要自己選「before」檔案。

典型用途

• PR 審查。 核准規格變更前，把 PR 分支的 .zwag 跟 main 的拿來比對。凡是落進紅色那堆的，都值得在 PR 描述裡寫一段破壞性變更說明。
• 發版前的把關。 把即將發佈的規格跟上一次發佈的拿來比；只要出現破壞性項目，就把 API 版本升大版（major）。