撮合系统是什么？把"买卖双方配对成成交"的那台发动机到底做了什么

import java.math.BigDecimal;
import java.util.Comparator;
import java.util.TreeMap;

/**
 * 订单方向枚举
 * BUY: 买单方向
 * SELL: 卖单方向
 */
enum Direction {
    BUY,
    SELL
}

/**
 * 订单实体类
 * 表示一个完整的交易订单，包含订单的所有属性
 */
class OrderEntity {
    /** 订单唯一序列号，用于时间优先排序 */
    public final long sequenceId;
    /** 订单方向：BUY或SELL */
    public final Direction direction;
    /** 订单价格，使用BigDecimal确保精确计算 */
    public final BigDecimal price;
    /** 订单数量，剩余可成交数量 */
    public long quantity;
    /** 订单创建时间戳 */
    public final long timestamp;
    
    /**
     * 构造订单实体
     * @param sequenceId 订单唯一序列号
     * @param direction 订单方向
     * @param price 订单价格
     * @param quantity 订单数量
     */
    public OrderEntity(long sequenceId, Direction direction, BigDecimal price, long quantity) {
        this.sequenceId = sequenceId;
        this.direction = direction;
        this.price = price;
        this.quantity = quantity;
        this.timestamp = System.currentTimeMillis();
    }
    
    /**
     * 重写toString方法，用于打印订单信息
     * @return 格式化的订单字符串
     */
    @Override
    public String toString() {
        return String.format("Order{id=%d, dir=%s, price=%s, qty=%d}", 
                sequenceId, direction, price, quantity);
    }
}

/**
 * 订单键记录类
 * 用于订单簿中的排序，包含序列号和价格两个关键字段
 * @param sequenceId 订单序列号
 * @param price 订单价格
 */
record OrderKey(long sequenceId, BigDecimal price) {
    // 注意：使用record自动生成equals和hashCode方法，确保TreeMap能正确定位订单
}

/**
 * 订单簿类
 * 管理同一方向的所有订单，实现订单的排序、添加、移除和查询
 */
class OrderBook {
    /** 订单簿方向：BUY或SELL */
    public final Direction direction;
    /**
     * 订单存储的核心数据结构
     * 使用TreeMap实现O(logN)的插入、删除和查询效率
     * 排序规则由订单方向决定
     */
    public final TreeMap<OrderKey, OrderEntity> book;

    /**
     * 卖盘排序比较器
     * 规则：1. 价格从低到高；2. 价格相同时，序列号小的优先（时间优先）
     */
    private static final Comparator<OrderKey> SORT_SELL = (o1, o2) -> {
        // 价格比较：低价格在前
        int priceCmp = o1.price().compareTo(o2.price());
        // 价格相同时，序列号比较：小序列号在前（时间优先）
        return priceCmp == 0 ? Long.compare(o1.sequenceId(), o2.sequenceId()) : priceCmp;
    };
    
    /**
     * 买盘排序比较器
     * 规则：1. 价格从高到低；2. 价格相同时，序列号小的优先（时间优先）
     */
    private static final Comparator<OrderKey> SORT_BUY = (o1, o2) -> {
        // 价格比较：高价格在前（注意o2和o1的顺序）
        int priceCmp = o2.price().compareTo(o1.price());
        // 价格相同时，序列号比较：小序列号在前（时间优先）
        return priceCmp == 0 ? Long.compare(o1.sequenceId(), o2.sequenceId()) : priceCmp;
    };
    
    /**
     * 构造订单簿
     * @param direction 订单簿方向
     */
    public OrderBook(Direction direction) {
        this.direction = direction;
        // 根据订单方向选择对应的排序比较器
        this.book = new TreeMap<>(direction == Direction.BUY ? SORT_BUY : SORT_SELL);
    }
    
    /**
     * 获取最优价格订单
     * 买盘返回价格最高的订单，卖盘返回价格最低的订单
     * @return 最优价格订单，若订单簿为空则返回null
     */
    public OrderEntity getFirst() {
        return this.book.isEmpty() ? null : this.book.firstEntry().getValue();
    }
    
    /**
     * 从订单簿中移除指定订单
     * @param order 要移除的订单
     * @return 移除成功返回true，否则返回false
     */
    public boolean remove(OrderEntity order) {
        // 使用订单的序列号和价格构建OrderKey，用于在TreeMap中定位
        return this.book.remove(new OrderKey(order.sequenceId, order.price)) != null;
    }
    
