csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
78911897124573af855fc5b74c4595eaa6347119
junhong_cmp_fiber/openspec/changes/add-agent-self-recharge-payment-methods/specs/agent-funds-commission/spec.md
break 7891189712
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m52s
Details
feat(代理自充): AUG26-017 代理自充收款方式与线下预存款审批字段 
- 受控配置新增代理在线自充允许范围（仅微信/仅支付宝/同时支持），读侧与创建侧取允许范围与可用商户池交集，两侧失败关闭
- 新增允许范围查询与修改端点，读限代理与平台账号、写限超级管理员，复用受控配置写服务留痕
- tb_agent_recharge_record 新增交易流水号、线下收款方式三列快照与其他凭证列（成对迁移 000213）
- 线下申请校验启用的收款方式字典项与必填交易流水号，交易流水号独立于在线渠道交易号、不参与去重
- 扩展 offline_recharge_approval 场景可映射字段白名单与字典引用保护
- 新增付款凭证识别能力与交易流水号预填接口，识别不落库、日志不记录载荷
2026-09-11 15:21:23 +08:00

10 KiB
Raw Blame History

RENAMED Requirements

  • FROM: ### Requirement: 代理在线充值可用支付方式按支付配置判定
  • TO: ### Requirement: 代理在线充值可用支付方式按允许范围与可用商户池判定

MODIFIED Requirements

Requirement: 代理在线充值可用支付方式按允许范围与可用商户池判定

系统 SHALL 以超级管理员维护的允许范围与当前可用商户池支付方式的交集判定代理在线充值的实际可用支付方式。允许范围 MUST 仅取仅微信、仅支付宝、同时支持三者之一；商户池侧 MUST 沿用"该支付方式存在启用商户池且存在启用、凭证完整且当前适配器可用的商户成员"的既有判定。对外支付方式枚举 MUST 固定为 wechat 与 alipay，MUST NOT 返回 fuiou、商户身份、凭证或允许范围本身。代理账号与平台账号均可查询该交集列表，查询 MUST 返回有序列且不因交集为空而报错；交集为空时创建对应方式的在线充值单 MUST 被拒绝且 MUST NOT 新建充值单或支付单，MUST NOT 回退任何历史生效支付配置。代理以 wechat 创建在线充值单时，若命中的商户为富友服务商，系统 MUST 使用富友主扫统一下单并将返回的二维码链接作为支付链接。允许范围变更 MUST 只影响后续新单；已创建未支付充值单 MUST 保留其支付方式与商户路由快照。

Scenario: 富友配置完整时微信可用

  • GIVEN 允许范围包含微信，且微信商户池存在启用、凭证完整的富友服务商商户成员
  • WHEN 代理账号查询可用支付方式
  • THEN 系统返回包含 wechat 的方式列表且不包含 fuiou

Scenario: 微信直连配置完整时微信可用

  • GIVEN 允许范围包含微信，且微信商户池存在启用、凭证完整的微信直连商户成员
  • WHEN 代理账号查询可用支付方式
  • THEN 系统返回包含 wechat 的方式列表

Scenario: 支付宝字段完整时支付宝可用

  • GIVEN 允许范围包含支付宝，且支付宝商户池存在启用、凭证完整的商户成员
  • WHEN 代理账号查询可用支付方式
  • THEN 系统返回包含 alipay 的方式列表

Scenario: 富友配置下微信创建走主扫下单

  • GIVEN 允许范围包含微信，且微信商户池命中的商户为富友服务商且字段完整
  • WHEN 代理账号以 wechat 创建在线充值单
  • THEN 系统调用富友主扫统一下单并返回二维码链接作为支付链接，本地充值单支付方式为 wechat、支付渠道为 fuiou

Scenario: 允许范围收窄后代理只看到被允许的方式

  • GIVEN 微信与支付宝商户池均存在可用成员
  • WHEN 超级管理员将允许范围设置为仅支付宝，代理账号随后查询可用支付方式
  • THEN 系统只返回 alipay

Scenario: 交集为空

  • GIVEN 允许范围只包含微信，而当前微信商户池不存在可用成员
  • WHEN 代理账号查询可用支付方式并尝试以 wechat 创建在线充值单
  • THEN 查询返回空列表且不报错，创建被拒绝且不新建充值单或支付单，不发生任何历史配置回退

Scenario: 配置变更不影响已创建未支付单

  • GIVEN 代理已创建待支付在线充值单并冻结了支付方式与商户路由快照
  • WHEN 超级管理员修改允许范围
  • THEN 该充值单的支付方式与商户快照保持不变，仅后续新单按新范围判定

Scenario: 平台账号可查询且看不到允许范围

  • GIVEN 请求账号为平台账号
  • WHEN 查询可用支付方式
  • THEN 系统返回与代理一致的交集列表，且响应不含允许范围本身、商户身份或凭证

Scenario: 非超级管理员不能读取或修改允许范围

  • GIVEN 请求账号为代理或平台账号
  • WHEN 读取或修改全局允许范围
  • THEN 系统拒绝访问且不返回允许范围取值

ADDED Requirements

Requirement: 代理自充允许方式配置可审计

系统 SHALL 允许超级管理员读取并修改代理在线自充允许方式，取值 MUST 仅限仅微信、仅支付宝、同时支持三种之一；每次成功修改 MUST 记录操作者、修改前后值与修改时间。其他角色 MUST NOT 读取或修改该允许范围。允许范围未被修改过时，系统 MUST 使用代码注册的安全默认值，MUST NOT 因缺少配置而拒绝查询或创建。

Scenario: 超级管理员修改允许范围

  • GIVEN 当前允许范围为同时支持
  • WHEN 超级管理员将其修改为仅微信
  • THEN 系统保存新值并记录操作者、修改前后值与修改时间

