产品需求文档

主题

支付架构重构 ​

功能概述 ​

将自助洗衣业务的支付模块从硬编码的单网点单账户模式，重构为以微信支付服务商模式为核心、支付宝为补充的多模式收款体系。客户端为微信小程序和支付宝小程序两个独立 App，各自根据所在平台获取对应支付配置；后端核心能力包括四部分：支付配置中心、微信服务商分账、微信服务商直收、支付宝直收。每个网点可独立绑定微信渠道配置一个（分账或直收二选一）和支付宝渠道配置一个（可选，最多两个渠道），改变以往改一个网点收款参数就要全量上线发布的困境。

用户故事 ​

作为 平台运营管理员，我希望 在后台可视化创建和管理网点收款配置，绑定后即时生效，以便 新开网点或调整收款参数不再需要研发介入和全量上线。

作为 加盟商，我希望 每笔订单完成后能清楚看到收款金额和分账明细，以便 资金透明，心里有底。

作为 用户，我希望 无论是在微信小程序还是支付宝小程序中都能完成支付，以便 用什么 App 扫码都能付。

作为 财务人员，我希望 系统自动完成分账和日终对账，以便 不再手工汇总多网点多渠道的 Excel 账单。

前置条件 ​

  • 已在微信支付服务商平台完成账号注册、认证，开通服务商支付和分账功能
  • 已有至少一个微信子商户完成进件
  • 已在支付宝开放平台创建应用并通过审核，获取商户 PID 和密钥
  • 网点信息已在系统中注册

子功能 A：支付配置中心 ​

概述 ​

提供网点级别的支付配置管理能力。管理员可创建多种支付模式的收款配置，分别绑定到网点的微信渠道和支付宝渠道。配置变更即时生效，无需重启服务或上线发布。

场景 1：创建支付配置 ​

  1. 运营管理员进入「支付配置」页面，点击「新建配置」
  2. 选择支付模式：微信服务商分账 / 微信服务商直收 / 支付宝直收
  3. 根据所选模式填写对应参数：
    • 微信分账：服务商商户号、API 密钥、子商户号、分账规则（比例/固定金额、接收方列表）
    • 微信直收：服务商商户号、API 密钥、子商户号、回调 URL
    • 支付宝直收：应用 ID、商户 PID、支付宝公钥、商户私钥、异步通知地址
  4. 点击「保存」，系统校验参数格式和有效性
  5. 配置创建成功，状态为「已启用」

场景 2：为网点绑定支付配置 ​

  1. 运营管理员进入「网点管理」→ 选择目标网点 →「支付设置」
  2. 页面分为「微信支付」和「支付宝支付」两个独立区域
  3. 微信支付区：从已启用的微信类配置中选一个（分账或直收）
  4. 支付宝支付区：从已启用的支付宝配置中选一个（也可不选，则仅支持微信）
  5. 确认绑定，系统校验：微信渠道最多一个、支付宝渠道最多一个
  6. 绑定成功后，微信小程序用户可用微信支付，支付宝小程序用户（如网点也绑了支付宝配置）可用支付宝支付

场景 3：更换支付配置 ​

  1. 运营管理员在网点支付设置页，分别更换微信或支付宝配置
  2. 更换一个渠道不影响另一渠道的已有绑定
  3. 系统记录变更日志（渠道、旧配置、新配置、操作人、时间）
  4. 正在进行的支付不受影响，新发起支付即时使用新配置

场景 4：停用/删除支付配置 ​

  1. 停用：若配置仍被网点绑定，提示受影响网点列表，确认后停用并自动解绑
  2. 删除：仅未被任何网点绑定的配置可删除

子功能 B：微信服务商分账模式 ​

概述 ​

基于微信支付服务商模式，用户支付成功后自动按预设规则（按比例或固定金额）将资金分账到平台方、加盟商、设备供应商等多个接收方，替代手工结算。

场景 1：配置分账规则 ​

  1. 在创建「微信服务商分账」配置时填写分账规则
  2. 分账方式：
    • 按比例：如平台 15%、加盟商 85%
    • 按固定金额：如每单平台抽 2 元，其余归加盟商
  3. 添加接收方（最多 10 个），每个接收方设置类型（平台/加盟商/供应商/其他）、商户号和分账比例或金额
  4. 系统校验：按比例模式各接收方比例之和 = 100%；按固定金额模式金额之和 ≤ 单笔最大限额

场景 2：支付 + 自动分账 ​

  1. 用户在微信小程序中发起支付，订单金额 20 元
  2. 系统根据网点微信分账配置发起支付，携带分账标记
  3. 支付成功后，系统自动调用微信分账接口：
    • 平台方：20 × 15% = 3 元
    • 加盟商：20 × 85% = 17 元
  4. 分账完成后更新订单状态，推送通知给加盟商

场景 3：分账失败处理 ​

  1. 微信分账失败（如接收方账户异常）→ 订单标记「分账失败」
  2. 自动进入重试队列：每 30 分钟重试一次，最多 5 次
  3. 5 次均失败后系统发出告警（站内通知 + 企业微信/钉钉）
  4. 财务人员核实后手动处理：修正接收方信息 → 手动重试分账

