Files
one-pipe-system/openspec/changes/add-payment-merchant-pool-management/proposal.md
2026-09-10 16:50:06 +08:00

3.4 KiB
Raw Blame History

Change: 新增支付商户与商户池管理

Why

docs/产品迭代8月份/支付商户API简版.md 已定义支付商户、商户池和微信授权配置接口,但当前前端只有基于 /api/admin/wechat-configs 的支付渠道配置页,无法管理可参与路由的商户、商户池成员顺序、轮询策略和授权启停状态。

同时,后台页面可能读取到 credentials,客户支付失败时也容易暴露内部商户切换逻辑。本提案需要把平台专属访问、凭证最小暴露、商户池配置和客户侧失败反馈固化为可验收的 OpenSpec 契约。

What Changes

  • 新增 payment-merchant-pool-management capability覆盖
    • 支付商户查询、创建、详情、按需更新和删除。
    • 商户池查询、创建、详情、更新、启用和停用。
    • 微信授权配置读取、保存及启停状态。
    • 商户池成员排序、轮询策略、统计周期和金额/笔数/时间阈值配置。
  • 新增 payment-checkout-feedback capability覆盖
    • “暂无可用商户”唯一明确提示。
    • 支付失败不暴露商户切换逻辑,不自动切换商户重试。
    • 用户重新发起一笔支付时使用新的支付请求。
  • 新增后台“商户池管理”入口,仅超级管理员和平台用户(user_type12)可见、可访问。
  • 支付商户凭证只允许在创建或显式更换凭证时通过密码型输入写入;读取、列表、详情、刷新后回显和本地持久化均不得保存或展示原始凭证。
  • 微信授权配置中的 AppSecret、Token、AES Key 等敏感字段遵循同样的只写和缓存隔离规则。
  • 该提案只定义契约和实施任务,不执行代码实现;提案获批后再进入实现阶段。

Impact

  • Affected specs:
    • payment-merchant-pool-management
    • payment-checkout-feedback
  • Affected code:
    • src/types/api/paymentMerchantPools.ts(新增)
    • src/api/modules/paymentMerchantPools.ts(新增)
    • src/api/modules/index.ts
    • src/types/api/index.ts
    • src/router/routesAlias.ts
    • src/router/routes/asyncRoutes.ts
    • src/router/guards/permission.ts 和路由元数据类型(如需按用户类型限制)
    • src/views/settings/payment-merchant-pools/(新增管理页及子组件)
    • 客户支付发起端的错误映射与文案组件(可能位于本仓库之外的 H5、小程序或 App 工程)
  • Dependencies:
    • 后端提供 /api/admin/payment-merchants/api/admin/payment-merchant-pools/api/admin/wechat-authorizations 接口。
    • 后端为客户支付失败提供稳定的“无可用商户”机器可读错误码,前端不得依赖中文消息判断。
    • 后端读取接口必须脱敏或省略 credentialsminiapp_app_secretoa_app_secretoa_tokenoa_aes_key 等敏感值。
  • Compatibility:
    • 不复用或重命名现有 /api/admin/wechat-configs 渠道配置能力。
    • 不向代理、企业客户或普通后台用户暴露商户池入口。
    • 商户池内部路由行为不改变现有订单、充值或其他支付接口的请求结构。

Non-Goals

  • 不在前端实现商户选择算法或自行决定切换逻辑;实际路由由后端根据商户池策略执行。
  • 不新增支付渠道、支付 SDK、退款或对账能力。
  • 不提供凭证查看、复制、下载或历史明文回显能力。
  • 不在客户支付端展示商户 ID、商户池、轮询策略、阈值或路由世代。