fix: improve trader error feedback, stale balance cleanup, and claw402 warnings (#1452)

* fix: improve trader error handling and balance validation

* fix: localize structured trader failure reasons

---------

Co-authored-by: apple <apple@MacbookPro-zbh.local>

api/handler_trader.go

@@ -1,6 +1,7 @@
 package api
 
 import (
+	"errors"
 	"fmt"
 	"net/http"
 	"strings"
@@ -10,6 +11,7 @@ import (
 	"nofx/store"
 
 	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
 )
 
 // AI trader management related structures
@@ -52,22 +54,265 @@ type UpdateTraderRequest struct {
 	SystemPromptTemplate string `json:"system_prompt_template"`
 }
 
+func formatTraderCreationError(reason, nextStep string) string {
+	if nextStep == "" {
+		return fmt.Sprintf("这次未能创建机器人：%s。", reason)
+	}
+	return fmt.Sprintf("这次未能创建机器人：%s。%s。", reason, nextStep)
+}
+
+func traderCreationRequestError(reason string) string {
+	return formatTraderCreationError(reason, "请检查你刚刚填写的内容后，再重新提交")
+}
+
+func exchangeDisplayName(exchange *store.Exchange) string {
+	if exchange == nil {
+		return "所选交易所账户"
+	}
+	if exchange.AccountName != "" {
+		return fmt.Sprintf("%s（%s）", exchange.Name, exchange.AccountName)
+	}
+	if exchange.Name != "" {
+		return exchange.Name
+	}
+	return "所选交易所账户"
+}
+
+func missingExchangeFields(exchange *store.Exchange) []string {
+	if exchange == nil {
+		return nil
+	}
+
+	var missing []string
+	switch exchange.ExchangeType {
+	case "binance", "bybit", "gate", "indodax":
+		if exchange.APIKey == "" {
+			missing = append(missing, "API Key")
+		}
+		if exchange.SecretKey == "" {
+			missing = append(missing, "Secret Key")
+		}
+	case "okx", "bitget", "kucoin":
+		if exchange.APIKey == "" {
+			missing = append(missing, "API Key")
+		}
+		if exchange.SecretKey == "" {
+			missing = append(missing, "Secret Key")
+		}
+		if exchange.Passphrase == "" {
+			missing = append(missing, "Passphrase")
+		}
+	case "hyperliquid":
+		if exchange.APIKey == "" {
+			missing = append(missing, "私钥")
+		}
+		if strings.TrimSpace(exchange.HyperliquidWalletAddr) == "" {
+			missing = append(missing, "钱包地址")
+		}
+	case "aster":
+		if strings.TrimSpace(exchange.AsterUser) == "" {
+			missing = append(missing, "Aster User")
+		}
+		if strings.TrimSpace(exchange.AsterSigner) == "" {
+			missing = append(missing, "Aster Signer")
+		}
+		if exchange.AsterPrivateKey == "" {
+			missing = append(missing, "Aster Private Key")
+		}
+	case "lighter":
+		if strings.TrimSpace(exchange.LighterWalletAddr) == "" {
+			missing = append(missing, "钱包地址")
+		}
+		if exchange.LighterAPIKeyPrivateKey == "" {
+			missing = append(missing, "API Key Private Key")
+		}
+	}
+
+	return missing
+}
+
+func mapStringPairs(kv ...string) map[string]string {
+	if len(kv) == 0 {
+		return nil
+	}
+
+	params := make(map[string]string, len(kv)/2)
+	for i := 0; i+1 < len(kv); i += 2 {
+		params[kv[i]] = kv[i+1]
+	}
+	return params
+}
+
+func validateExchangeForTraderCreation(exchange *store.Exchange) (string, string, map[string]string) {
+	if exchange == nil {
+		return formatTraderCreationError("还没有找到你选择的交易所账户", "请前往「设置 > 交易所配置」先添加一个可用账户，再回来创建机器人"),
+			"trader.create.exchange_not_found", nil
+	}
+	if !exchange.Enabled {
+		return formatTraderCreationError(
+			fmt.Sprintf("交易所账户「%s」目前处于未启用状态", exchangeDisplayName(exchange)),
+			"请前往「设置 > 交易所配置」启用该账户后，再重新创建机器人",
+		), "trader.create.exchange_disabled", mapStringPairs("exchange_name", exchangeDisplayName(exchange))
+	}
+
+	missing := missingExchangeFields(exchange)
+	if len(missing) > 0 {
+		return formatTraderCreationError(
+			fmt.Sprintf("交易所账户「%s」的配置还不完整，缺少 %s", exchangeDisplayName(exchange), strings.Join(missing, "、")),
+			"请前往「设置 > 交易所配置」补全该账户的必填信息后，再重新创建机器人",
+		), "trader.create.exchange_missing_fields", mapStringPairs(
+			"exchange_name", exchangeDisplayName(exchange),
+			"missing_fields", strings.Join(missing, ", "),
+		)
+	}
+
+	switch exchange.ExchangeType {
+	case "binance", "bybit", "okx", "bitget", "gate", "kucoin", "hyperliquid", "aster", "lighter", "indodax":
+		return "", "", nil
+	default:
+		return formatTraderCreationError(
+			fmt.Sprintf("交易所账户「%s」使用了当前版本暂不支持的类型 %s", exchangeDisplayName(exchange), exchange.ExchangeType),
+			"请改用当前版本支持的交易所账户后，再重新创建机器人",
+		), "trader.create.exchange_unsupported", mapStringPairs(
+			"exchange_name", exchangeDisplayName(exchange),
+			"exchange_type", exchange.ExchangeType,
+		)
+	}
+}
+
+func classifyTraderSetupReason(reason string) (string, string) {
+	trimmed := strings.TrimSpace(reason)
+	if trimmed == "" {
+		return "", ""
+	}
+
+	lower := strings.ToLower(trimmed)
+
+	switch {
+	case strings.Contains(lower, "failed to parse strategy config"),
+		strings.Contains(lower, "failed to parse strategy configuration"):
+		return "trader.reason.strategy_config_invalid", "当前策略配置内容已损坏，系统暂时无法解析"
+	case strings.Contains(lower, "has no strategy configured"):
+		return "trader.reason.strategy_missing", "当前机器人缺少有效的交易策略配置"
+	case strings.Contains(lower, "failed to parse private key"),
+		(strings.Contains(lower, "invalid hex character") && strings.Contains(lower, "private key")):
+		return "trader.reason.private_key_invalid", "私钥格式不正确，系统无法识别"
+	case strings.Contains(lower, "failed to initialize hyperliquid trader"):
+		return "trader.reason.hyperliquid_init_failed", "Hyperliquid 账户初始化失败，请确认私钥、主钱包地址和 Agent Wallet 配置是否正确"
+	case strings.Contains(lower, "failed to initialize aster trader"):
+		return "trader.reason.aster_init_failed", "Aster 账户初始化失败，请确认 Aster User、Signer 和私钥是否正确"
+	case strings.Contains(lower, "failed to get meta information"):
+		return "trader.reason.exchange_meta_unavailable", "系统暂时无法从交易所读取账户元信息"
+	case strings.Contains(lower, "security check failed") && strings.Contains(lower, "agent wallet balance too high"):
+		return "trader.reason.hyperliquid_agent_balance_too_high", "Hyperliquid Agent Wallet 余额过高，不符合当前安全要求"
+	case strings.Contains(lower, "failed to initialize account"):
+		return "trader.reason.exchange_account_init_failed", "交易所账户初始化失败，请确认钱包地址和 API Key 是否匹配"
+	case strings.Contains(lower, "unsupported trading platform"):
+		return "trader.reason.exchange_unsupported", "当前交易所类型暂不支持机器人初始化"
+	case strings.Contains(lower, "initial balance not set and unable to fetch balance from exchange"):
+		return "trader.reason.exchange_balance_unavailable", "系统暂时无法从交易所读取账户余额"
+	case strings.Contains(lower, "timeout"), strings.Contains(lower, "no such host"), strings.Contains(lower, "connection refused"):
+		return "trader.reason.exchange_service_unreachable", "系统暂时无法连接交易所服务"
+	default:
+		return "trader.reason.unknown", trimmed
+	}
+}
+
+func humanizeTraderSetupReason(reason string) string {
+	_, message := classifyTraderSetupReason(reason)
+	return message
+}
+
+func traderSetupReasonParams(err error, fallback string, kv ...string) map[string]string {
+	params := mapStringPairs(kv...)
+	rawReason := SanitizeError(err, fallback)
+	reasonKey, reasonMessage := classifyTraderSetupReason(rawReason)
+	if reasonMessage == "" && fallback != "" {
+		reasonMessage = fallback
+	}
+	if reasonMessage != "" {
+		if params == nil {
+			params = map[string]string{}
+		}
+		params["reason"] = reasonMessage
+	}
+	if reasonKey != "" {
+		if params == nil {
+			params = map[string]string{}
+		}
+		params["reason_key"] = reasonKey
+	}
+	return params
+}
+
+func describeTraderLoadError(traderName string, err error) string {
+	if err == nil {
+		return formatTraderCreationError("机器人配置虽然保存了，但运行实例没有成功初始化", "请检查模型、策略和交易所配置是否完整，然后再试一次")
+	}
+
+	reason := humanizeTraderSetupReason(SanitizeError(err, ""))
+	if reason == "" {
+		return formatTraderCreationError(
+			fmt.Sprintf("机器人「%s」在初始化运行实例时没有成功启动", traderName),
+			"请检查模型、策略和交易所配置是否完整，然后再试一次",
+		)
+	}
+
+	return formatTraderCreationError(
+		fmt.Sprintf("机器人「%s」在初始化运行实例时没有成功启动，原因是：%s", traderName, reason),
+		"请检查模型、策略和交易所配置是否完整，然后再试一次",
+	)
+}
+
+func describeTraderCreationWarning(traderName string, err error) string {
+	if err == nil {
+		return fmt.Sprintf("机器人「%s」已经保存，但当前还没有通过启动前校验。请先检查模型、策略和交易所配置，修正后再点击启动。", traderName)
+	}
+
+	reason := humanizeTraderSetupReason(SanitizeError(err, ""))
+	if reason == "" {
+		return fmt.Sprintf("机器人「%s」已经保存，但当前暂时还不能启动。请先检查模型、策略和交易所配置，修正后再点击启动。", traderName)
+	}
+
+	return fmt.Sprintf("机器人「%s」已经保存，但当前暂时还不能启动，原因是：%s。请先检查模型、策略和交易所配置，修正后再点击启动。", traderName, reason)
+}
+
+func describeTraderStartError(traderName string, err error) string {
+	if err == nil {
+		return fmt.Sprintf("这次未能启动机器人：机器人「%s」暂时还不能启动。请检查模型、策略和交易所配置后，再重新点击启动。", traderName)
+	}
+
+	reason := humanizeTraderSetupReason(SanitizeError(err, ""))
+	if reason == "" {
+		return fmt.Sprintf("这次未能启动机器人：机器人「%s」暂时还不能启动。请检查模型、策略和交易所配置后，再重新点击启动。", traderName)
+	}
+
+	return fmt.Sprintf("这次未能启动机器人：机器人「%s」暂时还不能启动，原因是：%s。请检查模型、策略和交易所配置后，再重新点击启动。", traderName, reason)
+}
+
+func formatTraderStartError(reason, nextStep string) string {
+	if nextStep == "" {
+		return fmt.Sprintf("这次未能启动机器人：%s。", reason)
+	}
+	return fmt.Sprintf("这次未能启动机器人：%s。%s。", reason, nextStep)
+}
+
 // handleCreateTrader Create new AI trader
 func (s *Server) handleCreateTrader(c *gin.Context) {
 	userID := c.GetString("user_id")
 	var req CreateTraderRequest
 	if err := c.ShouldBindJSON(&req); err != nil {
-		SafeBadRequest(c, "Invalid request parameters")
+		SafeBadRequestWithDetails(c, traderCreationRequestError("提交的信息不完整，或者格式不正确"), "trader.create.invalid_request", nil)
 		return
 	}
 
 	// Validate leverage values
 	if req.BTCETHLeverage < 0 || req.BTCETHLeverage > 50 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "BTC/ETH leverage must be between 1-50x"})
+		SafeBadRequestWithDetails(c, traderCreationRequestError("BTC/ETH 杠杆倍数需要在 1 到 50 倍之间"), "trader.create.invalid_btc_eth_leverage", nil)
 		return
 	}
 	if req.AltcoinLeverage < 0 || req.AltcoinLeverage > 20 {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "Altcoin leverage must be between 1-20x"})
