feat: 定合并的稳定版本

soul-api/internal/handler/balance.go

@@ -341,6 +341,53 @@ func AdminUserBalanceGet(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"success": true, "data": gin.H{"balance": balance, "transactions": transactions}})
 }
 
+// AdminUserBalanceAdjust POST /api/admin/users/:id/balance/adjust 管理端-人工调整用户余额
+func AdminUserBalanceAdjust(c *gin.Context) {
+	userID := c.Param("id")
+	if userID == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"success": false, "error": "缺少用户ID"})
+		return
+	}
+	var req struct {
+		Amount float64 `json:"amount" binding:"required"` // 正数增加，负数扣减
+		Remark string  `json:"remark"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"success": false, "error": "参数无效"})
+		return
+	}
+	if req.Amount == 0 {
+		c.JSON(http.StatusBadRequest, gin.H{"success": false, "error": "调整金额不能为 0"})
+		return
+	}
+	db := database.DB()
+	err := db.Transaction(func(tx *gorm.DB) error {
+		var ub model.UserBalance
+		if err := tx.Where("user_id = ?", userID).First(&ub).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				ub = model.UserBalance{UserID: userID, Balance: 0}
+			} else {
+				return err
+			}
+		}
+		newBalance := ub.Balance + req.Amount
+		if newBalance < 0 {
+			return fmt.Errorf("调整后余额不能为负，当前余额 %.2f", ub.Balance)
+		}
+		tx.Exec("INSERT INTO user_balances (user_id, balance, updated_at) VALUES (?, 0, NOW()) ON DUPLICATE KEY UPDATE balance = ?, updated_at = NOW()", userID, newBalance)
+		txID := fmt.Sprintf("bt_adj_%d", time.Now().UnixNano()%100000000000)
+		return tx.Create(&model.BalanceTransaction{
+			ID: txID, UserID: userID, Type: "admin_adjust", Amount: req.Amount,
+			CreatedAt: time.Now(),
+		}).Error
+	})
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{"success": false, "error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"success": true, "message": "余额已调整"})
+}
+
 // ConfirmBalanceRechargeByOrder 支付成功后确认充值（幂等），供 PayNotify 和 activateOrderBenefits 调用
 func ConfirmBalanceRechargeByOrder(db *gorm.DB, order *model.Order) error {
 	if order == nil || order.ProductType != "balance_recharge" {