YS CART – 綠界 ECPay

⚠️ 升級順序（請先讀）

本版硬性需求 YS CART core >= 2.57.0。請先把核心升級到 2.57.1，再更新本外掛。

核心版本不足時，本外掛會停在啟動守門：不註冊任何金流、物流方式、REST 路由或 CLI，只在後台顯示提示。若順序顛倒，結帳頁的綠界付款方式與物流建單會暫時消失，直到核心升級完成。

新增

• 信用卡退款（query-first 狀態機）：先查 `CreditDetail/QueryTrade` 關帳狀態，再依綠界官方流程分流——已授權→N（僅全額）、要關帳全額→E 後接 N、要關帳部分→R、已關帳→R；狀態未知一律拒絕操作。
• crash-safe 冪等防護：以核心 `refund_request_id` 為冪等鍵。同請求已成功→需完整證據才判定冪等重放；傳輸不確定（timeout／非 2xx／無 RtnCode）一律維持 pending，拒絕盲目重送；只有 provider 明確拒絕才可重試。
• 原子式退款 reservation：仲裁與寫入在同一個 CAS closure 內完成，併發下只有一個請求能 reserve 成功；任何 `DoAction` 都必須在 reservation 落盤之後。
• 交易指紋比對：金額／`TradeNo`／`MerchantTradeNo`／`gwsr`／環境／商店代號 typed-present 且型別敏感；舊紀錄缺指紋一律視為「無法證明是同一筆」。
• 不可變 result event：每一步金流動作追加 append-only 紀錄（step、attempted／executed、傳輸分類、RtnCode／RtnMsg、回應交易編號、指紋摘要、時間戳）。
• 訂單級退款凍結：存在任何結果未明的退款請求即拒絕新退款操作，直到人工核定。
• `wp ys-cart-ecpay refund-attempt` CLI（list／resolve；resolve 為真 CAS conditional UPDATE）。
• 信用卡查詢檢查碼（CreditCheckCode） 設定欄位：加密儲存，與 payment 憑證同一原子管線；建單改送 `NeedExtraPaidInfo=Y` 並持久化授權單號（gwsr）。
• 分期／紅利／銀聯／無法證明付款方式的交易一律導向人工退款（fail-closed）。

變更（core 2.57.0 配對）

• 宣告核心硬性需求 `YS_CART_ECPAY_REQUIRES_CORE = 2.57.0`；能力探測新增 `YSPaymentDetailStore` 與 `YSPaymentDispatch::current_operation_key`。核心整個缺席也改為 notice-only（不再靜默）。
• `payment_detail` 的所有寫入委派核心共用 CAS（`YSPaymentDetailStore`）；物流 callback 的 shipping 投影同步走此 CAS——付款通知、退款 ledger、物流投影從此是同一個 JSON 欄位的協調 writer。
• `MerchantTradeNo` 改由核心穩定 operation key 導出。

目前限制（請留意）

• 信用卡退款待受控正式商店實測（綠界 stage 環境官方不提供 DoAction）。gate 完成前 自動退款預設關閉，維持 record-only／manual-only；`ys_ec_ecpay_auto_refund_enabled` 需明確開啟。
• 測試模式（stage）直接拒絕退刷。
• ATM／超商／條碼維持人工退款；僅信用卡宣告 `supports_gateway_refund()`。

驗證

• 乾淨 clone × 正式核心 2.57.1：完整回歸 25 檔全綠。
• 兩次獨立乾淨 clone 重建，ZIP 位元組相同（`sha256 c898bc68…`）。
• 套件內容契約 26/0：67 檔 + 30 目錄，逐檔與 git HEAD blob 位元相同。