邹方成
6ee627139c
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 40s
feat(pay): 添加支付API基础结构 feat(miniapp): 创建支付测试小程序页面与配置 feat(wechatpay): 配置微信支付参数与证书 fix(guild): 修复成员列表查询条件 docs: 更新代码规范文档与需求文档 style: 统一前后端枚举显示与注释格式 refactor(admin): 重构用户奖励发放接口参数处理 test(title): 添加称号效果参数验证测试
44 lines
3.5 KiB
Markdown
44 lines
3.5 KiB
Markdown
## 审计结论摘要
|
||
- 金额统一“分”，积分统一“元等值整数(1元=1积分)”；现有退款登记复用积分流水记录“金额/100”，语义混用。
|
||
- 退款恢复积分在多次部分退款时可能重复恢复导致超恢复；预下单未持久化；前端金额展示直用“分”，体验不佳；订单积分抵扣落账缺失。
|
||
|
||
## 整改目标
|
||
- 明确并统一金额/积分口径：分↔积分换算唯一、无混用。
|
||
- 完善退款与积分恢复逻辑：部分退款按比例恢复、全额退款一次性恢复；幂等保护。
|
||
- 持久化支付域关键数据：预下单/交易/退款/通知；订单详情展示真实字段。
|
||
- 前端金额展示统一为“元”且格式化，枚举与文案一致。
|
||
|
||
## 具体改造项
|
||
1) 数据结构与落账
|
||
- 新增“货币退款流水”独立记录（或新增表`payment_refunds`并在订单详情聚合展示），将每笔退款金额以“分”记录；保留`user_points_ledger`仅记录“积分”类动作（如`refund_restore`）。
|
||
- 在支付阶段补充“订单积分扣减流水”(action=`order_deduct`)，并回填`orders.points_ledger_id`，与实际抵扣金额对应（分→积分换算）。
|
||
|
||
2) 退款恢复与幂等
|
||
- 部分退款按比例恢复积分：`恢复积分 = 订单积分抵扣(分) × 本次退款金额(分) / 实付金额(分) ÷ 100`（四舍五入），累计不超过订单抵扣积分总额。
|
||
- 全额退款一次性恢复剩余积分；为`refund_restore`增加去重幂等：唯一键`(order_no, action='refund_restore')`或累计校验。
|
||
- 订单置“已退款”的条件与部分退款展示：保持`2已支付`，在详情中清晰展示“累计已退款金额(分)”和每笔明细。
|
||
|
||
3) 预下单与交易持久化
|
||
- 引入并使用`payment_preorders/payment_transactions/payment_refunds/payment_notify_events`表：
|
||
- 预下单：落库`out_trade_no=order_no`与`prepay_id`，回填`orders.pay_preorder_id`。
|
||
- 交易：回调落库`transaction_id/amount/success_time/raw`，订单推进。
|
||
- 退款：真实调用后落库`refund_no/amount/status/success_time/raw`，并通过回调/查询推进状态。
|
||
- 通知事件：记录`notify_id/event_type/raw/processed`作审计与去重。
|
||
|
||
4) 前端展示统一
|
||
- 列表与详情金额展示统一格式化为“元”（保留两位小数），并保留原始分用于导出或接口。
|
||
- 详情页展示：交易号`transaction_id`、退款号`refund_no`、渠道/支付方式；“可退余额(分/元)”与“累计已退款(分/元)”。
|
||
|
||
5) 安全与幂等
|
||
- 业务幂等键：`order_no`（预下单/订单推进）、`notify_id`（回调）、`refund_no`（退款）。
|
||
- 数据库唯一索引：`orders.order_no`、`payment_preorders.out_trade_no`、`payment_transactions.transaction_id`、`payment_refunds.refund_no`、`payment_notify_events.notify_id`。
|
||
|
||
## 验收与测试
|
||
- 单元：分↔积分换算正确；部分/全额退款恢复积分计算；幂等重复请求不重复落账。
|
||
- 集成：真实预下单→回调验证→管理端主动退款→退款落库与恢复积分→订单详情展示一致；账单对账拉取与差异比对基础验证。
|
||
|
||
## 执行顺序
|
||
1. 数据表与DAO：新增支付域表与唯一索引；迁移脚本。
|
||
2. 业务与服务：预下单持久化、回调入库、退款入库与恢复积分比例算法、幂等保护。
|
||
3. 前端统一金额展示与详情字段扩展；导出口径对齐。
|
||
4. 测试与联调：场景覆盖与灰度验证，文案与枚举一致。 |