break
18796b16ff
26 KiB
代理资金与佣金当前行为
Purpose
描述代理充值、钱包、佣金、提现及其金额边界的当前可观察行为。
Requirements
Requirement: 代理钱包与提现状态门禁
系统 SHALL 仅允许正常钱包执行资金操作；冻结或关闭钱包拒绝扣款、冻结、释放或提现，提现申请按待审核、已通过、已拒绝、已到账状态推进，重复终态决定不得再次扣减或入账。
Scenario: 非正常钱包资金操作
- GIVEN 代理钱包已冻结或关闭
- WHEN 请求扣款、冻结、释放或提现
- THEN 系统返回状态错误且余额与流水不变
Requirement: 佣金异常状态可见
系统 SHALL 将佣金记录保持为已冻结、解冻中、已发放、已失效、回溯或待人工修正；链路断裂的记录进入待人工修正而不是静默计入可提现余额。回溯记录 MUST 为负数且不可提现，MUST NOT 计入可提现余额或提高可提现额度。
Scenario: 佣金链路断裂
- GIVEN 佣金记录无法关联完成后续发放所需事实
- WHEN 系统处理该记录
- THEN 记录保持待人工修正状态且不增加可提现余额
Scenario: 回溯记录不计入可提现余额
- GIVEN 代理店铺存在已发放佣金及其回溯记录
- WHEN 查询佣金明细并按可提现余额判定提现资格
- THEN 回溯记录以「回溯」状态与负数金额可见，且不增加该店铺的可提现余额
Requirement: 代理在线充值本地支付状态
系统 SHALL 将代理在线充值的本地支付投影按 0=待支付、1=已支付、2=已失败、3=已退款返回；订单和资产充值使用各自的状态集。
Scenario: 代理在线充值本地支付状态
- GIVEN 代理在线充值的本地支付记录存在
- WHEN 查询该充值的支付状态
- THEN 返回数值状态及对应中文名称
Requirement: 充值边界
系统 SHALL 接受资产充值 100 至 10000000 分、线下代理充值 1 至 100000000 分、在线代理充值至少 10000 分。
Scenario: 充值边界
- GIVEN 请求金额位于或越过边界
- WHEN 创建对应充值
- THEN 边界内请求进入既有支付流程，越界请求返回参数或业务错误
Requirement: 佣金待计算状态可恢复
系统 SHALL 将已支付订单的佣金待计算状态与可靠投递事实关联；投递异常不得静默遗留为无法继续处理的待计算订单。
Scenario: 佣金投递链路异常
- WHEN 佣金计算任务提交或消费链路发生可恢复异常
- THEN 订单维持待计算且投递状态、重试次数和失败摘要可查询，恢复投递后按既有规则得出有佣金、无佣金或待人工修正结果
Requirement: 退款佣金回扣可靠完成
系统 SHALL 在退款申请已通过时持久化佣金回溯请求；回溯请求的投递或处理异常不得静默遗留，且退款单在全部应有回溯明细生成并完成对应钱包流水前不得标记为已回溯。原佣金记录 MUST NOT 因回溯改变状态、金额、佣金来源或发放时间。
Scenario: 已退款订单佣金回扣失败后恢复
- WHEN 已退款订单的佣金回溯首次处理失败或进程中断
- THEN 退款单保持回溯未完成状态并保留可重试事实，后续成功处理后原佣金仍为已发放、回溯明细与佣金钱包负数流水均已生成且退款单标记为已完成
Scenario: 订单佣金未终态
- WHEN 退款申请已通过但原订单佣金仍未进入终态
- THEN 系统不写回溯明细、不标记回溯完成，并保留可重试事实等待终态
Scenario: 终态确无佣金
- WHEN 原订单佣金已进入终态且确认无佣金
- THEN 系统标记该退款单无需回溯并写入「无需回溯」审计，且不产生任何钱包变动
Scenario: 审批异常转人工不回溯
- WHEN 退款申请存在审批异常标记（企业微信通过后撤销）
- THEN 系统不生成回溯明细与钱包变动，标记该退款单的回溯后处理已闭合并写入转人工审计
Requirement: 退款后处理可补偿
系统 SHALL 对已通过但回溯未完成或资产未完成后处理的退款单提供幂等补偿；重复补偿不得重复生成回溯明细、重复扣减佣金钱包、重复写负数流水或重复处理资产。
Scenario: 遗留退款单补偿
- WHEN 补偿流程发现已通过且回溯完成事实缺失的退款单
- THEN 系统恢复该退款单的唯一后处理请求，并在全部应有回溯明细生成后更新其完成事实
Scenario: 周期性补偿
- WHEN 补偿扫描按既有周期任务形态执行且存在回溯后处理未闭合的退款单
- THEN 系统按固定周期重复补偿直至完成事实落库或该退款单转人工，且不重复产生任何资金事实
Requirement: 代理商资金概况按店铺 ID 检索
系统 SHALL 允许通过可选的正整数 shop_id 查询参数精确筛选 GET /api/admin/shops/fund-summary 的店铺资金概况；该条件 MUST 与当前账号的店铺数据范围及其他已提供筛选条件取交集，未提供时 MUST 保持既有列表行为。
Scenario: 按可见店铺 ID 精确检索
- WHEN 当前账号请求资金概况列表并提供其数据范围内的
shop_id - THEN 系统仅返回该 ID 且同时满足其他已提供筛选条件的店铺资金概况
Scenario: 店铺 ID 不匹配或超出数据范围
- WHEN 当前账号提供不存在、超出其数据范围或不满足其他已提供筛选条件的
shop_id - THEN 系统返回成功的空分页结果且不披露该店铺是否存在
Scenario: 店铺 ID 参数无效
- WHEN 当前账号提供零、负数或无法解析为正整数的
shop_id - THEN 系统返回参数错误且不执行资金概况查询
Scenario: 未提供店铺 ID
- WHEN 当前账号请求资金概况列表但未提供
shop_id - THEN 系统继续按既有分页、数据范围、店铺名称和主账号用户名条件返回结果
Requirement: 历史待审批线下代理充值可主动接入企业微信审批
系统 SHALL 提供 POST /api/admin/agent-recharges/{id}/trigger-approval，使具有既有代理充值管理访问权限的后台账号可为历史线下代理充值申请主动创建企业微信审批。系统 MUST 仅在线下充值记录处于待审批状态且 approval_instance_id 为空时创建审批；审批发起人 MUST 使用该充值记录的原创建账号。创建成功后，系统 MUST 原子保存唯一审批实例、审批提交请求及充值记录的审批实例关联，并返回更新后的充值申请审批摘要。
Scenario: 主动发起历史线下代理充值审批成功
- GIVEN 线下代理充值申请处于待审批状态、未关联审批实例，且其原创建账号和企业微信线下充值审批场景均可用
- WHEN 有既有代理充值管理访问权限的后台账号请求
POST /api/admin/agent-recharges/{id}/trigger-approval - THEN 系统创建以原创建账号为发起人的唯一企业微信审批并返回审批摘要，后续由既有可靠提交流程提交至企业微信
Scenario: 在线、非待审批或已发起记录被拒绝
- WHEN 请求主动发起的充值记录不是线下充值、不是待审批状态或已关联审批实例
- THEN 系统返回状态冲突且不创建新的审批实例或提交请求
Scenario: 并发主动发起同一充值审批
- WHEN 两个请求同时为同一符合条件的线下代理充值申请主动发起审批
- THEN 系统至多创建一个审批实例和一个审批提交请求，未成功创建关联的请求返回冲突
Scenario: 原创建人或审批渠道不可用
- WHEN 充值申请原创建账号不可用，或企业微信线下充值审批场景不可用
- THEN 系统返回相应错误，充值申请保持未关联审批实例，修复条件后可再次发起
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 系统拒绝访问且不返回允许范围取值
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 系统拒绝修改编码，但允许修改名称、排序、启停与备注
Requirement: 套餐退款佣金回溯
系统 SHALL 在退款申请已通过后生成关联原佣金记录与退款单的负数、不可提现回溯明细，并保留原佣金记录不变。回溯明细 MUST 冻结原订单号、原佣金标识、负数金额、不可提现标识、回溯后佣金钱包实际余额与生成时间。换货不在本期范围。
回溯准入 MUST 由退款申请状态与方式得出：仅退款申请已通过时可生成，原路退款还须渠道明确成功。待审批、原路处理中、渠道明确失败与企业微信通过后撤销 MUST NOT 生成回溯明细；渠道明确失败可修改材料后重提，重提后按最终成功金额生成一次。同一退款业务 MUST 幂等，幂等依据为「一次退款对应一次原佣金」的唯一事实，MUST NOT 依赖退款单上的佣金回扣标记。
原订单佣金未进入终态时系统 MUST 等待终态后再生成，MUST NOT 提前判定为无需回溯；确认无佣金时才标记无需回溯。
部分退款按本次成功退款金额与本次退款冻结实收金额的比例对每条原佣金等比例回溯。金额 MUST 以分整数精确计算，MUST NOT 溢出或引入浮点误差；每条按分向下取整，舍入差自稳定顺序（原佣金标识升序）末条起向前补足，每条不超过该条剩余可回溯余额；累计回溯 MUST NOT 超过各原佣金的可回溯余额。冻结实收金额缺失或非正时系统 MUST 记录可恢复失败且不落库、不改变余额，MUST NOT 以订单标价或申请金额替代。
生成回溯前系统 MUST 先拒绝并释放待审核提现的冻结余额，再生成回溯明细与钱包扣款流水；佣金钱包余额允许为负，MUST NOT 因余额不足而跳过或拒绝回溯。
Scenario: 部分退款舍入
- WHEN 一笔部分退款关联多条原佣金且比例计算产生分级舍入差
- THEN 系统按各条向下取整并自末条起向前补差，回溯总额等于应回溯额且不超过各原佣金可回溯余额
Scenario: 全额回溯
- WHEN 退款金额与冻结实收金额相等
- THEN 系统按各原佣金的剩余可回溯金额回溯，回溯总额等于各原佣金金额之和
Scenario: 冻结实收金额非正
- WHEN 本次退款冻结实收金额缺失或非正
- THEN 系统记录可恢复失败，不写回溯明细、不改变佣金钱包余额，且不以订单标价替代计算
Scenario: 原路渠道失败重提后按最终金额回溯
- GIVEN 一笔原路退款曾在渠道明确失败并可重提
- WHEN 该退款重提后最终渠道明确成功
- THEN 系统仅在该退款申请已通过时按其最终成功金额生成一次回溯明细，失败阶段不产生任何回溯事实
Scenario: 重复退款消费
- WHEN 同一退款完成事件被重复消费
- THEN 系统不重复生成回溯明细、钱包扣款或提现释放事实
Scenario: 回溯后佣金钱包负余额
- GIVEN 店铺佣金钱包余额不足以覆盖本次回溯金额
- WHEN 系统生成回溯明细
- THEN 钱包余额允许为负并记录回溯后实际余额，且不因余额不足而跳过或拒绝回溯
Scenario: 原佣金保持不变
- WHEN 一笔已发放佣金被回溯
- THEN 该原佣金记录的状态、金额、佣金来源与发放时间均不变，可提现余额按回溯金额减少
Requirement: 回溯明细关联查询与导出
系统 SHALL 在佣金明细中分别展示原发放佣金和回溯扣款记录，并允许从任一记录查询其关联的退款单、原佣金或全部回溯明细。回溯记录必须显示负数金额、不可提现标识、来源退款单号、原佣金记录号、生成时间和回溯后佣金钱包实际余额。原佣金与回溯记录 MUST 合并为同一列表的同一分页与同一排序口径，MUST NOT 因来源表不同而丢失或重复任一条事实。
佣金明细及导出 MUST 使用既有佣金数据范围：代理仅可读取自身及其既有可见范围内的事实，平台与超级管理员遵循既有范围；无权记录不得通过关联 ID、汇总或导出泄露存在性。
佣金明细导出 MUST 使用佣金记录粒度，原佣金与回溯记录各占一行，并冻结创建时筛选条件、操作者与可见范围。回溯后余额为对应钱包变动提交后的实际余额，可为负数；金额保持分，展示层转元 MUST NOT 改变负数或余额事实。
Scenario: 代理查询越权回溯记录
- WHEN 代理使用回溯记录 ID、原佣金 ID 或退款单号查询其数据范围外的回溯关系
- THEN 系统按既有数据范围返回不存在或空结果，不泄露关联事实
Scenario: 原佣金与回溯合并分页
- GIVEN 同一店铺同时存在原佣金记录与回溯记录
- WHEN 查询佣金明细列表并翻页
- THEN 两类记录按同一排序口径出现在同一结果集内，任一条不缺失也不重复
Scenario: 回溯记录导出
- WHEN 导出含回溯记录的佣金明细
- THEN 原佣金与回溯记录各占一行，回溯行金额为负数、可提现标识为不可提现、含关联佣金明细与退款单标识，且回溯后余额为负数时原样导出
可达操作索引
本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。
代理预充值
GET /api/admin/agent-recharges（查询代理充值订单列表）；POST /api/admin/agent-recharges（创建代理充值订单）；GET /api/admin/agent-recharges/{id}（查询代理充值订单详情）；POST /api/admin/agent-recharges/{id}/trigger-approval（补发历史线下代理充值审批）；POST /api/admin/agent-recharges/{id}/offline-pay（确认线下充值）；GET /api/admin/agent-recharges/{id}/payment-status（查询代理充值本地支付与到账状态）；POST /api/admin/agent-recharges/{id}/reject（驳回代理充值订单）；GET /api/admin/agent-recharges/payment-methods（查询代理在线充值可用支付方式）；POST /api/admin/agent-recharges/payment-voucher-ocr（识别付款凭证以预填交易流水号）。
代理自充支付方式配置
GET /api/admin/agent-self-recharge-payment-methods（查询代理自充实际可用支付方式）；PUT /api/admin/agent-self-recharge-payment-methods（修改代理在线自充允许范围）。
代理商资金管理
POST /api/admin/commission-records/{id}/resolve（修正待审佣金记录）；PUT /api/admin/shops/{id}/credit-limit（调整既有店铺实际信用额度）；GET /api/admin/shops/{shop_id}/commission-daily-stats（代理商每日佣金统计）；GET /api/admin/shops/{shop_id}/commission-records（代理商佣金明细）；GET /api/admin/shops/{shop_id}/commission-records/{id}（佣金明细详情）；GET /api/admin/shops/{shop_id}/commission-stats（代理商佣金统计）；GET /api/admin/shops/{shop_id}/main-wallet/transactions（代理商预充值钱包流水）；GET /api/admin/shops/{shop_id}/withdrawal-requests（代理商提现记录）；POST /api/admin/shops/{shop_id}/withdrawal-requests（发起提现申请）；GET /api/admin/shops/fund-summary（代理商资金概况）。
佣金提现审批
GET /api/admin/commission/withdrawal-requests（提现申请列表）；POST /api/admin/commission/withdrawal-requests/{id}/approve（审批通过提现申请）；POST /api/admin/commission/withdrawal-requests/{id}/reject（拒绝提现申请）。
提现配置管理
GET /api/admin/commission/withdrawal-settings（提现配置列表）；POST /api/admin/commission/withdrawal-settings（新增提现配置）；GET /api/admin/commission/withdrawal-settings/current（获取当前生效的提现配置）。