    /**
     * 向订单簿中添加订单
     * @param order 要添加的订单
     * @return 添加成功返回true，若订单已存在则返回false
     */
    public boolean add(OrderEntity order) {
        // 使用订单的序列号和价格构建OrderKey，TreeMap会自动根据比较器排序
        return this.book.put(new OrderKey(order.sequenceId, order.price), order) == null;
    }
    
    /**
     * 重写toString方法，用于打印订单簿状态
     * @return 格式化的订单簿字符串
     */
    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append(direction).append(" Book:\n");
        for (OrderEntity order : book.values()) {
            sb.append("  ").append(order).append("\n");
        }
        return sb.toString();
    }
}

/**
 * 成交记录类
 * 表示一次成功的撮合交易，包含成交的关键信息
 */
class Trade {
    /** 成交的买单ID */
    public final long buyOrderId;
    /** 成交的卖单ID */
    public final long sellOrderId;
    /** 成交价格 */
    public final BigDecimal price;
    /** 成交数量 */
    public final long quantity;
    /** 成交时间戳 */
    public final long timestamp;
    
    /**
     * 构造成交记录
     * @param buyOrderId 买单ID
     * @param sellOrderId 卖单ID
     * @param price 成交价格
     * @param quantity 成交数量
     */
    public Trade(long buyOrderId, long sellOrderId, BigDecimal price, long quantity) {
        this.buyOrderId = buyOrderId;
        this.sellOrderId = sellOrderId;
        this.price = price;
        this.quantity = quantity;
        this.timestamp = System.currentTimeMillis();
    }
    
    /**
     * 重写toString方法，用于打印成交信息
     * @return 格式化的成交字符串
     */
    @Override
    public String toString() {
        return String.format("Trade{buyId=%d, sellId=%d, price=%s, qty=%d}", 
                buyOrderId, sellOrderId, price, quantity);
    }
}

/**
 * 撮合引擎核心类
 * 实现买卖订单的自动撮合逻辑，遵循价格优先、时间优先的原则
 */
public class MatchEngine {
    /** 买盘订单簿，管理所有未成交的买单 */
    private final OrderBook buyBook;
    /** 卖盘订单簿，管理所有未成交的卖单 */
    private final OrderBook sellBook;
    /** 订单序列号计数器，用于生成唯一的订单ID */
    private long sequenceCounter = 0;
    
    /**
     * 构造撮合引擎
     * 初始化买盘和卖盘订单簿
     */
    public MatchEngine() {
        this.buyBook = new OrderBook(Direction.BUY);
        this.sellBook = new OrderBook(Direction.SELL);
    }
    
    /**
     * 生成唯一的订单序列号
     * 使用synchronized确保线程安全
     * @return 下一个唯一序列号
     */
    private synchronized long nextSequenceId() {
        return ++sequenceCounter;
    }
    
    /**
     * 提交新订单到撮合引擎
     * @param direction 订单方向
     * @param price 订单价格
     * @param quantity 订单数量
     */
    public void submitOrder(Direction direction, BigDecimal price, long quantity) {
        // 创建新订单，生成唯一序列号
        OrderEntity newOrder = new OrderEntity(nextSequenceId(), direction, price, quantity);
        System.out.println("\n=== 提交订单: " + newOrder);
        
        // 根据订单方向执行不同的撮合逻辑
        if (direction == Direction.BUY) {
            matchBuyOrder(newOrder);
        } else {
            matchSellOrder(newOrder);
        }
        
        // 打印当前订单簿状态，便于观察撮合结果
        System.out.println(buyBook);
        System.out.println(sellBook);
    }
    
