邹方成
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): 添加称号效果参数验证测试
4.5 KiB
4.5 KiB
目标
- 列表与详情页统一显示“用户、状态、来源、发货状态”等中文枚举名称
- 在订单详情提供“退款”入口（支持全额/部分退款），并完善数据还原（积分、库存/履约、优惠券）与幂等、校验流程
- 支持用户发起退款申请→后台审核→执行退款的闭环
前端改造
枚举与显示
- 新增/复用前端常量映射：
- 订单状态：
{1: 待支付, 2: 已支付, 3: 已取消, 4: 已退款} - 来源类型：
{1: 商城直购, 2: 抽奖票据, 3: 其他} - 发货状态：
{1: 待发货, 2: 已发货, 3: 已签收, 4: 异常} - 抽奖结果：
is_winner(0/1)→否/是、level(1/2/3)→S/A/B
- 订单状态：
- 列表与详情使用映射显示中文名；用户信息显示
nickname（无则显示用户ID）
退款入口与交互
- 详情页添加“退款”按钮：显示可退款金额（默认
actual_amount）、支持部分退款（输入退款金额与原因） - 提交后刷新详情；在详情页增加“退款记录”区块，显示每笔退款状态与时间、原因
- 禁用策略：
- 已取消或已退款不可再次退款
- 货已签收或虚拟已履约需走人工审批（按钮灰显或改为“申请退款”）
后端接口与流程
管理端
- 创建退款：
POST /api/admin/pay/refunds- 入参：
order_no, amount, reason - 校验：订单存在且
status=2；amount>0 && <= 未退款余额 - 幂等：生成
refund_no唯一；重复请求返回既有状态 - 执行：
- 微信真实退款：调用
/v3/refund/domestic/refunds（成功→记录到payment_refunds并落账） - 数据还原：
- 积分：写
user_points_ledger(action=refund_restore, points=points_amount)（按原抵扣金额，部分退款按比例/策略） - 虚拟履约：若
is_consumed=1且可撤销，标记撤销或新建“撤销记录”；否则保留人工处理标记 - 发货：如已发/已签收不自动撤销，标记异常并提示人工流程（退货入库）
- 积分：写
- 订单状态：
- 全额退款→置
status=4已退款 - 部分退款→保持
status=2已支付，记录累计退款额（在payment_refunds中维护）
- 全额退款→置
- 微信真实退款：调用
- 入参：
- 查询退款：
GET /api/admin/pay/refunds、GET /api/admin/pay/refunds/:refund_no - 在订单详情接口增加退款列表聚合（展示退款记录）
用户端退款（申请→审核→执行）
- 用户申请：
POST /api/app/orders/:order_no/refund/apply（金额与原因） - 管理端审核：
POST /api/admin/pay/refunds/:refund_no/approve | /reject - 审核通过→执行退款（同管理端创建退款）；拒绝→记录原因
数据模型建议（支付域）
payment_refunds：refund_no唯一，order_id/order_no/channel/status(submitted/success/abnormal/closed),amount_refund,reason,success_time,raw- 在现有
orders保持order_no唯一；在退款、通知增加幂等校验（refund_no/notify_id）
校验与边界
- 金额单位统一“分”；仅信任后端计算出的可退余额
- 订单来源：抽奖类订单（
source_type=2）需校验抽奖资产状态（user_inventory）是否可撤销 - 已签收/履约完成：默认不自动撤销，需人工处理或审批流；在系统中标注并可导出
幂等与一致性
- 退款：
refund_no唯一；重复请求返回现有记录 - 回调解密与验签：使用 SDK
notify.Handler；退款结果通过回调或主动查询推进记录状态 - 状态推进使用事务与条件更新（如
WHERE status=2）保证并发安全
前端展示增强（详情）
- 信息区块：订单、活动、付款、订单项、发货、积分、退款记录
- 显示中文枚举；金额统一格式化（分→元）或保留分展示
- 退款弹窗：输入金额/原因；显示可退款上限与提示规则（履约/签收需审批）
验收标准
- 列表与详情均显示中文枚举；详情展示活动与付款信息完整
- 管理端可创建退款并正确落账（占位或真实接入）；用户申请退款可走审批流程
- 幂等与边界校验完善；构建与联调通过
实施步骤
- 前端：新增枚举常量并替换列表/详情的显示；详情页加退款按钮与退款记录展示
- 后端：完善退款创建与查询接口、数据还原逻辑与幂等；补充详情接口聚合退款记录
- 用户端：新增退款申请与后台审核接口（可按你需求分阶段）
- 测试与联调：金额/并发/履约/签收边界；通知与查询兜底