feat: add commerce reconciliation ledger

docs/refactor/taro-frontend-integration.md

@@ -1752,7 +1752,77 @@ approved/processing -> failed
 - 退款通知地址由支付账户或 `submit_provider_refund.providerNotifyUrl` 配置，后端公开接收路径为 `POST /api/commerce/refunds/notify/wechat_pay?tenantId=<tenantId>`、`POST /api/commerce/refunds/notify/alipay?tenantId=<tenantId>`。这是支付平台回调地址，Taro 前端不要主动调用。
 - 退款通知只会推进已经审核/处理中的退款申请；未审核的 `requested` 退款不能被外部通知直接落账。
 - 已经 `succeeded` 的退款不能再次查询或再次标记成功，避免订单退款金额重复累加。前端应按接口返回状态展示，不要假设点击后立即到账。
-- 自动补偿 worker 已接入：支付漏通知和处理中退款会由后端定时查询供应商并幂等落账。完整资金流水对账、账单下载比对和异常订单运营台后续继续补；生产联调时仍需保留人工确认/失败登记入口。
+- 自动补偿 worker 已接入：支付漏通知和处理中退款会由后端定时查询供应商并幂等落账。资金对账已支持租户后台手工/API 导入供应商账单并查询差异；官方账单自动下载、差错处理工单和异常订单运营台后续继续补。生产联调时仍需保留人工确认/失败登记入口。
+
+### 租户后台资金对账
+
+资金对账是租户后台/财务运营能力，学生端不要接。对账接口只生成差异台账和审计，不会自动修改订单、支付、退款或权益。前端不能根据对账结果自行开通、退款或撤销权益。
+
+预览账单：
+
+```text
+POST /api/commerce/reconciliation/preview
+权限：tenant:reconciliation:read
+body: {
+  "provider": "wechat_pay | alipay | manual",
+  "billDate": "2026-06-29",
+  "billType": "payment | refund | combined",
+  "sourceName": "wechat-bill-20260629.csv",
+  "rows": [
+    {
+      "transactionType": "payment",
+      "orderNo": "<本地 orderNo 或 out_trade_no>",
+      "providerTradeNo": "<微信/支付宝交易号>",
+      "amountCents": 990,
+      "providerStatus": "SUCCESS"
+    },
+    {
+      "transactionType": "refund",
+      "orderNo": "<orderNo>",
+      "refundNo": "<本地 refundNo 或 out_refund_no>",
+      "providerRefundNo": "<支付平台退款单号>",
+      "refundAmountCents": 100,
+      "providerStatus": "REFUND_SUCCESS"
+    }
+  ],
+  "previewLimit": 200
+}
+```
+
+确认导入：
+
+```text
+POST /api/commerce/reconciliation/import
+权限：tenant:reconciliation:write
+```
+
+查询批次、明细和异常：
+
+```text
+GET /api/commerce/reconciliation/batches?provider=wechat_pay&billDate=2026-06-29
+GET /api/commerce/reconciliation/items?batchId=<batchId>&matchStatus=missing_provider
+GET /api/commerce/reconciliation/anomalies?provider=wechat_pay
+```
+
+`matchStatus` 取值：
+
+```text
+matched             本地和供应商账单匹配
+amount_mismatch     金额不一致
+status_mismatch     状态不一致
+missing_local       供应商账单有，本地没有
+missing_provider    本地已支付/退款成功，供应商账单没有
+duplicate           供应商账单重复行
+ignored             无效行或不符合本次 billType
+```
+
+前端处理规则：
+
+- 财务导入页建议使用 preview -> 人工确认 -> import -> anomalies 的流程。
+- `sourceHash` 可作为同一文件内容的识别线索，但当前接口不会阻止重复导入；前端应展示最近同名/同 hash 批次提醒。
+- 金额统一是分，前端不要传元。
+- 对账差异只是运营判断依据，最终订单修正必须走退款、补偿、人工确认或后续差错处理接口。
+- 当前后端支持 JSON 行导入；CSV/Excel 可以先由前端或后续后端 parser 转成上述 `rows`。微信/支付宝官方账单自动下载仍是后续后端任务。
 
 ### 激活码预检查与兑换