商店 Escrow：為商店所有者提供安全的付款
當玩家從使用者擁有的商店購買商品時，付款不再立即發送給商店所有者。相反，代幣由伺服器保管在 escrow 中，直到買家確認收到貨物。只有在此之後，商店所有者才會收到付款——98% 在鏈上，外加 2% 的伺服器佣金。
為什麼需要 Escrow？
沒有 escrow，商店所有者可能會收到付款後從不發貨。買家將無法追索。Escrow 保護雙方：
- 買家可以在貨物未交付或與描述不符時對訂單提出爭議。付款將被凍結，直到管理員審查該案件。
- 商店所有者在買家確認後保證收到付款——或者如果買家未採取行動，則在 7 天後自動收到付款。
工作原理
1 買家付款
買家將全額付款發送到伺服器的營運錢包。代幣被保管在 escrow 中。訂單狀態被設定為 escrow。
2 買家確認收貨
買家呼叫 POST /shop/confirm-receipt 確認已收到貨物。伺服器立即將付款的 98% 在鏈上發送到商店所有者的錢包。伺服器保留 2% 的佣金。
3 7 天後自動釋放
如果買家在 7 天內未確認或提出爭議，付款將自動釋放給商店所有者。背景工作程序每小時檢查一次過期的 escrow。
4 爭議解決
如果買家不滿意，可以呼叫 POST /shop/dispute 凍結付款。然後管理員透過 POST /shop/admin/resolve-payout 審查該案件，並執行以下操作之一：
- 釋放付款給商店所有者，或
- 退款——付款被取消，代幣保留在伺服器（買家可以手動獲得補償）。
付款狀態參考
| Status | Meaning |
|---|---|
none | 官方商店或無訂單 |
escrow | 代幣由伺服器保管，等待買家確認 |
disputed | 買家提出爭議，等待管理員審查 |
paid | 98% 已在鏈上發送給所有者 |
refunded | 管理員取消付款，代幣保留在伺服器 |
failed | 鏈上轉帳失敗 |
API 端點
| Endpoint | Who | Purpose |
|---|---|---|
POST /shop/confirm-receipt | 買家 | 確認收貨 → 釋放 escrow |
POST /shop/dispute | 買家 | 對訂單提出爭議 → 凍結 escrow |
POST /shop/admin/resolve-payout | 管理員 | 解決爭議（釋放或退款） |
GET /shop/my-payouts | 商店所有者 | 查看 escrow + 已付款總額和歷史記錄 |
錢包選擇
付款發送到商店所有者的錢包，使用與付款相同的鏈：
| Payment Currency | Owner Wallet Used |
|---|---|
| CC (Cash Coins) | CC wallet（備用：KC wallet） |
| KC (Keshe Coins) | KC wallet |
收益分成
| Recipient | Share |
|---|---|
| 商店所有者 | 98% |
| 伺服器佣金 | 2% |
2% 的佣金用於覆蓋基礎設施成本：區塊鏈 gas（如適用）、伺服器託管以及 escrow 服務本身。
官方商店
官方 Erleuchtung 商店（伺服器擁有，owner_id IS NULL）不納入 escrow 系統。官方商店商品的付款直接進入伺服器，不進行付款分割。
後續計畫
Escrow 系統現已上線。商店所有者可以透過 GET /shop/my-payouts 端點追蹤其待處理的 escrow 餘額和已付款收益。用於管理付款、確認收貨和提交爭議的前端儀表板將在即將發布的版本中推出。