    /**
     * 撮合买单逻辑
     * 尝试将买单与卖盘订单进行匹配，遵循价格优先、时间优先原则
     * @param buyOrder 待撮合的买单
     */
    private void matchBuyOrder(OrderEntity buyOrder) {
        // 循环撮合，直到买单完全成交或无法匹配
        while (buyOrder.quantity > 0) {
            // 获取卖盘中的最优卖单（价格最低的卖单）
            OrderEntity bestSell = sellBook.getFirst();
            
            // 情况1：卖盘为空，没有可匹配的卖单
            if (bestSell == null) {
                // 将买单加入买盘，等待后续匹配
                buyBook.add(buyOrder);
                break;
            }
            
            // 情况2：买单价格低于最优卖单价格，无法成交
            // 注意：使用compareTo方法比较BigDecimal，避免equals方法的精度问题
            if (buyOrder.price.compareTo(bestSell.price) < 0) {
                // 将买单加入买盘，等待后续匹配
                buyBook.add(buyOrder);
                break;
            }
            
            // 情况3：可以成交，计算可成交数量
            // 取买单和卖单剩余数量的最小值
            long matchQty = Math.min(buyOrder.quantity, bestSell.quantity);
            
            // 生成成交记录，使用卖单价格作为成交价格
            Trade trade = new Trade(buyOrder.sequenceId, bestSell.sequenceId, bestSell.price, matchQty);
            System.out.println("✅ 成交: " + trade);
            
            // 更新买单和卖单的剩余数量
            buyOrder.quantity -= matchQty;
            bestSell.quantity -= matchQty;
            
            // 如果卖单完全成交，从卖盘移除
            if (bestSell.quantity == 0) {
                sellBook.remove(bestSell);
            }
            // 继续循环，尝试匹配买单的剩余数量
        }
    }
    
    /**
     * 撮合卖单逻辑
     * 尝试将卖单与买盘订单进行匹配，遵循价格优先、时间优先原则
     * @param sellOrder 待撮合的卖单
     */
    private void matchSellOrder(OrderEntity sellOrder) {
        // 循环撮合，直到卖单完全成交或无法匹配
        while (sellOrder.quantity > 0) {
            // 获取买盘中的最优买单（价格最高的买单）
            OrderEntity bestBuy = buyBook.getFirst();
            
            // 情况1：买盘为空，没有可匹配的买单
            if (bestBuy == null) {
                // 将卖单加入卖盘，等待后续匹配
                sellBook.add(sellOrder);
                break;
            }
            
            // 情况2：卖单价格高于最优买单价格，无法成交
            // 注意：使用compareTo方法比较BigDecimal，避免equals方法的精度问题
            if (sellOrder.price.compareTo(bestBuy.price) > 0) {
                // 将卖单加入卖盘，等待后续匹配
                sellBook.add(sellOrder);
                break;
            }
            
            // 情况3：可以成交，计算可成交数量
            // 取卖单和买单剩余数量的最小值
            long matchQty = Math.min(sellOrder.quantity, bestBuy.quantity);
            
            // 生成成交记录，使用买单价格作为成交价格
            Trade trade = new Trade(bestBuy.sequenceId, sellOrder.sequenceId, bestBuy.price, matchQty);
            System.out.println("✅ 成交: " + trade);
            
            // 更新卖单和买单的剩余数量
            sellOrder.quantity -= matchQty;
            bestBuy.quantity -= matchQty;
            
            // 如果买单完全成交，从买盘移除
            if (bestBuy.quantity == 0) {
                buyBook.remove(bestBuy);
            }
            // 继续循环，尝试匹配卖单的剩余数量
        }
    }
    
    /**
     * 主方法，用于测试撮合引擎功能
     * @param args 命令行参数（未使用）
     */
    public static void main(String[] args) {
        // 创建撮合引擎实例
        MatchEngine engine = new MatchEngine();
        
        // 测试场景1：添加多个卖单，观察卖盘排序
        // 预期：卖盘按价格从低到高排序：100.40 -> 100.50 -> 100.60
        engine.submitOrder(Direction.SELL, new BigDecimal("100.50"), 100);
        engine.submitOrder(Direction.SELL, new BigDecimal("100.60"), 200);
        engine.submitOrder(Direction.SELL, new BigDecimal("100.40"), 150);
        
        // 测试场景2：添加买单，触发成交
        // 预期：
        // 1. 与100.40的卖单成交150股
        // 2. 与100.50的卖单成交50股
        // 3. 买单完全成交，退出
        engine.submitOrder(Direction.BUY, new BigDecimal("100.50"), 200);
        
        // 测试场景3：添加高价买单，触发更多成交
        // 预期：
        // 1. 与剩余的100.50卖单成交50股
        // 2. 与100.60的卖单成交200股
        // 3. 买单剩余50股，加入买盘
        engine.submitOrder(Direction.BUY, new BigDecimal("100.70"), 300);
        
        // 测试场景4：添加低价卖单，触发成交
        // 预期：
        // 1. 与买盘中100.70的买单成交50股
        // 2. 买单完全成交，退出
        engine.submitOrder(Direction.SELL, new BigDecimal("100.30"), 50);
    }
}