让代理充值复用现有网页支付能力
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 8m7s

微信按当前 v2/v3 配置分别生成 MWEB/H5 链接,支付宝复用 C 端 WAP 链接,并让可用支付方式基于生效配置判断。

Constraint: 支付链接统一通过 qr_content 返回,由前端渲染二维码;按要求不运行测试

Rejected: 微信 Native 与支付宝当面付 | 会引入非当前商户配置所需的额外产品开通

Confidence: high

Scope-risk: moderate

Directive: 微信 H5/MWEB 二维码仅承诺系统相机或外部浏览器扫码链路

Tested: 相关 Go 包编译通过;gofmt 与 git diff --check 通过

Not-tested: 按用户要求未运行自动化测试及真实支付联调
This commit is contained in:
2026-07-30 11:41:50 +08:00
parent 0f4f0d1176
commit 8fc667daee
24 changed files with 692 additions and 352 deletions

View File

@@ -40,7 +40,7 @@
|新增02企业微信审批接入|企微配置、模板映射、扫码绑定、审批运行和业务详情|Token、模板版本、上传提交、回调解密、轮询补偿和异常恢复|57小时|810小时|企微可信域名、模板 ID 变化、回调网络和真实账号权限会增加 48 小时|
|新增03站内通知|顶部铃铛、通知抽屉、通知中心和受控跳转|通知表、模板注册、接收人解析、未读/已读 API|34小时|34小时|前端多端布局差异、接收人关系不完整会增加 23 小时|
|新增04全局多视角审计|审计中心七个视角、详情抽屉和敏感字段展示|Audit Event、Integration Log、旧写入口切换、历史投影和脱敏|68小时|811小时|旧审计调用点遗漏、查询性能和历史字段差异会增加 510 小时|
|新增05代理钱包扫码充值|支付方式选择、二维码、倒计时和支付状态轮询|微信 Native、支付宝 PreCreate、支付单分发和钱包入账恢复|34小时|57小时|支付渠道配置、真实回调、微信 v2/富友差异会增加 36 小时|
|新增05代理钱包扫码充值|支付方式选择、二维码、倒计时和支付状态轮询|微信 v3 H5/v2 MWEB、支付宝 WAP 支付 URL、支付单分发和钱包入账恢复|34小时|57小时|支付渠道配置、真实回调、富友差异会增加 36 小时|
|全链路联调与发布|联调全部页面状态、修复交互、准备发布版本|数据核对、存量回填、旧入口清理、停机发布和恢复检查|34小时|45小时|生产数据与预期差异、外部回调不可达会增加 48 小时|
|**合计**|**前端约 5989 小时**|**后端约 93128 小时**|**约 812 人日**|**约 1216 人日**|**1 后端 + 1 前端并行时,正常目标 1215 个工作日;历史数据或换货迁移超预期时可能到 16 个工作日**|

View File