Scenario: 非法取值被拒绝

  • WHEN 提交三种允许取值之外的任何值
  • THEN 系统拒绝保存并保留原值

Scenario: 未配置时使用默认值

  • GIVEN 允许范围从未被修改
  • WHEN 查询实际可用支付方式
  • THEN 系统按代码注册的默认允许范围计算交集，不因缺少配置而失败

Requirement: 线下预存款审批收款方式、其他凭证与交易流水号

线下代理预存款/主钱包充值申请 SHALL 由提交人选择一项启用的线下收款方式字典项，并保存其标识、稳定编码与名称快照；字典项改名或停用 MUST NOT 改变历史申请已冻结的快照，已停用项 MUST NOT 可被新申请选取。申请 MUST 保存该笔充值对应的交易流水号，其取值来源为付款凭证识别出的支付单号，且 MUST 以人工确认或更正后的值为准；该系统字段 MUST 独立于在线支付由渠道返回的第三方交易号，MUST NOT 因该值影响任何在线支付事实、钱包入账或幂等判定，且 MUST NOT 作为跨记录去重键或入账前置条件。申请 MUST 支持至少一个支付凭证，并 MUST 支持可选的其他凭证；两类凭证均只保存既有附件对象键引用。系统 MUST 拒绝引用不存在或已停用的收款方式创建申请，MUST NOT 因未填写交易流水号而创建申请。

Scenario: 收款方式快照冻结

  • GIVEN 一笔线下预存款申请引用了某启用的线下收款方式
  • WHEN 超级管理员随后修改该字典项名称或将其停用
  • THEN 历史申请仍展示提交时冻结的编码与名称，新申请不可再选择该已停用项

Scenario: 引用不存在或已停用的收款方式被拒绝

  • WHEN 提交的收款方式字典项不存在或已停用
  • THEN 系统拒绝创建申请且不保存审批实例

Scenario: 支付凭证与其他凭证分别留存

  • WHEN 提交人上传支付凭证与若干其他凭证并创建申请
  • THEN 系统分别保存支付凭证与其他凭证的对象键引用，且企业微信审批详情可取得两类凭证

Scenario: 交易流水号留存并可在审批详情取得

  • WHEN 线下预存款申请创建成功
  • THEN 该充值记录保存人工确认后的交易流水号，并可在企业微信审批详情中取得

Scenario: 缺少交易流水号时拒绝创建

  • WHEN 提交人未填写或填写空白交易流水号
  • THEN 系统拒绝创建申请且不增加钱包余额

Scenario: 交易流水号独立于在线渠道交易号

  • GIVEN 一笔线下预存款申请已保存人工确认的交易流水号
  • WHEN 向同一充值记录写入或修正该交易流水号
  • THEN 在线支付由渠道返回的第三方交易号、支付渠道与支付状态均不受影响，在线充值的入账对账与幂等判定结果不变

Scenario: 相同交易流水号不被系统拒绝

  • WHEN 两笔不同的线下预存款申请保存了完全相同的交易流水号
  • THEN 系统均接受创建，不因该值重复而拒绝或去重

Requirement: 付款凭证识别仅作交易流水号预填

系统 SHALL 提供付款凭证识别，以上传附件的对象键请求识别并只返回支付单号供交易流水号表单预填。识别结果 MUST NOT 写入任何资金事实字段；申请最终保存的交易流水号 MUST 以人工确认或更正后的提交值为准。支付金额、备注、付款人、支付方式与支付时间即使由 Gateway 返回，MUST NOT 被本接口返回或自动预填。识别失败 MUST 返回可理解的失败结果且 MUST NOT 阻断人工填写与提交。系统 MUST NOT 在日志、审计或错误响应中记录凭证内容或识别原始结果。

Scenario: 识别成功仅返回交易流水号预填值

  • GIVEN 提交人已上传一张图片类型的支付凭证并以其对象键请求识别
  • WHEN 识别成功
  • THEN 系统只返回识别出的支付单号供交易流水号预填，且此时未创建任何充值申请

Scenario: 识别结果被人工更正

  • GIVEN 识别返回的支付单号与实际不符
  • WHEN 提交人更正后提交申请
  • THEN 系统保存更正后的值，识别原值不影响任何业务事实

Scenario: 识别失败不阻断人工填写

  • WHEN 凭证非图片、对象不存在或识别服务失败
  • THEN 系统返回明确失败，且提交人仍可人工填写全部字段后提交

Scenario: 日志不记录识别原始结果

  • WHEN 付款凭证识别被调用并返回结果
  • THEN 日志、审计与错误记录只包含业务标识与结果摘要，不包含凭证内容或识别原始结果

Requirement: 线下收款方式字典对代理充值引用的可见性

系统 SHALL 使线下收款方式字典的引用保护覆盖引用它的代理充值申请：已被任一代理充值申请引用的字典项 MUST NOT 被物理删除，MUST 只允许停用，且 MUST 保留历史申请的名称快照。字典项稳定编码在存在引用后 MUST NOT 被修改。

Scenario: 被代理充值引用的字典项不可删除

  • GIVEN 某线下收款方式字典项已被至少一笔代理充值申请引用
  • WHEN 超级管理员请求删除该字典项
  • THEN 系统拒绝删除并返回只能停用的稳定错误

Scenario: 被代理充值引用的字典项编码不可修改

  • GIVEN 某线下收款方式字典项已被至少一笔代理充值申请引用
  • WHEN 超级管理员请求修改该字典项的稳定编码
  • THEN 系统拒绝修改编码，但允许修改名称、排序、启停与备注
Reference in New Issue View Git Blame Copy Permalink