邹方成
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): 添加称号效果参数验证测试
74 lines
4.5 KiB
Markdown
74 lines
4.5 KiB
Markdown
## 目标
|
||
- 列表与详情页统一显示“用户、状态、来源、发货状态”等中文枚举名称
|
||
- 在订单详情提供“退款”入口（支持全额/部分退款），并完善数据还原（积分、库存/履约、优惠券）与幂等、校验流程
|
||
- 支持用户发起退款申请→后台审核→执行退款的闭环
|
||
|
||
## 前端改造
|
||
### 枚举与显示
|
||
- 新增/复用前端常量映射：
|
||
- 订单状态：`{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`）保证并发安全
|
||
|
||
## 前端展示增强（详情）
|
||
- 信息区块：订单、活动、付款、订单项、发货、积分、退款记录
|
||
- 显示中文枚举；金额统一格式化（分→元）或保留分展示
|
||
- 退款弹窗：输入金额/原因；显示可退款上限与提示规则（履约/签收需审批）
|
||
|
||
## 验收标准
|
||
- 列表与详情均显示中文枚举；详情展示活动与付款信息完整
|
||
- 管理端可创建退款并正确落账（占位或真实接入）；用户申请退款可走审批流程
|
||
- 幂等与边界校验完善；构建与联调通过
|
||
|
||
## 实施步骤
|
||
1. 前端：新增枚举常量并替换列表/详情的显示；详情页加退款按钮与退款记录展示
|
||
2. 后端：完善退款创建与查询接口、数据还原逻辑与幂等；补充详情接口聚合退款记录
|
||
3. 用户端：新增退款申请与后台审核接口（可按你需求分阶段）
|
||
4. 测试与联调：金额/并发/履约/签收边界；通知与查询兜底
|