GenarrativeAI/Genarrative
10
0
Fork 0
Code Issues 24 Pull Requests 8 Actions 2 Packages Projects 1 Releases Wiki Activity

收紧退款人工复核与重试契约

Browse Source 
补齐退款事实对比字段与人工复核审计展示
人工复核重放严格校验管理员、原因和错误码
退款占用重试完整匹配管理员与归一化原因
统一退款原因持久化上限并修复刷新恢复
补充前后端回归测试、生成绑定与数据契约文档
This commit is contained in:
段舒康
2026-07-14 19:20:25 +08:00
parent c70a33d682
commit a597fcd076
15 changed files with 480 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/project-memory/shared-memory/decision-log.md
+2 -2
View File
@@ -4079,9 +4079,9 @@
## 2026-07-13 后台充值退款使用钱包占用与统一用户详情
- 背景：普通 V3 退款已经能从回调、查单和账单收口现金事实，但后台主动退款若先调微信再扣泥点，会在用户余额不足时产生本可避免的欠账；后台各页面也没有统一查询用户余额、绑定状态和充值订单的入口。
- 决策：新增 `profile_recharge_refund_hold`，后台执行退款前按累计部分退款公式原子占用本次应追回的永久泥点，再使用客户端稳定 `requestId` 派生 `out_refund_no` 调微信。部分退款额外占用 1 泥点并发舍入缓冲，防止占用创建后到达的外部退款跨越累计 `floor` 边界；全额退款不加缓冲。`SUCCESS` 扣款并结算匹配占用，`CLOSED` 释放，`PROCESSING / ABNORMAL` 保持；结果未知时不擅自释放，至少等待 10 分钟并连续 3 次退款查单收到官方 `RESOURCE_NOT_EXISTS` 才由 worker 释放。普通消费必须排除全部活动占用。
- 决策：新增 `profile_recharge_refund_hold`，后台执行退款前按累计部分退款公式原子占用本次应追回的永久泥点，再使用客户端稳定 `requestId` 派生 `out_refund_no` 调微信。重试必须同时匹配原订单、退款号、退款金额、管理员和归一化原因，不能绕过底层完整幂等校验。部分退款额外占用 1 泥点并发舍入缓冲，防止占用创建后到达的外部退款跨越累计 `floor` 边界；全额退款不加缓冲。`SUCCESS` 扣款并结算匹配占用，`CLOSED` 释放，`PROCESSING / ABNORMAL` 保持；结果未知时不擅自释放，至少等待 10 分钟并连续 3 次退款查单收到官方 `RESOURCE_NOT_EXISTS` 才由 worker 释放。普通消费必须排除全部活动占用。
- 欠账与冻结：支付侧已经成功退款时不能回滚现金事实；永久泥点不足部分继续只写订单 settlement 的 `unrecovered_points`，限制普通消费，后续永久泥点优先自动偿还。每日免费和会员周期泥点不参与。人工冻结单独使用 `profile_wallet_manual_restriction`，解除人工冻结不解除退款欠账限制。
- 人工复核：交易号或订单总额冲突只允许管理员确认退款归属，退款行追加不可变的管理员、原因、时间和获批错误码后重新运行标准结算；一次确认只豁免对应冲突，其他不变量继续 fail-closed。该操作不是“直接解冻”，余额不足仍形成欠账。会员退款、未知错误和非法结算计划不显示该入口，也不能复用泥点钱包冻结语义。
- 人工复核：交易号或订单总额冲突只允许管理员确认退款归属；管理员 DTO 与确认面板必须并排展示本地订单和微信退款事实的交易号、订单总额与冲突类型。提交请求携带界面所见 `expectedErrorCode`，SpacetimeDB 事务核对当前错误码一致后，退款行才追加不可变的管理员、原因、时间和获批错误码并重新运行标准结算；已处理请求只有管理员、归一化原因和错误码全部一致时才视为幂等重放，状态变化或任一审计内容不一致继续 fail-closed。获批错误码通过正式读取契约展示，一次确认只豁免对应冲突，其他不变量继续 fail-closed。该操作不是“直接解冻”，余额不足仍形成欠账。会员退款、未知错误和非法结算计划不显示该入口，也不能复用泥点钱包冻结语义。
- 发布基线：退款功能和退款事实表尚未进入 release，首次上线只以 release 已有 schema 和数据为迁移基线；不为 master 上未发布的退款中间结构保留旧行 normalization 或历史人工复核兼容。
- 后台边界：充值订单、预检、执行、应急退款号登记、用户详情和钱包冻结均只挂在管理员鉴权路由。用户详情由 `user_id` 或陶泥号经认证服务解析，返回头像、昵称、脱敏手机号、绑定状态、钱包分桶、占用、欠账和最近订单；后台语义明确的用户字段复用同一个图标按钮和弹窗，管理员主体及 `admin:*` 合成 ID 不打开用户详情。
- 部分退款预检：微信支付查单 `trade_state=REFUND` 只表示已发生退款，不代表全额退款。刷新已登记退款后，本地累计成功退款大于 0 且小于订单总额、且不存在非终态退款、活动 hold、欠账或人工冻结时，可以继续退本地剩余额度；没有本地成功退款事实能解释 `REFUND` 时继续失败关闭并要求登记或账单对账。