Files

T

- 删除所有 logger.debug 调试日志
- 删除过于详细的 logger.info 常规操作日志
- 保留 logger.error 和 logger.warn 重要错误和警告日志
- 优化日志输出，减少生产环境日志噪音

2025-12-02 22:22:39 +08:00

16 KiB

Raw Blame History

跟单订单跟踪与统计设计文档

1. 方案概述

采用订单跟踪匹配方案，精确追踪每笔买入订单，当 Leader 卖出时进行精确匹配，实现：

精确的买入-卖出匹配关系
准确的盈亏计算（已实现/未实现）
完整的订单统计信息
多维度数据统计

2. 核心思路

2.1 事件监听

当前监听的事件类型：交易事件（trade）

事件来源：
- WebSocket User Channel：event_type = "trade"
- 轮询 CLOB API：GET /trades?user={leaderAddress}
触发时机：交易已成交
数据字段：id（trade_id）、market、side（BUY/SELL）、price、size、timestamp
去重标识：leader_id + trade_id（trade.id）

说明：

只监听已成交的交易事件，不监听订单创建事件
交易事件表示 Leader 已经完成买入或卖出操作
通过 trade.id 进行去重，确保同一笔交易只处理一次

2.2 买入订单跟踪

当 Leader 买入时（通过交易事件）：

检测到 side = "BUY" 的交易事件
创建跟单买入订单
记录到 copy_order_tracking 表
记录买入数量、价格、状态等信息

2.3 卖出订单匹配

当 Leader 卖出时（通过交易事件）：

检测到 side = "SELL" 的交易事件
查找未匹配的买入订单（FIFO 策略）
按比例匹配卖出数量
更新买入订单的匹配状态
记录匹配关系到 sell_match_record 和 sell_match_detail

2.4 匹配策略

FIFO（先进先出）：按买入时间顺序匹配
部分匹配：支持一个买入订单被多次卖出匹配
状态管理：filled → partially_matched → fully_matched

3. 数据模型

3.1 订单跟踪表（copy_order_tracking）

CREATE TABLE copy_order_tracking (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    copy_trading_id BIGINT NOT NULL,  -- 跟单关系ID
    account_id BIGINT NOT NULL,
    leader_id BIGINT NOT NULL,
    template_id BIGINT NOT NULL,
    market_id VARCHAR(100) NOT NULL,
    side VARCHAR(10) NOT NULL,  -- YES/NO
    buy_order_id VARCHAR(100) NOT NULL,  -- 跟单买入订单ID
    leader_buy_trade_id VARCHAR(100) NOT NULL,  -- Leader 买入交易ID
    quantity DECIMAL(20, 8) NOT NULL,  -- 买入数量
    price DECIMAL(20, 8) NOT NULL,  -- 买入价格
    matched_quantity DECIMAL(20, 8) NOT NULL DEFAULT 0,  -- 已匹配卖出数量
    remaining_quantity DECIMAL(20, 8) NOT NULL,  -- 剩余未匹配数量
    status VARCHAR(20) NOT NULL,  -- filled, fully_matched, partially_matched
    created_at BIGINT NOT NULL,
    updated_at BIGINT NOT NULL,
    INDEX idx_copy_trading (copy_trading_id),
    INDEX idx_remaining (remaining_quantity, status)
);

3.2 卖出匹配记录表（sell_match_record）

CREATE TABLE sell_match_record (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    copy_trading_id BIGINT NOT NULL,
    sell_order_id VARCHAR(100) NOT NULL,  -- 跟单卖出订单ID
    leader_sell_trade_id VARCHAR(100) NOT NULL,  -- Leader 卖出交易ID
    market_id VARCHAR(100) NOT NULL,
    side VARCHAR(10) NOT NULL,
    total_matched_quantity DECIMAL(20, 8) NOT NULL,  -- 总匹配数量
    sell_price DECIMAL(20, 8) NOT NULL,  -- 卖出价格
    total_realized_pnl DECIMAL(20, 8) NOT NULL,  -- 总已实现盈亏
    created_at BIGINT NOT NULL,
    INDEX idx_copy_trading (copy_trading_id)
);

3.3 匹配明细表（sell_match_detail）

CREATE TABLE sell_match_detail (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    match_record_id BIGINT NOT NULL,  -- 关联 sell_match_record.id
    tracking_id BIGINT NOT NULL,  -- 关联 copy_order_tracking.id
    buy_order_id VARCHAR(100) NOT NULL,
    matched_quantity DECIMAL(20, 8) NOT NULL,  -- 匹配的数量
    buy_price DECIMAL(20, 8) NOT NULL,
    sell_price DECIMAL(20, 8) NOT NULL,
    realized_pnl DECIMAL(20, 8) NOT NULL,  -- 盈亏 = (sell_price - buy_price) * matched_quantity
    created_at BIGINT NOT NULL,
    FOREIGN KEY (match_record_id) REFERENCES sell_match_record(id),
    FOREIGN KEY (tracking_id) REFERENCES copy_order_tracking(id)
);

