8.5 KiB
代理资金与佣金当前行为
Purpose
描述代理充值、钱包、佣金、提现及其金额边界的当前可观察行为。
Requirements
Requirement: 代理钱包与提现状态门禁
系统 SHALL 仅允许正常钱包执行资金操作；冻结或关闭钱包拒绝扣款、冻结、释放或提现，提现申请按待审核、已通过、已拒绝、已到账状态推进，重复终态决定不得再次扣减或入账。
Scenario: 非正常钱包资金操作
- GIVEN 代理钱包已冻结或关闭
- WHEN 请求扣款、冻结、释放或提现
- THEN 系统返回状态错误且余额与流水不变
Requirement: 佣金异常状态可见
系统 SHALL 将佣金记录保持为已冻结、解冻中、已发放、已失效或待人工修正；链路断裂的记录进入待人工修正而不是静默计入可提现余额。
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 在退款审批生效时持久化佣金回扣请求；回扣请求的投递或处理异常不得静默遗留，且退款单在全部应回扣佣金失效并完成对应钱包流水前不得标记为已回扣。
Scenario: 已退款订单佣金回扣失败后恢复
- WHEN 已退款订单的佣金回扣首次处理失败或进程中断
- THEN 退款单保持佣金未回扣状态并保留可重试事实，后续成功处理后佣金记录失效、佣金钱包按既有规则扣减且退款单标记为已回扣
Requirement: 退款后处理可补偿
系统 SHALL 对已退款但佣金未回扣或资产未完成后处理的退款单提供幂等补偿；重复补偿不得重复扣减佣金钱包、重复写回扣流水或重复处理资产。
Scenario: 遗留退款单补偿
- WHEN 补偿流程发现已退款且
commission_deducted=false的退款单 - 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；业务义务以上述 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/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-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（获取当前生效的提现配置）。