foodie-server/specs/027-offline-transfer-payment/contracts/api.md

API Contracts: 線下轉賬支付

日期：2026-09-03 | 风格：沿用项目规范（@RequestHeader String token、@RequestParam/@RequestBody 显式注解、DTO 承载）

新增接口（后端）

1. 商家收款账户查询（收银台展示用）

GET /chanting/store/bankInfo?id={storeId}

• 鉴权：匿名（@Anonymous，同 getstore 风格）
• 逻辑：pos_store.id=storeId → user_id → info_user，取 bankAccountName / bankName / bankAccountNo

• 返回：

  // 三项齐全
  { "code": 200, "data": { "accountName": "AMAZEWAY LIMITED", "bankName": "國泰世華銀行", "accountNo": "1234567890" } }
  // 任一为空 → 收银台隐藏「線下支付」选项
  { "code": 200, "data": null }
  

• App 用法：选项显示条件 = data != null；展开卡片显示三字段（参考原型），建议账号行带复制按钮。

2. 商家确认转账收款

GET /system/orderShOprate/confirmTransferPayment?id={orderId}
Header: token（商家，须有该店权限 requireMerchantOrderAccess）

• 逻辑（镜像 confirmCashPayment）：
  1. 校验 payType == 6，否则 no.order.paytype.not.transfer
  2. 校验 state != 4（已取消），否则 no.order.transfer.cancelled
  3. 校验 payStatus != 1，否则 no.order.transfer.already.paid
  4. payStatus 0→1；orderLogHelper 记「商家{名}确认转账收款」
  5. 外送单(type=0)调 deliveryOrderNotificationService.notifyOrderAvailable(order) 推送附近骑手
• 返回：{ "code": 200 } 或国际化错误

3. 骑手接单门禁（修改现有接口）

GET /system/orderQsOprate/acceptOrder（现有）增加校验：

• payType == 6 && payStatus != 1 → 拒绝，no.order.transfer.not.paid（「商家确认收款后骑手才能接单」）

复用接口（App 端直接用，无改动）

接口	用途
POST /infouser/user/../createOrder（paymentMethod="6"）	转账单创建，透传 payType=6，无需后端改动
骑手 orderList（tab=newTask）	已过滤 payStatus=1，转账单确认前不可见（零改动）
GET /chanting/store/bankList	026 已交付，银行名称字典（商家资料侧用）

后端国际化 key（五份 properties）

ruoyi-admin/src/main/resources/i18n/messages{,_zh_CN,_zh_TW,_en_US,_vi}.properties：

key	zh_CN 文案
no.order.paytype.not.transfer	该订单不是转账支付订单
no.order.transfer.cancelled	订单已取消，不能确认收款
no.order.transfer.already.paid	该订单已确认收款
no.order.transfer.not.paid	商家确认收款后骑手才能接单

商家 Web（foodie-store）

• index.vue paymentTypeLabel 映射加 6: 'OfflineTransfer'；i18n index 命名空间四语言：
  • zh：线下转账 / tw：轉賬支付 / en：Transfer Payment / vi：Chuyển khoản

App 端交互说明（交付给 App 团队，不在本期代码内）

1. 收银台：进入时调 bankInfo，data != null 才显示「線下支付」选项（副标题「轉賬後請聯繫客服確認」）；选中展开红色提示（轉帳完成後，請透過即時通訊客服發送憑證…）+ 灰底卡片三行（帳戶名稱/銀行名稱/銀行帳戶）；提交下单 paymentMethod=6。
2. 商家 App：转账单显示「轉賬支付」标签；待收款单提供「確認收款」按钮调 confirmTransferPayment；确认后订单进入正常接单/出餐流程。
3. 骑手 App：无需改动——未确认单本来不可见不可接；确认后单出现在抢单列表并收到推送。