@@ -65,7 +65,7 @@
| D-16 | 数据同步保留轮询兜底关键业务事件按立即、3 分钟、5 分钟触发;超频不建立退避状态 | 数据同步 |
| D-17 | 企微发起身份按账号类型分流:平台/超级管理员必须扫码绑定并使用本人 `userid`,代理使用部署配置中的固定企微账号代提交;真实业务提交人始终独立进入审批表单、通知和审计 | 企微审批 |
| D-18 | 全系统审计本次一次性切换到 Audit Event + Integration Log多视角 API 和前端同时发布 | 全局 |
| D-19 | 代理在线充值最低 100 元,支持微信 Native 和支付宝 PreCreate,支付成功直接入主钱包且不审批 | 21、新增充值 |
| D-19 | 代理在线充值最低 100 元,按配置使用微信 v3 H5/v2 MWEB 和支付宝 WAP 支付 URL,支付成功直接入主钱包且不审批 | 21、新增充值 |
| D-20 | 资产层只展示一个预计最终到期时间;当前套餐和全部排队主套餐共同参与推算,临期也使用同一结果 | 06、11、22 |
| D-21 | 换货完成时新资产自动继承旧资产店铺;旧资产保留原店铺用于历史查询和权限追踪 | 禅道 #98 |
| D-22 | 店铺可选绑定一个平台业务员该字段只表达业务归属不恢复需求16的分销和佣金关系 | 禅道 #96 |
@@ -1179,7 +1179,7 @@ CHECK (
|------|------|
| 修改角色默认额度 | 只更新角色模板和审计,不扫描、不修改任何已有店铺钱包 |
| 创建店铺 | 在创建事务中读取默认角色模板并初始化代理主钱包实际额度 |
| 修改额度 | 拒绝代理账号;校验平台独立权限、加载主钱包、校验新可用金额、按 `version` 条件更新、写信用变更审计 |
| 修改额度 | 拒绝代理账号;校验平台独立权限、加载主钱包、校验新可用金额、按服务端读取的 `version` 条件更新、写信用变更审计 |
| 钱包扣款 | 使用有效额度计算可用金额,同事务更新余额、版本和资金流水 |
| 查询/导出 | Query 返回 `credit_enabled``credit_limit``available_balance``is_in_debt``debt_amount` |
@@ -1190,7 +1190,7 @@ PUT /api/admin/shops/{id}/credit-limit 独立调整信用额度
GET /api/admin/shops/fund-summary 返回信用和可用金额
```
角色页面显示“新建代理默认信用额度”,并明确提示“修改后不会影响已有店铺”。店铺资金页面独立显示和修改实际信用额度。前端只展示接口返回的可用金额,不自行重新计算;额度调整弹框显示修改前后金额预览,并发冲突时刷新最新钱包版本
角色页面显示“新建代理默认信用额度”,并明确提示“修改后不会影响已有店铺”。店铺资金页面独立显示和修改实际信用额度。前端只展示接口返回的可用金额,不自行重新计算;额度调整弹框显示修改前后金额预览,乐观锁版本由后端读取和校验
资金概况中的 `is_in_debt` 表示 `balance < 0``debt_amount = max(-balance, 0)`;冻结金额只影响现金可用金额和总可用金额,不直接记为欠款。额度调整只改变资金边界,不伪造一条金额为零的钱包交易流水;变更前后值进入全局 Audit Event。
@@ -1344,7 +1344,7 @@ sequenceDiagram
#### 代理在线扫码充值
- 代理只能为当前店铺主钱包充值,最低 `10000`100 元)。
- 支持微信 Native 和支付宝 `alipay.trade.precreate`,创建本地充值单和 `tb_payment(order_type=agent_recharge)`再预下单
- 按当前配置使用微信 v3 H5 或 v2 MWEB并复用支付宝 `alipay.trade.wap.pay` 支付 URL,创建本地充值单和 `tb_payment(order_type=agent_recharge)`生成链接
- 每次主动创建都生成新的充值单和支付单;`request_id` 只防同一次 HTTP 提交重试,不按金额或已有待支付单复用。后端原样返回第三方 `qr_content`,前端使用二维码组件渲染,不生成后端图片文件。
- 不返回 `expires_at`,也不展示本地推算的精确倒计时;支付是否成功、关闭或失效以第三方回调和受控查单结果为准。前端每 3 秒轮询的轻量接口只读取本地状态,不直接触发第三方查单。
- 微信/支付宝回调按支付单类型分发,校验渠道、支付配置、金额、第三方交易号和业务单关联。
@@ -1426,7 +1426,7 @@ POST /api/admin/agent-recharges/{id}/reject
- 统计待审批退款、平台员工线下充值和历史终态记录数量。
- 轮换用户 demo 中泄露的企微 Secret、Token 和 EncodingAESKey配置可信域名、应用可见范围和回调地址。
- 发布并验证退款、线下充值企微模板控件映射,验证代理固定代提交成员可用,并要求会发起审批的平台/超级管理员完成扫码绑定。
- 验证微信 Native、支付宝 PreCreate 配置和回调地址,确认代理充值支付渠道可用。
- 验证微信 v3 H5/v2 MWEB、支付宝 WAP 配置和回调地址,确认代理充值支付渠道可用且支付宝无需开通当面付
- 盘点旧账号、资产、轮询日志的写入口和查询入口,确认统一审计切换清单。
- 停机窗口内由业务使用超级管理员配置普通角色导出字段并抽样验证;不运行默认授权迁移,永久禁止导出的字段不进入代码目录。

View File

@@ -1514,7 +1514,7 @@
接口GET /api/admin/agent-recharges/payment-methodsPOST /api/admin/agent-rechargesGET /api/admin/agent-recharges/{id}/payment-statusGET /api/admin/agent-recharges/{id}下线offline-pay和reject旧接口。
在线规则代理只充当前店铺且不提交shop_id最低10000分支持微信Native和支付宝PreCreate每次主动创建都是全新充值单和支付单统一返回qr_content且不返回expires_at。支付回调和受控查单进入同一幂等确认用例并校验金额、配置、交易号和业务单先固化支付成功与入账Outbox再由可靠Worker独立事务更新主钱包、版本、唯一流水、充值完成状态和审计。重复回调或任务不重复入账迟到成功不能吞掉已付资金。
在线规则代理只充当前店铺且不提交shop_id最低10000分按当前配置使用微信v3 H5或v2 MWEB并复用支付宝WAP支付URL前端自行渲染二维码支付宝无需开通当面付每次主动创建都是全新充值单和支付单统一返回qr_content且不返回expires_at。支付回调和受控查单进入同一幂等确认用例并校验金额、配置、交易号和业务单先固化支付成功与入账Outbox再由可靠Worker独立事务更新主钱包、版本、唯一流水、充值完成状态和审计。重复回调或任务不重复入账迟到成功不能吞掉已付资金。
线下规则:仅平台/超管创建金额大于0目标店铺和15个结构化付款凭证必填金额提交后固定创建后提交企微审批只能同意或拒绝。通过后自动增加代理主钱包并写流水无操作密码recharge:{recharge_no}防重;驳回终结原单且不支持退回/重提,撤销/删除为已关闭;通过后撤销且已入账不自动扣回。

View File

@@ -50,7 +50,7 @@
| #55 套餐分配生效条件 | 套餐和分配接口已支持默认值、覆盖值和最终生效值 | 创建/编辑套餐传 `expiry_base`;分配时传 `expiry_base_override`,展示 `effective_expiry_base` |
| #60 店铺联系电话搜索 | 店铺列表已支持 11 位联系电话精确查询 | 将输入值作为 `contact_phone` 查询参数传给店铺列表接口 |
| #86 资产换货标识和跳转 | 资产解析接口已返回 `exchange_trace.previous_asset/next_asset``can_view` | 仅 `can_view=true` 且存在资产 ID 时允许跳转;该需求前端已对接可保持现状 |
| #38 代理信用额度 | 角色默认额度、店铺实际额度、资金概况和负可用余额均已有接口 | 使用分单位字段;更新时携带钱包 `version`;余额为负数时正常展示 |
| #38 代理信用额度 | 角色默认额度、店铺实际额度、资金概况和负可用余额均已有接口 | 使用分单位字段;调额不传钱包 `version`,并发控制由后端负责;余额为负数时正常展示 |
| #94 状态同步和运营商回调 | 后端回调、定时触发和原轮询链路已装配 | 通常无前端新调用;状态页面继续读取现有资产状态字段 |
| #96 店铺业务员 | 店铺创建/更新、候选人、列表/详情和筛选都已支持业务员 | 创建/编辑店铺选择 `business_owner_account_id`;列表可按该 ID 筛选并展示名称 |
| #98 换货新资产继承旧店铺 | 换货完成时后端自动继承旧资产店铺归属 | 前端继续调用原换货完成接口,不新增分配步骤 |
@@ -89,7 +89,7 @@
| --- | --- | --- |
| #60 联系电话搜索 | `GET /api/admin/shops?contact_phone=11位号码` | 精确查询;可与店铺名称、编号等条件组合 |
| #96 店铺业务员 | `GET /api/admin/shops/business-owner-candidates``POST /api/admin/shops``PUT /api/admin/shops/:id``GET /api/admin/shops` | 创建/更新传 `business_owner_account_id`;列表可用同名参数筛选,响应展示账号 ID、名称和可用状态 |
| #38 信用额度 | `PUT /api/admin/roles/:id/default-credit``PUT /api/admin/shops/:id/credit-limit``GET /api/admin/shops/fund-summary` | 角色接口配置新建代理默认值;店铺接口传 `credit_enabled + credit_limit + version`;金额单位均为分 |
| #38 信用额度 | `PUT /api/admin/roles/:id/default-credit``PUT /api/admin/shops/:id/credit-limit``GET /api/admin/shops/fund-summary` | 角色接口配置新建代理默认值;店铺接口`credit_enabled + credit_limit`,乐观锁由后端管理;金额单位均为分 |
| #55 套餐默认生效条件 | `POST /api/admin/packages``PUT /api/admin/packages/:id``GET /api/admin/packages/:id` | 请求使用 `expiry_base=from_activation|from_purchase`;响应展示默认生效条件名称 |
| #55 分配覆盖 | `POST /api/admin/shop-package-batch-allocations``PATCH /api/admin/shop-package-allocations/:id/expiry-base` | 分配时使用 `expiry_base_override``null` 表示跟随套餐默认值 |
| #43 系列套餐多选 | `POST /api/admin/shop-series-grants``PUT /api/admin/shop-series-grants/:id/packages` | `packages` 是 1100 项数组,每项包含 `package_id``cost_price`,删除时传 `remove=true` |

View File

@@ -426,7 +426,7 @@ GET /api/admin/bulk-purchases/{task_id}/items?status=4&page=1&page_size=50
### 在线支付与入账
- 继续使用现有支付配置,只按 `wechat``alipay` 选择当前可用配置,不建设多通道自动路由、优先级或故障转移。
- 微信使Native,支付宝使`alipay.trade.precreate`。后端把第三方返回的字符串或 HTTPS URL 原样映射为 `qr_content`,前端渲染二维码;后端不生成二维码图片或新增二维码生成接口。
- 微信C 端 H5,支付宝`alipay.trade.wap.pay`。后端把支付 HTTPS URL 原样映射为 `qr_content`,前端渲染二维码;后端不生成二维码图片或新增二维码生成接口,支付宝无需开通当面付
- 创建接口不返回 `expires_at`,前端不展示本地推算的精确倒计时。本地时间不能判定第三方支付单是否失效,支付成功或关闭以回调和后端受控查单为准。
- `request_id` 只防止同一次提交重试。代理每次主动创建或再次拉起支付都使用新 `request_id` 并产生新的充值单和支付单,旧单等待第三方自然收敛,不复用、不主动取消。
- 支付回调或查单先在事务中固化真实收款事实:支付单已支付、充值单 `2=已支付``processing_status=1`并可靠写入钱包入账 Outbox随后 Worker 在独立事务中更新钱包和版本、创建唯一流水、将充值单改为 `3=已完成``processing_status=2`并写资金审计。入账失败使用 `processing_status=3`可靠重试,不回滚支付事实。

View File

@@ -1,6 +1,6 @@
# 新增需求 05代理钱包扫码充值
> 状态:已冻结,本文保留为实施明细;如有冲突,以标准评审稿和 UR#34 PRD 为准。
> 状态:2026-07-30 修正支付产品选择,本文保留为实施明细;如有冲突,以标准评审稿和 UR#34 PRD 为准。
> 评审主文档:`../../7月迭代技术方案-标准评审稿.md`
> 实施 PRD`../../../../.scratch/ur34-agent-recharge/PRD.md`
> 范围:代理在后台使用微信或支付宝扫码充值代理主钱包。
@@ -12,8 +12,8 @@
3. 单笔最低充值金额为 100 元,即 `10000` 分。
4. 代理在线充值不进入企业微信审批;支付成功事实先落库,再由可靠 Worker 幂等增加代理主钱包余额。
5. 平台员工线下代充值仍按 `02-企业微信审批接入.md` 走企微审批,与本方案隔离。
6. 后端返回支付二维码内容,前端使用现有二维码组件渲染,不由后端生成或保存二维码图片文件。
7. 微信使用 Native 支付,支付宝使`alipay.trade.precreate` 当面付预创建
6. 后端返回支付 URL,前端使用现有二维码组件渲染,不由后端生成或保存二维码图片文件。
7. 微信按当前配置使用 v3 H5 或 v2 MWEB,支付宝 C 端 `alipay.trade.wap.pay` 手机网站支付;不要求开通 Native 或当面付产品
8. 支付回调、钱包入账、钱包流水和审计必须幂等,重复回调不能重复加钱。
9. 当前代理充值复杂写逻辑迁移到 Application/Domain旧 Service 不再保留另一套在线入账逻辑。
@@ -46,9 +46,9 @@ sequenceDiagram
Agent->>Web: 输入金额并选择支付方式
Web->>API: 创建扫码充值单
API->>DB: 创建充值单和支付单
API->>Pay: Native/PreCreate 预下单
Pay-->>API: 二维码内容
API-->>Web: 原样返回 qr_content
API->>Pay: 生成 H5/WAP 支付链接
Pay-->>API: HTTPS URL
API-->>Web: URL 写入 qr_content 返回
Web-->>Agent: 展示二维码并轮询支付状态
Agent->>Pay: 扫码完成支付
Pay->>Callback: 异步支付通知
@@ -87,9 +87,9 @@ internal/
│ ├── post_wallet.go 可靠任务执行钱包入账
│ ├── sync_pending.go 受控查询待支付第三方订单
│ └── get_payment_status.go 轻量支付状态查询
├── infrastructure/adapter/payment/
│ ├── wechat_native.go 微信 Native 预下
│ └── alipay_precreate.go 支付宝当面付预创建
├── infrastructure/payment/
│ ├── wechat_web.go 微信 H5/MWEB 支付链接与查
│ └── alipay_wap.go 支付宝 WAP 支付链接与查单
├── infrastructure/persistence/
│ └── agent_recharge_repository.go
└── query/agentrecharge/
@@ -123,7 +123,7 @@ internal/
- 钱包乐观锁冲突时由 Application 重新加载后有限重试,不能重复创建流水。
- 支付渠道成功不等于业务已经完成;只有钱包事务成功后充值单才变为已完成。
## 五、支付预下单
## 五、支付链接
### 5.1 统一支付单
@@ -147,35 +147,35 @@ tb_payment.amount = recharge_amount
tb_payment.payment_config_id = 创建时使用的配置ID
```
先完成本地事务,再调用第三方预下单。预下单失败时把支付单标记为失败并关闭本次充值单,代理重新创建,不复用来源不明确的旧二维码
先完成本地事务,再生成支付链接。链接生成失败时把支付单标记为失败并关闭本次充值单,代理重新创建,不复用来源不明确的旧链接
### 5.2 微信扫码
微信使用 Native 下单:
微信按当前配置选择 H5/MWEB 下单:
```text
微信支付 v3 TransactionNative
-> 返回 code_url
provider_type=wechat -> 微信 v3 TransactionH5 -> h5_url
provider_type=wechat_v2 -> 微信 v2 MWEB -> mweb_url
```
现有微信 SDK 已包含 `TransactionNative`,需要在项目支付 Adapter 中封装,不在 Handler 直接调用 SDK。
代理充值 Adapter 复用统一 `CreateH5Order` 入口,不在 Handler 判断协议或重复调用 SDK。
若当前生效支付配置为:
- `wechat`:使用微信 v3 Native
- `wechat_v2`补充 v2 Native 统一下单实现
- `fuiou`只有现有富友配置明确支持后台扫码产品时才返回微信可用;不支持时前端隐藏微信扫码入口,不擅自用 JSAPI 代替
- `wechat`:使用微信 v3 H5
- `wechat_v2`使用微信 v2 MWEB并复用 v2 查单与回调验签
- `fuiou`不在本需求扩展富友后台扫码产品,不返回微信可用。
### 5.3 支付宝扫码
支付宝使用当前 SDK 已提供的
支付宝复用 C 端现有手机网站支付链接
```text
alipay.trade.precreate
-> 返回 qr_code
alipay.trade.wap.pay
-> 返回签名 HTTPS URL
```
不复用现有 WAP 支付 URL。创建时校验当前支付配置中的:
该方式不依赖支付宝当面付。创建时校验当前支付配置中的:
```text
ali_app_id
@@ -184,11 +184,11 @@ ali_public_key
ali_notify_url
```
配置不完整时支付宝方式显示为不可用,不能创建只有本地记录而没有有效二维码的充值单。
配置不完整时支付宝方式显示为不可用,不能创建只有本地记录而没有有效支付链接的充值单。
### 5.4 二维码响应
后端统一返回二维码内容,不返回二维码图片:
后端统一返回支付 URL,不返回二维码图片:
```json
{
@@ -197,7 +197,7 @@ ali_notify_url
"payment_no": "ARCH20260715143000000001",
"payment_method": "wechat",
"amount": 10000,
"qr_content": "weixin://wxpay/bizpayurl?...",
"qr_content": "https://pay.example.com/...",
"status": 1,
"status_name": "待支付",
"payment_status": 0,
@@ -207,7 +207,7 @@ ali_notify_url
}
```
微信返回 `code_url`、支付宝返回 `qr_code`Application 统一映射为 `qr_content`
微信返回 `h5_url`、支付宝返回签名 WAP URLApplication 统一映射为 `qr_content`,前端自行渲染二维码
本地无法准确知道第三方订单的真实失效时间,因此接口不返回 `expires_at`,前端不展示本地推算的精确倒计时。第三方支付成功或关闭以回调和后端受控查单为准。
@@ -404,14 +404,14 @@ GET /api/admin/agent-recharges/{id}/payment-status
```text
代理创建充值单
支付预下单成功/失败
支付链接生成成功/失败
微信/支付宝支付回调成功/失败
钱包入账成功/失败
重复回调被幂等忽略
第三方查单确认支付关闭或失效
```
支付渠道交互`tb_integration_log`钱包余额变化写关键 `Audit Event`,并关联充值单、支付单、代理钱包和钱包流水。
微信 H5/MWEB 下单与支付渠道查单`tb_integration_log`;支付宝 WAP URL 本地签名不伪造外部调用日志。钱包余额变化写关键 `Audit Event`,并关联充值单、支付单、代理钱包和钱包流水。
在线充值不产生审批通知。目标代理主钱包实际入账后必须生成“充值到账”站内通知;在线实际提交账号与目标代理主账号不同时,两者分别通知并按充值单与接收人防重。平台线下代充值的真实提交人只接收 UR#37 的审批结果通知,除非其本身也是到账通知接收人。
@@ -423,8 +423,8 @@ GET /api/admin/agent-recharges/{id}/payment-status
- `CreateAgentRechargeRequest.payment_method` 增加 `alipay`,金额校验改为 `min=10000`
- 创建代理在线充值时同时创建 `tb_payment` 记录。
- 新增 `PaymentOrderTypeAgentRecharge`
- 微信支付 Adapter 增加 Native 预下单
- 支付宝 Adapter 增加 `TradePreCreate`
- 微信支付 Adapter 复用 C 端 H5 下单并返回 `h5_url`
- 支付宝 Adapter 复用 C 端 `BuildWapPayURL`
- 支付宝回调增加代理充值分发。
- 微信/富友代理充值回调统一改为按支付单分发,不只依赖 `ARCH` 前缀。
-`agent_recharge.Service.HandlePaymentCallback` 迁入 `ConfirmAgentRechargePayment` 用例。
@@ -444,8 +444,8 @@ GET /api/admin/agent-recharges/{id}/payment-status
1. 验证 99.99 元被后端拒绝100 元可以创建充值单。
2. 验证代理只能为自己的店铺创建微信或支付宝充值。
3. 验证微信 Native 返回有效 `code_url`,前端能够扫码支付。
4. 验证支付宝 PreCreate 返回有效 `qr_code`,前端能够扫码支付。
3. 分别验证微信 v3 H5 与 v2 MWEB 返回有效 HTTPS URL前端能够渲染二维码并通过外部浏览器扫码支付。
4. 验证支付宝 WAP 返回有效签名 HTTPS URL前端能够渲染二维码并扫码支付且商户无需开通当面付。
5. 验证支付回调通过支付单类型分发到代理充值用例。
6. 验证微信、支付宝回调金额不一致时不会增加钱包余额。
7. 验证支付成功后不创建企微审批实例,先固化支付事实,再由可靠 Worker 完成钱包入账。