场景 4：退款与分账回退 ​

  1. 用户发起退款 → 检查订单分账状态
  2. 已分账的订单先调用微信分账回退接口，按原比例从各接收方退回
  3. 回退成功后执行退款，资金从子商户账户原路退回用户

分账状态流转 ​

  • 待分账 → 分账中 → 已分账
  • 分账中 → 分账失败 → 重试 → 分账中（循环最多 5 次）→ 分账失败（最终）
  • 已分账 → 已回退（退款场景）

子功能 C：微信服务商直接收款模式 ​

概述 ​

基于微信支付服务商模式，子商户直接向用户收款，不涉及分账。适用于加盟商独立经营、平台通过其他方式（如固定月费）收取服务费的场景。

场景 1：用户支付 ​

  1. 用户在微信小程序中发起支付
  2. 系统根据网点绑定的微信直收配置，获取服务商参数和子商户号
  3. 调用微信服务商支付 API（sub_mch_id 设为对应子商户）
  4. 用户完成支付，资金直接进入子商户账户
  5. 系统记录支付流水，推送支付成功通知

场景 2：退款 ​

  1. 用户发起退款 → 调用微信服务商退款接口
  2. 退款从子商户账户原路退回
  3. 支持全额和部分退款

子功能 D：支付宝直接收款模式 ​

概述 ​

独立于微信支付体系，支持支付宝当面付和 APP 支付，作为网点的第二种收款渠道。网点绑定支付宝配置后，用户在支付宝小程序中即可使用支付宝支付。

场景 1：用户支付宝支付 ​

  1. 用户在支付宝小程序中扫码发起支付
  2. 系统根据网点绑定的支付宝配置发起支付（当面付 / APP 支付）
  3. 用户完成支付 → 支付宝异步通知到达 → 系统验签后更新订单状态

场景 2：退款 ​

  1. 调用支付宝 alipay.trade.refund 接口
  2. 支持全额和部分退款

场景 3：未绑支付宝的网点 ​

  1. 网点仅绑定微信配置，未绑定支付宝配置
  2. 微信小程序用户正常使用微信支付
  3. 支付宝小程序用户扫码后，前端获取不到支付宝配置，提示「该网点暂不支持支付宝支付」

交互说明 ​

支付配置列表 ​

元素类型说明规则
筛选-支付模式下拉微信分账/微信直收/支付宝/全部默认全部
筛选-状态下拉已启用/已停用默认全部
新建配置主按钮打开创建表单—
配置列表项行名称、模式、状态、绑定网点数点击进入详情

网点支付设置页 ​

区域元素说明
微信支付下拉选择器从已启用的微信类配置中选一个（分账或直收），可切换或解绑
支付宝支付下拉选择器从已启用的支付宝配置中选一个，可留空（仅微信收款）

分账规则配置 ​

元素类型说明规则
分账方式单选按比例 / 按固定金额必选
接收方列表动态表单最多 10 个类型、商户号、比例或金额
接收方类型下拉平台/加盟商/供应商/其他平台至少一个

验收标准 ​

支付配置中心 ​

  • [ ] F-102-AC01：支持创建/编辑/停用/删除三种模式的支付配置，各有独立参数 Schema
  • [ ] F-102-AC02：配置列表支持按模式和状态筛选
  • [ ] F-102-AC03：网点可分别绑定微信和支付宝配置，各渠道最多一个，切换后即时生效
  • [ ] F-102-AC04：停用配置自动解绑关联网点，删除仅限未绑定配置
  • [ ] F-102-AC05：配置变更日志完整可追溯（操作人、时间、渠道、变更内容）

微信服务商分账 ​

  • [ ] F-102-AC06：支持按比例和固定金额两种分账规则，接收方最多 10 个
  • [ ] F-102-AC07：支付成功后 30 秒内自动发起分账
  • [ ] F-102-AC08：分账失败自动重试 5 次，5 次后告警
  • [ ] F-102-AC09：支持分账查询和退款场景的分账回退

微信服务商直收 ​

  • [ ] F-102-AC10：服务商模式下子商户直接收款，资金不经过分账
  • [ ] F-102-AC11：支持全额和部分退款
  • [ ] F-102-AC12：与分账模式可在不同网点独立使用，互不影响

支付宝直收 ​

  • [ ] F-102-AC13：支持支付宝当面付和 APP 支付
  • [ ] F-102-AC14：异步通知正确处理（验签、幂等），支持退款
  • [ ] F-102-AC15：未绑定支付宝的网点，支付宝支付请求返回明确错误提示

整体 ​

  • [ ] F-102-AC16：微信小程序用户使用微信支付，支付宝小程序用户使用支付宝支付，各自独立
  • [ ] F-102-AC17：微信配置更换不影响支付宝绑定，反之亦然

技术备注 ​

  • 配置参数采用 JSON 字段存储，不同模式对应不同 Schema，便于扩展新模式（如云闪付）
  • 配置变更通过 Redis Pub/Sub 或配置中心（Nacos）推送，各服务节点 1 分钟内生效
  • PAYMENT_CONFIG_BINDING 表 site_id + channel 联合唯一索引，防止同渠道重复绑定
  • 绑定操作以 site_id + channel 为 Key 加分布式锁
  • 微信分账/直收 SDK 与支付宝 SDK 独立引入，各渠道适配器模式互不耦合
  • 支付密钥（API Key、私钥等）加密存储，日志脱敏