monisuo/ASSET_API_DIAGNOSIS.md

# Flutter资产页面API接口问题诊断报告

**诊断时间**: 2026-03-24 13:55
**问题状态**: ✅ 已定位
**影响**: Flutter前端资产页面无法正确显示数据

---

## 🔍 问题诊断

### Flutter前端期望的API返回格式

**接口**: `/api/asset/overview`

**期望字段**:
```json
{
  "totalAsset": "15500.00",      // 总资产
  "fundBalance": "15500.00",     // 资金账户余额
  "tradeBalance": "0.00",        // 交易账户余额
  "totalProfit": "0.00"          // 总盈亏
}
```

### 后端实际返回的格式

**当前字段**:
```json
{
  "totalAssets": 15500.0,        // ❌ 字段名不匹配（应该是 totalAsset）
  "fundBalance": 15500.0,        // ✅ 正确
  "tradeValue": 0,               // ❌ 字段名不匹配（应该是 tradeBalance）
  "fundFrozen": 0.0,             // ⚠️  Flutter不需要
  "positions": []                // ⚠️  Flutter不需要
}
```

### 问题清单

| 问题 | 严重性 | 说明 |
|------|--------|------|
| ❌ 字段名错误 | 高 | `totalAssets` 应该是 `totalAsset` |
| ❌ 字段名错误 | 高 | `tradeValue` 应该是 `tradeBalance` |
| ❌ 缺失字段 | 高 | 缺少 `totalProfit` 字段 |
| ⚠️  多余字段 | 低 | `fundFrozen` 和 `positions` Flutter不需要 |

---

## 🛠️ 修复方案

### 修改 AssetService.getOverview() 方法

**文件**: `src/main/java/com/it/rattan/monisuo/service/AssetService.java`

**修改前**:
```java
public Map<String, Object> getOverview(Long userId) {
    Map<String, Object> result = new HashMap<>();
    
    AccountFund fund = getOrCreateFundAccount(userId);
    result.put("fundBalance", fund.getBalance());
    result.put("fundFrozen", fund.getFrozen());
    
    // ... 交易账户计算 ...
    result.put("tradeValue", tradeValue);
    result.put("positions", positions);
    
    BigDecimal totalAssets = fund.getBalance().add(tradeValue);
    result.put("totalAssets", totalAssets);
    
    return result;
}
```

**修改后**:
```java
public Map<String, Object> getOverview(Long userId) {
    Map<String, Object> result = new HashMap<>();
    
    // 资金账户
    AccountFund fund = getOrCreateFundAccount(userId);
    BigDecimal fundBalance = fund.getBalance();
    result.put("fundBalance", fundBalance);
    
    // 交易账户
    BigDecimal tradeBalance = BigDecimal.ZERO;
    BigDecimal totalCost = BigDecimal.ZERO;  // 累计成本
    BigDecimal totalValue = BigDecimal.ZERO; // 当前价值
    
    LambdaQueryWrapper<AccountTrade> wrapper = new LambdaQueryWrapper<>();
    wrapper.eq(AccountTrade::getUserId, userId)
           .gt(AccountTrade::getQuantity, BigDecimal.ZERO);
    List<AccountTrade> trades = accountTradeMapper.selectList(wrapper);
    
    for (AccountTrade trade : trades) {
        Coin coin = coinService.getCoinByCode(trade.getCoinCode());
        if (coin != null) {
            BigDecimal value = trade.getQuantity().multiply(coin.getPrice())
                    .setScale(8, RoundingMode.DOWN);
            tradeBalance = tradeBalance.add(value);
            
            // 计算成本和盈亏
            BigDecimal cost = trade.getQuantity().multiply(trade.getAvgPrice());
            totalCost = totalCost.add(cost);
            totalValue = totalValue.add(value);
        }
    }
    
    result.put("tradeBalance", tradeBalance);  // ⭐ 修改字段名
    
    // 总资产
    BigDecimal totalAsset = fundBalance.add(tradeBalance);
    result.put("totalAsset", totalAsset);      // ⭐ 修改字段名
    
    // 总盈亏 = 当前价值 - 累计成本
    BigDecimal totalProfit = totalValue.subtract(totalCost);
    result.put("totalProfit", totalProfit);    // ⭐ 新增字段
    
    return result;
}
```

---

## 📊 修复后的API返回示例

```json
{
  "code": "0000",
  "msg": "操作成功",
  "data": {
    "totalAsset": 15500.00,      // ✅ 修正字段名
    "fundBalance": 15500.00,     // ✅ 保持不变
    "tradeBalance": 0.00,        // ✅ 修正字段名
    "totalProfit": 0.00          // ✅ 新增字段
  },
  "success": true
}
```

---

## 🔍 其他接口检查

### /api/asset/fund 接口

**当前返回**:
```json
{
  "fund": {
    "id": 5,
    "userId": 5,
    "balance": 15500.0,          // ✅ Flutter期望
    "frozen": 0.0,
    "totalDeposit": 15500.0,
    "totalWithdraw": 0.0,
    "createTime": "...",
    "updateTime": "..."
  }
}
```

**Flutter期望**:
```dart
class AccountFund {
  final String balance;         // ✅ 匹配
  final String frozenBalance;   // ❌ 后端是 frozen，前端是 frozenBalance
}
```

**问题**: 字段名不匹配 `frozen` vs `frozenBalance`

**修复**: Flutter前端应该使用 `frozen` 而不是 `frozenBalance`

---

### /api/asset/trade 接口

**当前返回**:
```json
{
  "positions": []  // ✅ 正确
}
```

**Flutter期望**:
```dart
class AccountTrade {
  final String currentValue;  // ❌ 后端是 value
  final String profit;        // ❌ 后端没有
  final double profitRate;    // ❌ 后端没有
}
```

**问题**: 缺少盈亏相关字段

---

## 🎯 修复优先级

### P0 (立即修复)
1. ✅ 修改 `getOverview()` 方法的字段名
2. ✅ 添加 `totalProfit` 字段

### P1 (短期修复)
3. ⏳ 完善 `/api/asset/trade` 接口，添加盈亏计算
4. ⏳ 统一字段命名规范

### P2 (长期优化)
5. ⏳ Flutter前端适配后端实际字段
6. ⏳ 添加API文档和接口规范

---

## 📝 修复步骤

### 步骤1: 修改AssetService.java

```bash
cd ~/Desktop/projects/monisuo
# 编辑 AssetService.java 的 getOverview() 方法
```

### 步骤2: 重新编译

```bash
mvn clean package -DskipTests
```

### 步骤3: 重启服务

```bash
pkill -f monisuo-1.0.jar
nohup java -jar target/monisuo-1.0.jar --server.port=5010 > logs/app.log 2>&1 &
```

### 步骤4: 测试验证

```bash
./test_asset_api.sh
```

---

## ✅ 验证清单

- [ ] 后端返回 `totalAsset` 字段
- [ ] 后端返回 `tradeBalance` 字段
- [ ] 后端返回 `totalProfit` 字段
- [ ] Flutter前端能正确显示总资产
- [ ] Flutter前端能正确显示资金余额
- [ ] Flutter前端能正确显示交易余额
- [ ] Flutter前端能正确显示总盈亏

---

**最后更新**: 2026-03-24 13:55
**状态**: ✅ 问题已定位，等待修复
**预计修复时间**: 10分钟