feat(M08-B): 补保洁微信转账回调与轮询

2026-06-29 10:47:54 +08:00
parent b07c451700
commit a1bace2dac
12 changed files with 446 additions and 21 deletions
@@ -140,3 +140,17 @@
  - Body：`mode?: "API" | "MOCK"`，`note?: string`。
  - 说明：对 `CONFIRMED` 保洁结算单发起微信商家转账。`API` 模式会校验门店/全局微信收款账户、商户凭据、保洁员微信 openid 和转账场景配置；`MOCK` 仅非生产环境可用。
  - 返回：成功转账直接返回 `PAID` 结算单；微信返回 `FAIL` 时记录失败原因；微信返回待确认或处理中状态时保留 `CONFIRMED`，并返回 `payoutState`、`payoutReference` 和 `payoutPackageInfo`。
+
+## 2026-06-29 微信转账回调与轮询增量
+
+- `POST /admin-api/cleaning/settlements/:settlementId/wechat-transfer/sync`
+  - 登录：必须。
+  - 权限：`cleaning.task.write`、`tenant.manage` 或 `PLATFORM_ADMIN`；服务层继续校验 `cleaning.settlement.write`。
+  - Body：`note?: string`。
+  - 说明：按结算单商户转账单号主动查询微信商家转账状态；`SUCCESS` 自动标记 `PAID`，`FAIL` 记录失败原因，其它中间态保留 `CONFIRMED` 并更新 `payout_state`。
+
+- `POST /app-api/cleaning/wechat-transfer/notify`
+  - 登录：不需要，依赖微信支付通知签名验证。
+  - Headers：`wechatpay-timestamp`、`wechatpay-nonce`、`wechatpay-serial`、`wechatpay-signature`。
+  - Body：微信支付 v3 加密通知原文。
+  - 说明：服务端用原始 body 验签解密，校验商户号后按 `out_bill_no` 或 `transfer_bill_no` 定位保洁结算单，并写回成功、失败或中间态。