4. 核心流程

4.1 买入订单跟踪流程

Leader 买入交易
  ↓
检测到交易，计算跟单数量
  ↓
根据模板模式计算：
  - RATIO 模式: 数量 = Leader 数量 × copyRatio
  - FIXED 模式: 数量 = fixedAmount / 买入价格
  ↓
创建跟单买入订单
  ↓
记录到 copy_order_tracking
  - quantity: 买入数量
  - price: 买入价格
  - remaining_quantity: 初始等于 quantity
  - status: "filled"

4.2 卖出订单匹配流程

Leader 卖出交易
  ↓
查找未匹配的买入订单（remaining_quantity > 0）
  ↓
按 FIFO 顺序匹配
  ↓
计算匹配数量（统一按比例，不区分模式）
  - 需要匹配数量 = Leader 卖出数量 × copyRatio
  - 实际匹配数量 = min(需要匹配数量, 剩余持仓数量)
  ↓
更新买入订单状态
  - matched_quantity += 匹配数量
  - remaining_quantity -= 匹配数量
  - status: 根据剩余数量更新
  ↓
记录匹配关系
  - sell_match_record: 卖出订单记录
  - sell_match_detail: 匹配明细（每笔买入订单的匹配）

重要说明：

买入时：根据模板的 copyMode 计算（RATIO 按比例，FIXED 按固定金额）
卖出时：统一按比例计算（Leader 卖出数量 × copyRatio），不区分模式
固定金额模式：只影响买入时的计算，卖出时仍然按比例

4.3 匹配计算示例

示例1：比例模式

场景（比例模式，copyRatio = 100%）：
- 买入订单1: quantity=100, remaining=100
- 买入订单2: quantity=50, remaining=50
- Leader 卖出: 120

匹配过程：
1. 计算需要匹配：120 × 100% = 120
2. 订单1: 匹配 min(100, 120) = 100，剩余需匹配 = 20
3. 订单2: 匹配 min(50, 20) = 20，剩余需匹配 = 0

结果：
- 订单1: remaining = 0, status = "fully_matched"
- 订单2: remaining = 30, status = "partially_matched"
- 跟单卖出: 120

示例2：固定金额模式

场景（固定金额模式，fixedAmount = 15 USDC，copyRatio = 100%）：
- Leader 买入: 100 数量，价格 0.5
- 跟单买入: 15 / 0.5 = 30 数量（固定金额）
- Leader 卖出: 50 数量，价格 0.7

匹配过程：
1. 计算需要匹配：50 × 100% = 50（按比例，不按固定金额）
2. 订单1: 匹配 min(30, 50) = 30，剩余需匹配 = 20

结果：
- 订单1: remaining = 0, status = "fully_matched"
- 跟单卖出: 30（不超过持仓）
- 注意：虽然买入时是固定金额，但卖出时按比例计算

示例3：部分比例模式

场景（比例模式，copyRatio = 30%）：
- Leader 买入: 100 数量
- 跟单买入: 100 × 30% = 30 数量
- Leader 卖出: 50 数量

匹配过程：
1. 计算需要匹配：50 × 30% = 15
2. 订单1: 匹配 min(30, 15) = 15，剩余需匹配 = 0

结果：
- 订单1: remaining = 15, status = "partially_matched"
- 跟单卖出: 15

5. 统计功能

5.1 跟单关系统计

统计维度：

总买入数量/金额/订单数
总卖出数量/金额/订单数
当前持仓数量
平均买入价格
总已实现盈亏
总未实现盈亏（持仓盈亏）
总盈亏及百分比

计算方式：

// 使用 util 方法进行数值计算
val totalBuyQuantity = buyOrders.sumOf { it.quantity.toSafeBigDecimal() }
val totalSellQuantity = sellOrders.sumOf { it.quantity.toSafeBigDecimal() }
val currentPosition = buyOrders.sumOf { it.remainingQuantity.toSafeBigDecimal() }

// 已实现盈亏
val totalRealizedPnl = matchDetails.sumOf { it.realizedPnl.toSafeBigDecimal() }

// 未实现盈亏（需要当前市场价格）
val currentPrice = getMarketCurrentPrice(marketId)
val avgBuyPrice = totalBuyAmount.div(totalBuyQuantity)
val unrealizedPnl = currentPosition.multi(currentPrice.subtract(avgBuyPrice))

// 总盈亏
val totalPnl = totalRealizedPnl.add(totalUnrealizedPnl)

5.2 订单信息

买入订单列表：

订单ID、Leader 交易ID
市场、方向、数量、价格
已匹配数量、剩余数量
订单状态

卖出订单列表：

订单ID、Leader 交易ID
市场、方向、数量、价格
已实现盈亏

匹配关系列表：