+		SafeBadRequestWithDetails(c, traderCreationRequestError("山寨币杠杆倍数需要在 1 到 20 倍之间"), "trader.create.invalid_altcoin_leverage", nil)
 		return
 	}
 
@@ -77,12 +322,61 @@ func (s *Server) handleCreateTrader(c *gin.Context) {
 		for _, symbol := range symbols {
 			symbol = strings.TrimSpace(symbol)
 			if symbol != "" && !strings.HasSuffix(strings.ToUpper(symbol), "USDT") {
-				c.JSON(http.StatusBadRequest, gin.H{"error": fmt.Sprintf("Invalid symbol format: %s, must end with USDT", symbol)})
+				SafeBadRequestWithDetails(c, traderCreationRequestError(
+					fmt.Sprintf("交易对 %s 的格式不正确，目前只支持以 USDT 结尾的合约交易对", symbol),
+				), "trader.create.invalid_symbol", mapStringPairs("symbol", symbol))
 				return
 			}
 		}
 	}
 
+	model, err := s.store.AIModel().Get(userID, req.AIModelID)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			SafeBadRequestWithDetails(c, formatTraderCreationError("还没有找到你选择的 AI 模型", "请前往「设置 > 模型配置」先添加并启用一个可用模型，再回来创建机器人"), "trader.create.model_not_found", nil)
+			return
+		}
+		SafeError(c, http.StatusInternalServerError,
+			formatTraderCreationError("暂时无法读取你的 AI 模型配置", "请稍后重试；如果问题持续，再检查本地服务是否正常"),
+			err,
+		)
+		return
+	}
+	if !model.Enabled {
+		SafeBadRequestWithDetails(c, formatTraderCreationError(
+			fmt.Sprintf("AI 模型「%s」目前还没有启用", model.Name),
+			"请前往「设置 > 模型配置」启用它后，再重新创建机器人",
+		), "trader.create.model_disabled", mapStringPairs("model_name", model.Name))
+		return
+	}
+	if model.APIKey == "" {
+		SafeBadRequestWithDetails(c, formatTraderCreationError(
+			fmt.Sprintf("AI 模型「%s」缺少 API Key 或支付凭证", model.Name),
+			"请前往「设置 > 模型配置」补全模型凭证后，再重新创建机器人",
+		), "trader.create.model_missing_credentials", mapStringPairs("model_name", model.Name))
+		return
+	}
+
+	if req.StrategyID == "" {
+		SafeBadRequestWithDetails(c, formatTraderCreationError("你还没有选择交易策略", "请先选择一个策略，再继续创建机器人"), "trader.create.strategy_required", nil)
+		return
+	}
+
+	if req.StrategyID != "" {
+		_, err = s.store.Strategy().Get(userID, req.StrategyID)
+		if err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				SafeBadRequestWithDetails(c, formatTraderCreationError("你选择的策略不存在，或者已经被删除了", "请重新选择一个可用策略后，再继续创建机器人"), "trader.create.strategy_not_found", nil)
+				return
+			}
+			SafeError(c, http.StatusInternalServerError,
+				formatTraderCreationError("暂时无法读取你选择的策略配置", "请稍后重试；如果问题持续，再检查本地服务是否正常"),
+				err,
+			)
+			return
+		}
+	}
+
 	// Generate trader ID (use short UUID prefix for readability)
 	exchangeIDShort := req.ExchangeID
 	if len(exchangeIDShort) > 8 {
@@ -127,7 +421,11 @@ func (s *Server) handleCreateTrader(c *gin.Context) {
 	actualBalance := req.InitialBalance // Default to use user input
 	exchanges, err := s.store.Exchange().List(userID)
 	if err != nil {
-		logger.Infof("⚠️ Failed to get exchange config, using user input for initial balance: %v", err)
+		SafeError(c, http.StatusInternalServerError,
+			formatTraderCreationError("暂时无法读取你的交易所配置", "请稍后重试；如果问题持续，再检查本地服务是否正常"),
+			err,
+		)
+		return
 	}
 
 	// Find matching exchange configuration
@@ -139,15 +437,22 @@ func (s *Server) handleCreateTrader(c *gin.Context) {
 		}
 	}
 
-	if exchangeCfg == nil {
-		logger.Infof("⚠️ Exchange %s configuration not found, using user input for initial balance", req.ExchangeID)
-	} else if !exchangeCfg.Enabled {
-		logger.Infof("⚠️ Exchange %s not enabled, using user input for initial balance", req.ExchangeID)
-	} else {
+	if exchangeMsg, exchangeErrorKey, exchangeErrorParams := validateExchangeForTraderCreation(exchangeCfg); exchangeMsg != "" {
+		SafeBadRequestWithDetails(c, exchangeMsg, exchangeErrorKey, exchangeErrorParams)
+		return
+	}
+
+	{
 		tempTrader, createErr := buildExchangeProbeTrader(exchangeCfg, userID)
 		if createErr != nil {
-			logger.Infof("⚠️ Failed to create temporary trader, using user input for initial balance: %v", createErr)
-		} else {
+			SafeBadRequestWithDetails(c, formatTraderCreationError(
+				fmt.Sprintf("交易所账户「%s」没有通过初始化校验，原因是：%s", exchangeDisplayName(exchangeCfg), humanizeTraderSetupReason(SanitizeError(createErr, "配置校验未通过"))),
+				"请前往「设置 > 交易所配置」检查这个账户的密钥、地址和账户信息是否填写正确",
+			), "trader.create.exchange_probe_failed", traderSetupReasonParams(createErr, "配置校验未通过",
+				"exchange_name", exchangeDisplayName(exchangeCfg),
+			))
+			return
+		} else if tempTrader != nil {
 			// Query actual balance
 			balanceInfo, balanceErr := tempTrader.GetBalance()
 			if balanceErr != nil {
@@ -193,27 +498,48 @@ func (s *Server) handleCreateTrader(c *gin.Context) {
 	err = s.store.Trader().Create(traderRecord)
 	if err != nil {
 		logger.Infof("❌ Failed to create trader: %v", err)
-		SafeInternalError(c, "Failed to create trader", err)
+		publicMsg := SanitizeError(err, formatTraderCreationError("机器人配置没有保存成功", "请检查名称、模型、策略和交易所配置后，再试一次"))
+		statusCode := http.StatusBadRequest
+		if publicMsg == formatTraderCreationError("机器人配置没有保存成功", "请检查名称、模型、策略和交易所配置后，再试一次") {
+			statusCode = http.StatusInternalServerError
+		}
+		SafeError(c, statusCode, publicMsg, err)
 		return
 	}
 	logger.Infof("🔧 DEBUG: CreateTrader succeeded")
 
 	// Immediately load new trader into TraderManager
 	logger.Infof("🔧 DEBUG: Preparing to call LoadUserTraders")
+	startupWarning := ""
 	err = s.traderManager.LoadUserTradersFromStore(s.store, userID)
 	if err != nil {
 		logger.Infof("⚠️ Failed to load user traders into memory: %v", err)
-		// Don't return error here since trader was successfully created in database
+		startupWarning = describeTraderCreationWarning(req.Name, err)
 	}
 	logger.Infof("🔧 DEBUG: LoadUserTraders completed")
 
+	if startupWarning == "" {
+		if loadErr := s.traderManager.GetLoadError(traderID); loadErr != nil {
+		logger.Infof("⚠️ Trader %s failed to load after creation: %v", traderID, loadErr)
+			startupWarning = describeTraderCreationWarning(req.Name, loadErr)
+		}
+	}
+
+	if startupWarning == "" {
+		if _, getErr := s.traderManager.GetTrader(traderID); getErr != nil {
+		logger.Infof("⚠️ Trader %s not found in memory after creation: %v", traderID, getErr)
+			startupWarning = describeTraderCreationWarning(req.Name, getErr)
+		}
+	}
+
 	logger.Infof("✓ Trader created successfully: %s (model: %s, exchange: %s)", req.Name, req.AIModelID, req.ExchangeID)
 
 	c.JSON(http.StatusCreated, gin.H{
-		"trader_id":   traderID,
-		"trader_name": req.Name,
-		"ai_model":    req.AIModelID,
-		"is_running":  false,
+		"trader_id":        traderID,
+		"trader_name":      req.Name,
+		"ai_model":         req.AIModelID,
+		"is_running":       false,
+		"startup_warning":  startupWarning,
 	})
 }
 
@@ -291,6 +617,17 @@ func (s *Server) handleUpdateTrader(c *gin.Context) {
 		strategyID = existingTrader.StrategyID
 	}
 
+	exchangeChanged := req.ExchangeID != "" && req.ExchangeID != existingTrader.ExchangeID
+	resetInitialBalance := exchangeChanged && req.InitialBalance <= 0
+
+	initialBalance := existingTrader.InitialBalance
+	if req.InitialBalance > 0 {
+		initialBalance = req.InitialBalance
+	}
+	if resetInitialBalance {
+		initialBalance = 0
+	}
+
 	// Update trader configuration
 	traderRecord := &store.Trader{
 		ID:                   traderID,
@@ -299,7 +636,7 @@ func (s *Server) handleUpdateTrader(c *gin.Context) {
 		AIModelID:            req.AIModelID,
 		ExchangeID:           req.ExchangeID,
 		StrategyID:           strategyID, // Associated strategy ID
-		InitialBalance:       req.InitialBalance,
+		InitialBalance:       initialBalance,
 		BTCETHLeverage:       btcEthLeverage,
 		AltcoinLeverage:      altcoinLeverage,
 		TradingSymbols:       req.TradingSymbols,
@@ -331,6 +668,14 @@ func (s *Server) handleUpdateTrader(c *gin.Context) {
 		return
 	}
 
+	if resetInitialBalance {
+		logger.Infof("🔄 Exchange changed for trader %s, resetting stale initial_balance to 0", traderID)
+		if err := s.store.Trader().UpdateInitialBalance(userID, traderID, 0); err != nil {
+			SafeInternalError(c, "Failed to reset trader initial balance", err)
+			return
+		}
+	}
+
 	// Remove old trader from memory first (this also stops if running)
 	s.traderManager.RemoveTrader(traderID)
 
@@ -396,11 +741,15 @@ func (s *Server) handleStartTrader(c *gin.Context) {
 	traderID := c.Param("id")
 
 	// Verify trader belongs to current user
-	_, err := s.store.Trader().GetFullConfig(userID, traderID)
+	fullCfg, err := s.store.Trader().GetFullConfig(userID, traderID)
 	if err != nil {
 		c.JSON(http.StatusNotFound, gin.H{"error": "Trader does not exist or no access permission"})
 		return
 	}
+	traderName := traderID
+	if fullCfg != nil && fullCfg.Trader != nil && fullCfg.Trader.Name != "" {
+		traderName = fullCfg.Trader.Name
+	}
 
 	// Check if trader exists in memory and if it's running
 	existingTrader, _ := s.traderManager.GetTrader(traderID)
@@ -419,45 +768,49 @@ func (s *Server) handleStartTrader(c *gin.Context) {
 	logger.Infof("🔄 Loading trader %s from database...", traderID)
 	if loadErr := s.traderManager.LoadUserTradersFromStore(s.store, userID); loadErr != nil {
 		logger.Infof("❌ Failed to load user traders: %v", loadErr)
-		c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to load trader: " + loadErr.Error()})
+		SafeErrorWithDetails(c, http.StatusInternalServerError, describeTraderStartError(traderName, loadErr), "trader.start.load_failed", traderSetupReasonParams(loadErr, "", "trader_name", traderName), loadErr)
 		return
 	}
 
 	trader, err := s.traderManager.GetTrader(traderID)
 	if err != nil {
-		// Check detailed reason
-		fullCfg, _ := s.store.Trader().GetFullConfig(userID, traderID)
 		if fullCfg != nil && fullCfg.Trader != nil {
 			// Check strategy
 			if fullCfg.Strategy == nil {
-				c.JSON(http.StatusBadRequest, gin.H{"error": "Trader has no strategy configured, please create a strategy in Strategy Studio and associate it with the trader"})
+				SafeBadRequestWithDetails(c, describeTraderStartError(traderName, fmt.Errorf("trader has no strategy configured")), "trader.start.strategy_missing", mapStringPairs("trader_name", traderName))
 				return
 			}
 			// Check AI model
 			if fullCfg.AIModel == nil {
-				c.JSON(http.StatusBadRequest, gin.H{"error": "Trader's AI model does not exist, please check AI model configuration"})
+				SafeBadRequestWithDetails(c, formatTraderStartError("这个机器人关联的 AI 模型不存在", "请前往「设置 > 模型配置」检查后，再重新点击启动"), "trader.start.model_not_found", mapStringPairs("trader_name", traderName))
 				return
 			}
 			if !fullCfg.AIModel.Enabled {
-				c.JSON(http.StatusBadRequest, gin.H{"error": "Trader's AI model is not enabled, please enable the AI model first"})
+				SafeBadRequestWithDetails(c, formatTraderStartError(
+					fmt.Sprintf("机器人「%s」关联的 AI 模型「%s」目前还没有启用", traderName, fullCfg.AIModel.Name),
+					"请前往「设置 > 模型配置」启用它后，再重新点击启动",
+				), "trader.start.model_disabled", mapStringPairs("trader_name", traderName, "model_name", fullCfg.AIModel.Name))
 				return
 			}
 			// Check exchange
 			if fullCfg.Exchange == nil {
-				c.JSON(http.StatusBadRequest, gin.H{"error": "Trader's exchange does not exist, please check exchange configuration"})
+				SafeBadRequestWithDetails(c, formatTraderStartError("这个机器人关联的交易所账户不存在", "请前往「设置 > 交易所配置」检查后，再重新点击启动"), "trader.start.exchange_not_found", mapStringPairs("trader_name", traderName))
 				return
 			}
 			if !fullCfg.Exchange.Enabled {
-				c.JSON(http.StatusBadRequest, gin.H{"error": "Trader's exchange is not enabled, please enable the exchange first"})
+				SafeBadRequestWithDetails(c, formatTraderStartError(
+					fmt.Sprintf("机器人「%s」关联的交易所账户「%s」目前还没有启用", traderName, exchangeDisplayName(fullCfg.Exchange)),
+					"请前往「设置 > 交易所配置」启用它后，再重新点击启动",
+				), "trader.start.exchange_disabled", mapStringPairs("trader_name", traderName, "exchange_name", exchangeDisplayName(fullCfg.Exchange)))
 				return
 			}
 		}
 		// Check if there's a specific load error
 		if loadErr := s.traderManager.GetLoadError(traderID); loadErr != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to load trader: " + loadErr.Error()})
+			SafeBadRequestWithDetails(c, describeTraderStartError(traderName, loadErr), "trader.start.load_failed", traderSetupReasonParams(loadErr, "", "trader_name", traderName))
 			return
 		}
-		c.JSON(http.StatusNotFound, gin.H{"error": "Failed to load trader, please check AI model, exchange and strategy configuration"})
+		SafeBadRequestWithDetails(c, describeTraderStartError(traderName, err), "trader.start.setup_invalid", traderSetupReasonParams(err, "", "trader_name", traderName))
 		return
 	}