# 代理资金与佣金当前行为

## 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；业务义务以上述 Requirements 为准。

### 代理预充值

`GET /api/admin/agent-recharges`（查询代理充值订单列表）；`POST /api/admin/agent-recharges`（创建代理充值订单）；`GET /api/admin/agent-recharges/{id}`（查询代理充值订单详情）；`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`（获取当前生效的提现配置）。