卖出订单ID
匹配的买入订单ID
匹配数量
买入价格、卖出价格
盈亏

6. 数值计算规范

使用 util 扩展方法：

toSafeBigDecimal(): 安全转换为 BigDecimal
multi(): 乘法运算
div(): 除法运算
eq(), lt(), gt(), gte(), lte(): 比较运算

示例：

// 计算匹配数量
val matchedQty = min(remainingQty.toSafeBigDecimal(), needMatchQty.toSafeBigDecimal())

// 计算盈亏
val pnl = sellPrice.toSafeBigDecimal()
    .subtract(buyPrice.toSafeBigDecimal())
    .multi(matchedQty)

// 比较数量
if (remainingQty.toSafeBigDecimal().gt(BigDecimal.ZERO)) {
    // 还有剩余
}

7. 关键实现点

7.1 买入数量计算

// 买入时根据模式计算
fun calculateBuyQuantity(leaderTrade: Trade, template: CopyTradingTemplate): BigDecimal {
    return when (template.copyMode) {
        "RATIO" -> {
            // 比例模式：Leader 数量 × 比例
            leaderTrade.size.toSafeBigDecimal()
                .multi(template.copyRatio)
        }
        "FIXED" -> {
            // 固定金额模式：固定金额 / 买入价格
            val fixedAmount = template.fixedAmount?.toSafeBigDecimal()
                ?: throw IllegalStateException("固定金额模式下 fixedAmount 不能为空")
            val buyPrice = leaderTrade.price.toSafeBigDecimal()
            fixedAmount.div(buyPrice)
        }
        else -> throw IllegalArgumentException("不支持的 copyMode: ${template.copyMode}")
    }
}

7.2 卖出匹配算法

// 卖出时统一按比例计算（不区分模式）
fun matchSellOrder(leaderSellTrade: Trade, copyTrading: CopyTrading, template: CopyTradingTemplate): BigDecimal {
    // 统一按比例计算，不区分 RATIO 或 FIXED 模式
    val needMatch = leaderSellTrade.size.toSafeBigDecimal()
        .multi(template.copyRatio)
    
    val unmatchedOrders = findUnmatchedBuyOrders(copyTrading.id, leaderSellTrade.market, leaderSellTrade.side)
    var totalMatched = BigDecimal.ZERO
    var remaining = needMatch
    
    for (order in unmatchedOrders) {
        if (remaining.lte(BigDecimal.ZERO)) break
        
        val matchQty = min(order.remainingQuantity.toSafeBigDecimal(), remaining)
        totalMatched = totalMatched.add(matchQty)
        remaining = remaining.subtract(matchQty)
        
        updateOrderTracking(order, matchQty)
        recordMatchDetail(order, matchQty, leaderSellTrade)
    }
    
    return totalMatched
}

7.3 状态更新

fun updateOrderStatus(tracking: CopyOrderTracking) {
    when {
        tracking.remainingQuantity.toSafeBigDecimal().eq(BigDecimal.ZERO) -> {
            tracking.status = "fully_matched"
        }
        tracking.matchedQuantity.toSafeBigDecimal().gt(BigDecimal.ZERO) -> {
            tracking.status = "partially_matched"
        }
        else -> {
            tracking.status = "filled"
        }
    }
}

8. API 设计

8.1 查询跟单统计

POST /api/copy-trading/statistics/detail
Request: { copyTradingId: Long }
Response: CopyTradingStatisticsResponse

8.2 查询订单列表

POST /api/copy-trading/orders/tracking
Request: { copyTradingId: Long, type: "buy" | "sell" | "matched" }
Response: OrderListResponse

9. 优势

精确匹配：每笔卖出都能追溯到对应的买入订单
准确盈亏：可以精确计算每笔交易的盈亏
完整统计：支持多维度数据统计和分析
可追溯性：完整的买入-卖出匹配关系，便于审计

10. WebSocket 与轮询去重机制

10.1 同时运行策略

WebSocket 和轮询可以同时运行：

WebSocket：作为主要数据源，实时接收交易推送
轮询：作为补充数据源，定期查询确保不遗漏
去重机制：通过 trade_id 确保同一笔交易只处理一次

10.2 去重数据模型

已处理交易表（processed_trade）

CREATE TABLE processed_trade (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    leader_id BIGINT NOT NULL,
    leader_trade_id VARCHAR(100) NOT NULL,  -- Leader 的交易ID（trade.id，唯一标识）
    trade_type VARCHAR(10) NOT NULL,  -- BUY 或 SELL
    source VARCHAR(20) NOT NULL,  -- 'websocket' 或 'polling'
    processed_at BIGINT NOT NULL,
    created_at BIGINT NOT NULL,
    UNIQUE KEY uk_leader_trade (leader_id, leader_trade_id),
    INDEX idx_processed_at (processed_at)
);

唯一标识：leader_id + leader_trade_id 组合作为唯一键