break
cbf909b878
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m6s
40 lines
3.8 KiB
Markdown
40 lines
3.8 KiB
Markdown
## Why
|
||
|
||
当前代理充值只能由平台员工通过线下代充完成；现有代理在线充值入口仅创建本地记录，不能生成微信或支付宝扫码支付内容，也无法在真实收款后可靠、幂等地增加代理主钱包余额。需要补齐桌面端扫码充值闭环，让代理能够安全地为当前店铺主钱包自主充值，同时保持平台线下代充审批链路不变。
|
||
|
||
功能 ID：`feature-034-agent-wallet-qr-recharge`。
|
||
|
||
## What Changes
|
||
|
||
- 代理可在后台选择微信或支付宝，为当前所属店铺的主钱包创建在线充值单；请求不接受目标 `shop_id`。
|
||
- 微信使用 Native 支付、支付宝使用 `alipay.trade.precreate`，后端统一返回原始 `qr_content`，由前端渲染二维码。
|
||
- 代理在线充值金额范围固定为 `10000～100000000` 分，即最低 100 元、最高 100 万元；平台线下代充金额规则不随之改变。
|
||
- 每次主动创建生成新的充值单与支付单；同一次请求重试使用提交账号与 `request_id` 持久化幂等。
|
||
- 支付成功先固化支付事实，再通过可靠 Outbox/Worker 幂等增加代理主钱包余额、写唯一钱包流水并完成充值单。
|
||
- 增加本地支付与入账状态查询，供桌面端页面轮询；不提供 JSAPI、H5、WAP、手机唤起、二维码图片、主动取消、支付方式切换或在线退款。
|
||
- 微信、支付宝回调按 `tb_payment.order_type` 分发代理充值，校验支付配置、渠道、金额、第三方交易号及业务关联，重复回调不得重复入账。
|
||
- 支付单保存创建时的收款身份快照：微信商户号或支付宝应用 ID，联合支付方式与配置 ID 支持后续导出对账；该字段不在在线创建响应中暴露。
|
||
- 平台员工线下代充继续走现有企业微信审批，不与代理在线充值互相复用创建权限或审批状态。
|
||
- 充值创建、列表、详情和在线支付状态响应统一返回稳定来源字段：`platform_offline` 表示平台线下代充，`agent_online` 表示代理在线自充；列表支持按该字段筛选。
|
||
- 复用现有 Fiber、GORM、Asynq、支付 SDK、统一钱包入账、公共 Outbox 与 Integration Log，不新增依赖；本 Change 不建设或接入 Audit Event。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
无。
|
||
|
||
### Modified Capabilities
|
||
|
||
- `agent-recharge`: 将现有代理充值 Stub 扩展为微信/支付宝桌面扫码支付、支付状态收敛和可靠钱包入账完整能力，并收紧代理自主充值权限与在线金额规则。
|
||
|
||
## Impact
|
||
|
||
- API：调整 `POST /api/admin/agent-recharges` 的角色判别请求契约与在线响应；新增可用支付方式和轻量支付状态读取能力。
|
||
- 复杂写主通道：`Handler → Application UseCase → Domain → Repository/Infrastructure`，收口在线创建、支付确认和钱包入账状态机；旧 Service 仅保留未触碰查询或作为迁移门面。
|
||
- 读取辅助通道：`Handler → Query → GORM/DTO`，用于充值列表、详情和支付状态轮询。
|
||
- Infrastructure：扩展微信 Native、支付宝 PreCreate Adapter，复用 `tb_payment`、公共 Outbox、Integration Log 和现有支付回调入口。
|
||
- 数据：增加代理充值支付业务类型、请求幂等、收款身份快照和处理状态所需字段/约束；禁止外键和 GORM 关联标签。
|
||
- 验收：按用户明确要求不新增或运行自动化测试；通过编译、静态检查、迁移演练、接口/数据库人工核对和联调环境真实扫码验证角色权限、100 元边界、请求幂等、回调校验、异步入账与唯一流水。
|
||
- 性能：创建接口只做必要数据库写入与一次渠道预下单；轮询接口走轻量本地查询，避免每次请求第三方，维持 API P95 小于 200ms（第三方预下单耗时单独观测）。
|