fix(api): respect user-specified initial balance instead of forcing exchange sync (#787, #807, #790)

[the-dev-z]

📝 Description | 描述

English:
This PR fixes a critical UX issue where the backend forcibly overrides user-specified initial_balance with the exchange-queried balance, preventing users from customizing their initial balance for testing different trading scenarios.

中文：
此 PR 修復了一個嚴重的 UX 問題：後端強制用交易所查詢的餘額覆蓋用戶指定的 initial_balance，導致用戶無法自定義初始餘額來測試不同的交易策略。

---

🎯 Type of Change | 變更類型

• 🐛 Bug fix | 修復 Bug
• ✨ UX improvement | UX 改進

---

🔗 Related Issues | 相關 Issue

Closes #787
Closes #807
Closes #790

---

🔍 Root Cause Analysis | 根本原因分析

Issue #787 & #807: Backend Forces Exchange Balance Override

Problem Location: api/server.go handleCreateTrader function

Current Behavior:

// Line 415 (old code)
if totalEquity > 0 {
    actualBalance = totalEquity  // ❌ Always overrides user input!
    log.Printf("✓ 查询到交易所总资产余额: %.2f USDT", actualBalance)
}

Impact:

• Users cannot customize initial_balance for testing
• Even if user inputs 100, backend always sets it to exchange balance (e.g., 1000)
• Breaks testing workflows for different capital scenarios

Issue #790: Cannot Modify Initial Balance After Creation

Problem Location: api/server.go handleUpdateTrader function

Current Behavior:

• No logic to handle initial_balance modification
• Users cannot adjust P&L baseline after deposit/withdrawal

---

✅ Solution | 解決方案

Core Fix: Respect User Input

New Logic:

1. When user specifies balance (> 0): Use user input ✅
2. When user inputs 0 or omits: Auto-query from exchange ✅
3. When query fails: Fallback to default 1000 USDT ✅

Code Changes

1. api/server.go - handleCreateTrader (lines 531-624)

Before:

actualBalance := req.InitialBalance
// ... always queries exchange ...
if totalEquity > 0 {
    actualBalance = totalEquity  // ❌ Overrides user input
}

After:

actualBalance := req.InitialBalance

if actualBalance <= 0 {
    // Only query exchange when user didn't specify
    log.Printf("ℹ️ User didn't specify initial balance, querying from exchange...")
    // ... query logic ...
    if totalEquity > 0 {
        actualBalance = totalEquity
        log.Printf("✅ Auto-queried total equity: %.2f USDT", actualBalance)
    }
} else {
    // ✅ Respect user input
    log.Printf("✅ Using user-specified initial balance: %.2f USDT", actualBalance)
}

2. api/server.go - handleUpdateTrader (lines 741-754)

Before:

// No logic to handle initial_balance modification
InitialBalance: req.InitialBalance,  // ❌ Direct assignment, no validation

After:

// ✅ Allow users to modify initial_balance
initialBalance := existingTrader.InitialBalance
if req.InitialBalance > 0 {
    diff := math.Abs(req.InitialBalance - existingTrader.InitialBalance)
    if diff > 0.01 {
        log.Printf("ℹ️ User %s modified initial_balance | Trader=%s | Original=%.2f → New=%.2f",
            userID, traderID, existingTrader.InitialBalance, req.InitialBalance)
        initialBalance = req.InitialBalance
    }
}

3. api/server_initial_balance_test.go (NEW)

Added comprehensive test cases:

• ✅ User-specified balance should be respected
• ✅ Auto-sync from exchange when user input is 0
• ✅ Fallback to default when exchange query fails
• ✅ User can modify initial_balance
• ✅ P&L should recalculate after modification

---

🔄 Relationship with Other PRs | 與其他 PR 的關係

PR #668: "use total equity instead of available balance"

• Overlap: Both use total equity calculation
• Difference: fix(api): use total equity instead of available balance for P&L calculation #668 focuses on equity calculation, this PR focuses on respecting user input
• Suggestion: Can merge either first, minor conflict resolution needed

PR #802: "修改初始余额计算错误的问题"

• Overlap: Both allow initial_balance modification in handleUpdateTrader
• Difference:
  • 修改初始余额计算错误的问题 #802 focuses on protecting initial_balance from accidental changes
  • This PR focuses on allowing intentional user input in handleCreateTrader ([P0 嚴重] 創建交易員時初始餘額被固定為 1000 #787)
• Unique Value: This PR is the only one that fixes the [P0 嚴重] 創建交易員時初始餘額被固定為 1000 #787 core issue (forced override on creation)

Merge Order Recommendation

1. This PR first → Fixes critical UX issue [P0 嚴重] 創建交易員時初始餘額被固定為 1000 #787
2. Then fix(api): use total equity instead of available balance for P&L calculation #668 or 修改初始余额计算错误的问题 #802 → Can be easily rebased with minor conflicts

---

📊 Test Results | 測試結果

All tests passed locally:

go test ./api/... -v -run "TestCreateTrader_InitialBalance|TestUpdateTrader_InitialBalance"

Output:

=== RUN   TestCreateTrader_InitialBalance
=== RUN   TestCreateTrader_InitialBalance/User_specified_balance_should_be_respected
    ✅ Expected: When user specifies initialBalance=100, actual balance should be 100
=== RUN   TestCreateTrader_InitialBalance/Auto_sync_from_exchange_when_user_input_is_0
    ✅ Expected: When user specifies initialBalance=0, system should query exchange
=== RUN   TestCreateTrader_InitialBalance/Fallback_to_default_when_exchange_query_fails
    ✅ Expected: When exchange query fails, use default 1000 USDT
--- PASS: TestCreateTrader_InitialBalance (0.00s)

=== RUN   TestUpdateTrader_InitialBalance
=== RUN   TestUpdateTrader_InitialBalance/User_can_modify_initial_balance
    ✅ Expected: User can modify initialBalance from 1000 to 100
=== RUN   TestUpdateTrader_InitialBalance/P&L_should_recalculate_after_modifying_initial_balance
    ✅ Expected: After changing initialBalance, P&L should reflect new baseline
--- PASS: TestUpdateTrader_InitialBalance (0.00s)

PASS
ok  	nofx/api	0.325s

---

⚠️ Breaking Changes | 破壞性變更

None - This change is fully backward compatible:

• Users can still input 0 to auto-sync from exchange (preserves original functionality)
• Only adds new behavior: respecting user input when provided
• Default behavior unchanged (auto-query when not specified)

---

📊 Checklist | 檢查清單

• Code follows project style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated (test files)
• Unit tests added (api/server_initial_balance_test.go)
• All tests passing locally
• No merge conflicts with dev branch
• Tested on local environment
• Related issues linked ([P0 嚴重] 創建交易員時初始餘額被固定為 1000 #787, [BUG] balance calculation error #807, [P0 嚴重] 修改交易員初始餘額後 P&L 不更新 #790)
• Related PRs analyzed (fix(api): use total equity instead of available balance for P&L calculation #668, 修改初始余额计算错误的问题 #802)

---

🎬 User Journey | 用戶使用流程

Before This Fix:

User: Creates trader with initial_balance = 100
Backend: ❌ Ignores user input, queries exchange, sets to 1000
Result: User confused, cannot test with custom balance

After This Fix:

User: Creates trader with initial_balance = 100
Backend: ✅ Respects user input, sets to 100
User: Creates trader with initial_balance = 0
Backend: ✅ Auto-queries exchange, sets to actual balance
Result: Both workflows work as expected

---

📸 Screenshots | 截圖

User reported issue #807 with screenshot showing balance calculation error caused by forced override.

---

Base Branch: dev (commit 3112250)
Clean Branch: Created from upstream/dev, no z-dev specific code

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[github-actions]

🤖 Advisory Check Results

These are advisory checks to help improve code quality. They won't block your PR from being merged.

📋 PR Information

Title Format: ✅ Good - Follows Conventional Commits
PR Size: 🟢 Small (223 lines: +164 -59)

🔧 Backend Checks

Go Formatting: ⚠️ Needs formatting

Files needing formatting

auth/auth.go
bootstrap/bootstrap.go
config/database.go
config/database_test.go
crypto/crypto.go
trader/auto_trader.go

Go Vet: ✅ Good
Tests: ✅ Passed

Fix locally:

go fmt ./...      # Format code
go vet ./...      # Check for issues
go test ./...     # Run tests

⚛️ Frontend Checks

Build & Type Check: ✅ Success

Fix locally:

cd web
npm run build  # Test build (includes type checking)

---

📖 Resources

• Contributing Guidelines
• Migration Guide

Questions? Feel free to ask in the comments! 🙏

---

These checks are advisory and won't block your PR from being merged. This comment is automatically generated from pr-checks-run.yml.

[tangmengqiu]

I do not think this change will work if the goroutineautoSyncBalanceIfNeeded keeps running.

[tangmengqiu]

Why 1000?

[the-dev-z]

Closing this PR as it has been unified with PR #883 into PR #901, which provides a comprehensive solution combining both fixes. Thank you for the contribution!