临时备份一次

docs/7月迭代/需求17-信用额度.md

@@ -0,0 +1,264 @@
+# 需求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`），禁用该按钮，展示"存在欠款，无法修改信用额度"。
+
+### 页面：余额显示（全局）
+
+代理管理列表的余额列：支持显示负数，负数红色标注。
+
+### 平台员工余额（角色信用）
+
+平台员工操作（如批量订购代理余额扣款）时，可用余额 = 当前余额 + 角色信用额度。  
+在批量订购确认页展示可用额度。