265 lines
7.3 KiB
Markdown
265 lines
7.3 KiB
Markdown
# 需求17：信用额度
|
||
|
||
> DDD 结构：`internal/domain/wallet/`
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
### 两类主体
|
||
|
||
| 主体 | 信用额度来源 | 修改条件 |
|
||
|------|------------|---------|
|
||
| 代理（店铺） | 创建店铺时设置 `credit_limit` | 修改前必须先清零欠款（`balance >= 0`）|
|
||
| 平台员工 | 基于**角色**，不是账号 | 角色权限表里配置 |
|
||
|
||
### 可用余额公式
|
||
|
||
```
|
||
可用额度 = balance + credit_limit - frozen_balance
|
||
```
|
||
|
||
- `balance` 可以为负（表示欠款）
|
||
- `balance < 0` 时表示已在使用信用额度
|
||
- `balance < -credit_limit` 表示超额使用（理论上不可达，系统保护）
|
||
|
||
### BPO-009 "是否可授权额度"开关
|
||
|
||
- 代理创建时，新增 `enable_credit` 开关
|
||
- 开关关闭 = `credit_limit` 强制为 0，不允许使用信用额度
|
||
- 平台员工账号通过角色自动拥有额度，无需开关
|
||
|
||
### BPO-012 负余额显示
|
||
|
||
- 代理前台（AgentWallet）：`balance` 正常展示（可为负）
|
||
- 前端不做"不能为负"的前端校验，由后端控制
|
||
|
||
---
|
||
|
||
## 数据库变更
|
||
|
||
### 1. Shop 表加信用额度字段
|
||
|
||
```sql
|
||
ALTER TABLE tb_shop
|
||
ADD COLUMN enable_credit BOOLEAN NOT NULL DEFAULT FALSE
|
||
COMMENT '是否可使用信用额度',
|
||
ADD COLUMN credit_limit BIGINT NOT NULL DEFAULT 0
|
||
COMMENT '授信额度上限（分）';
|
||
```
|
||
|
||
### 2. AgentWallet 表加信用额度字段
|
||
|
||
```sql
|
||
ALTER TABLE tb_agent_wallet
|
||
ADD COLUMN credit_limit BIGINT NOT NULL DEFAULT 0
|
||
COMMENT '信用额度（分），与 shop.credit_limit 同步，余额可到 -credit_limit';
|
||
```
|
||
|
||
> 钱包上冗余一份，是为了避免每次扣款都要 join shop 表。通过 Shop 修改额度时同步更新钱包。
|
||
|
||
### 3. 角色信用额度配置（平台员工）
|
||
|
||
```sql
|
||
ALTER TABLE tb_role
|
||
ADD COLUMN credit_limit BIGINT NOT NULL DEFAULT 0
|
||
COMMENT '该角色的信用额度（分），仅对平台员工角色有效';
|
||
```
|
||
|
||
---
|
||
|
||
## Model 变更
|
||
|
||
```go
|
||
// internal/model/shop.go
|
||
type Shop struct {
|
||
// ...原有字段...
|
||
EnableCredit bool `gorm:"column:enable_credit;not null;default:false;comment:是否可使用信用额度" json:"enable_credit"`
|
||
CreditLimit int64 `gorm:"column:credit_limit;type:bigint;not null;default:0;comment:授信额度上限（分）" json:"credit_limit"`
|
||
}
|
||
|
||
// internal/model/agent_wallet.go
|
||
type AgentWallet struct {
|
||
// ...原有字段（Balance, FrozenBalance 已存在）...
|
||
CreditLimit int64 `gorm:"column:credit_limit;type:bigint;not null;default:0;comment:信用额度（分）" json:"credit_limit"`
|
||
}
|
||
|
||
// GetAvailableBalance 更新：可用余额 = 余额 - 冻结 + 信用额度
|
||
func (w *AgentWallet) GetAvailableBalance() int64 {
|
||
return w.Balance - w.FrozenBalance + w.CreditLimit
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 领域层（DDD）
|
||
|
||
```go
|
||
// internal/domain/wallet/wallet.go
|
||
|
||
// AgentWallet 钱包聚合根（扩展现有模型）
|
||
type AgentWalletAggregate struct {
|
||
model.AgentWallet
|
||
domainEvents []DomainEvent `gorm:"-"`
|
||
}
|
||
|
||
// Debit 扣款（含信用额度）
|
||
func (w *AgentWalletAggregate) Debit(amountCents int64, refType string, refID uint) error {
|
||
available := w.Balance - w.FrozenBalance + w.CreditLimit
|
||
if available < amountCents {
|
||
return ErrInsufficientBalance
|
||
}
|
||
before := w.Balance
|
||
w.Balance -= amountCents
|
||
w.recordEvent(WalletDebitedEvent{
|
||
WalletID: w.ID,
|
||
ShopID: w.ShopID,
|
||
Amount: amountCents,
|
||
BalanceBefore: before,
|
||
BalanceAfter: w.Balance,
|
||
RefType: refType,
|
||
RefID: refID,
|
||
})
|
||
return nil
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 应用层
|
||
|
||
```go
|
||
// internal/application/wallet/grant_credit.go
|
||
|
||
// GrantCreditCommand 授信命令
|
||
type GrantCreditCommand struct {
|
||
ShopID uint
|
||
CreditLimit int64 // 分
|
||
OperatorID uint
|
||
}
|
||
|
||
// GrantCreditUseCase 设置代理信用额度
|
||
type GrantCreditUseCase struct {
|
||
shopStore ShopStore
|
||
walletStore WalletStore
|
||
txManager TxManager
|
||
}
|
||
|
||
func (uc *GrantCreditUseCase) Execute(ctx context.Context, cmd GrantCreditCommand) error {
|
||
return uc.txManager.RunInTx(ctx, func(tx *gorm.DB) error {
|
||
shop, err := uc.shopStore.GetByID(ctx, cmd.ShopID)
|
||
if err != nil { return err }
|
||
|
||
// 修改信用额度前，必须当前余额 >= 0（无欠款）
|
||
wallet, err := uc.walletStore.GetMainWallet(ctx, cmd.ShopID)
|
||
if err != nil { return err }
|
||
if wallet.Balance < 0 {
|
||
return errors.New(errors.CodeForbidden, "存在欠款，请先清零后再修改信用额度")
|
||
}
|
||
|
||
// 同步更新 shop 和 wallet
|
||
if err := uc.shopStore.UpdateCreditLimit(ctx, tx, cmd.ShopID, cmd.CreditLimit); err != nil {
|
||
return err
|
||
}
|
||
return uc.walletStore.UpdateCreditLimit(ctx, tx, wallet.ID, cmd.CreditLimit)
|
||
})
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API 设计
|
||
|
||
### 1. 创建店铺（新增字段）
|
||
|
||
```
|
||
POST /admin/shops
|
||
```
|
||
|
||
新增参数：
|
||
```go
|
||
EnableCredit bool `json:"enable_credit" description:"是否开启信用额度"`
|
||
CreditLimit int64 `json:"credit_limit" description:"授信额度（分），enable_credit=true 时有效"`
|
||
```
|
||
|
||
### 2. 修改信用额度
|
||
|
||
```
|
||
PUT /admin/shops/{id}/credit-limit
|
||
```
|
||
|
||
```go
|
||
type UpdateCreditLimitRequest struct {
|
||
CreditLimit int64 `json:"credit_limit" validate:"min=0" description:"新授信额度（分），修改前需余额>=0"`
|
||
}
|
||
```
|
||
|
||
错误场景：余额为负时，返回 `CodeForbidden`，msg="存在欠款（-XX元），请先清零后再修改信用额度"
|
||
|
||
### 3. 角色信用额度配置（平台员工）
|
||
|
||
```
|
||
PUT /admin/roles/{id}/credit-limit
|
||
```
|
||
|
||
```go
|
||
type UpdateRoleCreditLimitRequest struct {
|
||
CreditLimit int64 `json:"credit_limit" validate:"min=0" description:"该角色的信用额度（分）"`
|
||
}
|
||
```
|
||
|
||
### 4. 查询钱包（余额展示更新）
|
||
|
||
现有 `GET /admin/agent-wallets/{shopID}` 响应新增字段：
|
||
|
||
```go
|
||
type AgentWalletResponse struct {
|
||
// ...原有字段...
|
||
CreditLimit int64 `json:"credit_limit" description:"信用额度（分）"`
|
||
AvailableBalance int64 `json:"available_balance" description:"可用余额 = balance - frozen + credit_limit（分），可为负"`
|
||
IsInDebt bool `json:"is_in_debt" description:"是否有欠款（balance < 0）"`
|
||
DebtAmount int64 `json:"debt_amount" description:"欠款金额（分），balance<0时有值"`
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端对接
|
||
|
||
### 页面：创建/编辑代理
|
||
|
||
新增"信用额度"区块：
|
||
```
|
||
信用额度：
|
||
[☑ 开启信用额度]
|
||
授信上限：[____] 元 （enable_credit=true 时展示）
|
||
```
|
||
|
||
提交时：`enable_credit: true, credit_limit: 100000`（单位：分，前端转换）
|
||
|
||
### 页面：代理详情 > 钱包信息
|
||
|
||
```
|
||
钱包余额：-¥200.00 （红色显示）
|
||
信用额度：¥1,000.00
|
||
可用余额：¥800.00
|
||
```
|
||
|
||
当 `is_in_debt=true` 时，余额展示红色，并加"欠款"标签。
|
||
|
||
### 页面：修改信用额度
|
||
|
||
入口：代理详情 > 钱包 > "修改信用额度"按钮
|
||
弹框：输入新额度 → `PUT /admin/shops/{id}/credit-limit`
|
||
|
||
如果当前有欠款（`is_in_debt=true`），禁用该按钮，展示"存在欠款，无法修改信用额度"。
|
||
|
||
### 页面：余额显示（全局）
|
||
|
||
代理管理列表的余额列：支持显示负数，负数红色标注。
|
||
|
||
### 平台员工余额（角色信用）
|
||
|
||
平台员工操作（如批量订购代理余额扣款）时，可用余额 = 当前余额 + 角色信用额度。
|
||
在批量订购确认页展示可用额度。
|