feat: 添加用户余额充值/退款功能 (#17)

## 功能特性

### 前端
- 在用户列表操作列添加充值和退款按钮
- 实现充值/退款对话框，支持输入金额和备注
- 从编辑用户表单中移除余额字段，防止直接修改
- 添加余额不足验证，实时显示操作后余额
- 优化备注提示词，提供多种场景示例

### 后端
- 为 redeem_codes 表添加 notes 字段（迁移文件）
- 在 UpdateUserBalance 接口添加 notes 参数支持
- 添加余额验证：金额必须大于0，操作后余额不能为负
- UpdateUser 接口移除 balance 字段处理，防止误操作
- 完整的审计日志和缓存管理

## 安全保护

- 前端：余额不足时禁用提交按钮，实时提示
- 后端：双重验证（输入金额 > 0 + 结果余额 >= 0）
- 权限：仅管理员可访问（AdminAuth 中间件）
- 审计：所有操作记录到 redeem_codes 表

## 修改文件

后端：
- backend/migrations/004_add_redeem_code_notes.sql
- backend/internal/model/redeem_code.go
- backend/internal/service/admin_service.go
- backend/internal/handler/admin/user_handler.go

前端：
- frontend/src/views/admin/UsersView.vue
- frontend/src/api/admin/users.ts
- frontend/src/i18n/locales/zh.ts
- frontend/src/i18n/locales/en.ts

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

backend/internal/handler/admin/user_handler.go

@@ -49,8 +49,9 @@ type UpdateUserRequest struct {
 
 // UpdateBalanceRequest represents balance update request
 type UpdateBalanceRequest struct {
-	Balance   float64 `json:"balance" binding:"required"`
+	Balance   float64 `json:"balance" binding:"required,gt=0"`
 	Operation string  `json:"operation" binding:"required,oneof=set add subtract"`
+	Notes     string  `json:"notes"`
 }
 
 // List handles listing all users with pagination
@@ -183,7 +184,7 @@ func (h *UserHandler) UpdateBalance(c *gin.Context) {
 		return
 	}
 
-	user, err := h.adminService.UpdateUserBalance(c.Request.Context(), userID, req.Balance, req.Operation)
+	user, err := h.adminService.UpdateUserBalance(c.Request.Context(), userID, req.Balance, req.Operation, req.Notes)
 	if err != nil {
 		response.InternalError(c, "Failed to update balance: "+err.Error())
 		return

backend/internal/model/redeem_code.go

@@ -14,6 +14,7 @@ type RedeemCode struct {
 	Status    string     `gorm:"size:20;default:unused;not null" json:"status"` // unused/used
 	UsedBy    *int64     `gorm:"index" json:"used_by"`
 	UsedAt    *time.Time `json:"used_at"`
+	Notes     string     `gorm:"type:text" json:"notes"`
 	CreatedAt time.Time  `gorm:"not null" json:"created_at"`
 
 	// 订阅类型专用字段

backend/internal/service/admin_service.go

@@ -22,7 +22,7 @@ type AdminService interface {
 	CreateUser(ctx context.Context, input *CreateUserInput) (*model.User, error)
 	UpdateUser(ctx context.Context, id int64, input *UpdateUserInput) (*model.User, error)
 	DeleteUser(ctx context.Context, id int64) error
-	UpdateUserBalance(ctx context.Context, userID int64, balance float64, operation string) (*model.User, error)
+	UpdateUserBalance(ctx context.Context, userID int64, balance float64, operation string, notes string) (*model.User, error)
 	GetUserAPIKeys(ctx context.Context, userID int64, page, pageSize int) ([]model.ApiKey, int64, error)
 	GetUserUsageStats(ctx context.Context, userID int64, period string) (any, error)
 
@@ -271,8 +271,6 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 		return nil, errors.New("cannot disable admin user")
 	}
 
-	// Track balance and concurrency changes for logging
-	oldBalance := user.Balance
 	oldConcurrency := user.Concurrency
 
 	if input.Email != "" {
@@ -284,7 +282,6 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 		}
 	}
 
-	// 更新用户字段
 	if input.Username != nil {
 		user.Username = *input.Username
 	}
@@ -295,22 +292,14 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 		user.Notes = *input.Notes
 	}
 
-	// Role is not allowed to be changed via API to prevent privilege escalation
 	if input.Status != "" {
 		user.Status = input.Status
 	}
 
-	// 只在指针非 nil 时更新 Balance（支持设置为 0）
-	if input.Balance != nil {
-		user.Balance = *input.Balance
-	}
-
-	// 只在指针非 nil 时更新 Concurrency（支持设置为任意值）
 	if input.Concurrency != nil {
 		user.Concurrency = *input.Concurrency
 	}
 
-	// 只在指针非 nil 时更新 AllowedGroups
 	if input.AllowedGroups != nil {
 		user.AllowedGroups = *input.AllowedGroups
 	}
@@ -319,41 +308,6 @@ func (s *adminServiceImpl) UpdateUser(ctx context.Context, id int64, input *Upda
 		return nil, err
 	}
 
-	// 余额变化时失效缓存
-	if input.Balance != nil && *input.Balance != oldBalance {
-		if s.billingCacheService != nil {
-			go func() {
-				cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
-				defer cancel()
-				if err := s.billingCacheService.InvalidateUserBalance(cacheCtx, id); err != nil {
-					log.Printf("invalidate user balance cache failed: user_id=%d err=%v", id, err)
-				}
-			}()
-		}
-	}
-
-	// Create adjustment records for balance/concurrency changes
-	balanceDiff := user.Balance - oldBalance
-	if balanceDiff != 0 {
-		code, err := model.GenerateRedeemCode()
-		if err != nil {
-			log.Printf("failed to generate adjustment redeem code: %v", err)
-			return user, nil
-		}
-		adjustmentRecord := &model.RedeemCode{
-			Code:   code,
-			Type:   model.AdjustmentTypeAdminBalance,
-			Value:  balanceDiff,
-			Status: model.StatusUsed,
-			UsedBy: &user.ID,
-		}
-		now := time.Now()
-		adjustmentRecord.UsedAt = &now
-		if err := s.redeemCodeRepo.Create(ctx, adjustmentRecord); err != nil {
-			log.Printf("failed to create balance adjustment redeem code: %v", err)
-		}
-	}
-
 	concurrencyDiff := user.Concurrency - oldConcurrency
 	if concurrencyDiff != 0 {
 		code, err := model.GenerateRedeemCode()
@@ -390,12 +344,14 @@ func (s *adminServiceImpl) DeleteUser(ctx context.Context, id int64) error {
 	return s.userRepo.Delete(ctx, id)
 }
 
-func (s *adminServiceImpl) UpdateUserBalance(ctx context.Context, userID int64, balance float64, operation string) (*model.User, error) {
+func (s *adminServiceImpl) UpdateUserBalance(ctx context.Context, userID int64, balance float64, operation string, notes string) (*model.User, error) {
 	user, err := s.userRepo.GetByID(ctx, userID)
 	if err != nil {
 		return nil, err
 	}
 
+	oldBalance := user.Balance
+
 	switch operation {
 	case "set":
 		user.Balance = balance
@@ -405,11 +361,14 @@ func (s *adminServiceImpl) UpdateUserBalance(ctx context.Context, userID int64,
 		user.Balance -= balance
 	}
 
+	if user.Balance < 0 {
+		return nil, fmt.Errorf("balance cannot be negative, current balance: %.2f, requested operation would result in: %.2f", oldBalance, user.Balance)
+	}
+
 	if err := s.userRepo.Update(ctx, user); err != nil {
 		return nil, err
 	}
 
-	// 失效余额缓存
 	if s.billingCacheService != nil {
 		go func() {
 			cacheCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
@@ -420,6 +379,30 @@ func (s *adminServiceImpl) UpdateUserBalance(ctx context.Context, userID int64,
 		}()
 	}
 
+	balanceDiff := user.Balance - oldBalance
+	if balanceDiff != 0 {
+		code, err := model.GenerateRedeemCode()
+		if err != nil {
+			log.Printf("failed to generate adjustment redeem code: %v", err)
+			return user, nil
+		}
+
+		adjustmentRecord := &model.RedeemCode{
+			Code:   code,
+			Type:   model.AdjustmentTypeAdminBalance,
+			Value:  balanceDiff,
+			Status: model.StatusUsed,
+			UsedBy: &user.ID,
+			Notes:  notes,
+		}
+		now := time.Now()
+		adjustmentRecord.UsedAt = &now
+
+		if err := s.redeemCodeRepo.Create(ctx, adjustmentRecord); err != nil {
+			log.Printf("failed to create balance adjustment redeem code: %v", err)
+		}
+	}
+
 	return user, nil
 }
 

backend/migrations/004_add_redeem_code_notes.sql

@@ -0,0 +1,6 @@
+-- 为 redeem_codes 表添加备注字段
+
+ALTER TABLE redeem_codes
+ADD COLUMN IF NOT EXISTS notes TEXT DEFAULT NULL;
+
+COMMENT ON COLUMN redeem_codes.notes IS '备注说明（管理员调整时的原因说明）';