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

## 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；业务义务以上述 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`（获取当前生效的提现配置）。