Exchange futures engine, implements by Golang.
- Go 1.21+
- Make (optional, for using Makefile targets)
# Clone the repository
git clone <repository-url>
cd futures_engine
# Download dependencies
go mod download
# Build the project
make build
# or
go build -o bin/futures_engine ./cmd/futures_engine
# Run the application
./bin/futures_engine
# Run with options
./bin/futures_engine --help
./bin/futures_engine --version
./bin/futures_engine --log-level debug
# Run tests
make test
# or
go test -v ./...
# Run with coverage
make coverage
# Development mode with auto-reload (requires air)
make devmake build- Build the binarymake test- Run testsmake coverage- Run tests with coveragemake lint- Run linter (requires golangci-lint)make clean- Clean build artifactsmake release- Build optimized release binarymake help- Show all available targets
├── cmd/futures_engine/ # Application entrypoint
├── internal/ # Private application code
│ ├── config/ # Configuration management
│ ├── logger/ # Logging utilities
│ └── version/ # Version information
├── pkg/utils/ # Public utility packages
├── docs/ # Documentation
├── .github/workflows/ # CI/CD pipelines
├── Dockerfile # Container configuration
├── Makefile # Build automation
└── .golangci.yml # Linting configuration
職責：
- 接收、驗證、儲存訂單
- 訂單狀態管理（pending, partially filled, filled, cancelled）
- 訂單類型支援（limit, market, stop-loss, take-profit）
為什麼需要：
- 與現貨不同，永續合約的訂單需要關聯到特定倉位，並且要驗證保證金充足性。訂單不只是簡單的買賣，還涉及開倉、平倉、加倉等操作。
職責：
- 維護多個交易對的 order book
- 價格優先、時間優先的撮合邏輯
- 處理不同訂單類型的撮合策略
- 生成成交記錄（trades）
與現貨的差異：
- 撮合時需要即時更新倉位狀態，並觸發保證金檢查。每筆成交都可能影響用戶的未實現盈虧。
職責：
- 倉位開倉、加倉、減倉、平倉邏輯
- 計算平均開倉價格
- 追蹤每個用戶的多空倉位
- 倉位模式管理（單向持倉/雙向持倉）
核心概念：
- 這是永續合約特有的模組。每個用戶可以持有多頭（long）或空頭（short）倉位，系統需要精確追蹤倉位大小、開倉均價和方向。
職責：
- 初始保證金（Initial Margin）計算
- 維持保證金（Maintenance Margin）計算
- 可用餘額計算
- 保證金模式支援（全倉/逐倉）
理論基礎：
- 保證金是槓桿交易的核心。初始保證金決定了用戶能開多大的倉位，維持保證金則是防止爆倉的最後防線。
職責：
- 實時監控所有倉位的風險率
- 計算強平價格
- 執行自動減倉（ADL）邏輯
- 風險限額管理
為什麼重要：
- 這是保護交易所和用戶的核心模組。需要高效地計算每個倉位的風險，並在必要時觸發強平。
職責：
- 執行強制平倉
- 管理強平訂單隊列
- 接管被強平的倉位
- 計算並分配強平罰金
運作原理：
- 當倉位的保證金率低於維持保證金要求時，系統會接管倉位並以市價平倉，避免穿倉（負餘額）。
職責：
- 計算標記價格（避免市場操縱）
- 整合多個數據源的價格
- 提供公平的強平觸發價格
設計理由：
- 使用標記價格而非最新成交價來計算未實現盈虧和強平，可以防止市場操縱導致的不公平強平。
職責：
- 計算資金費率
- 定時收取/支付資金費用
- 維持永續合約價格錨定現貨
核心機制：
- 這是永續合約特有的機制，通過定期的資金費用交換，使合約價格不會長期偏離現貨價格。
職責：
- 處理已實現盈虧結算
- 更新用戶餘額
- 處理資金費用結算
- 管理保險基金
重要性：
- 確保所有的盈虧都能正確結算，並管理系統的保險基金以應對穿倉損失。
職責：
- 累積強平罰金
- 覆蓋穿倉損失
- 管理基金使用規則
存在理由：
- 當強平無法以維持保證金價格成交時，保險基金用來覆蓋損失，保護其他用戶。
職責：
- 計算未實現盈虧（Unrealized PnL）
- 計算已實現盈虧（Realized PnL）
- 支援不同的計算模式（Mark Price / Last Price）
計算邏輯：
- 需要考慮開倉均價、當前價格、倉位方向和大小，並且要處理部分平倉的複雜情況。
職責：
- 從多個現貨交易所獲取價格
- 計算加權平均價格
- 處理異常價格數據
設計目的：
- 提供穩定、難以操縱的參考價格，作為標記價格計算的基礎。
依賴關係：
用戶下單 → OMS驗證 → Margin檢查 → Matching Engine撮合
↓
Position Manager更新倉位
↓
Risk Engine評估風險
↓
如需強平 → Liquidation Engine
↓
Settlement Engine結算
- 高並發處理：使用 Go 的 goroutine 和 channel 實現高效的並發處理
- 記憶體管理：Order book 需要在記憶體中維護，但也要有持久化機制
- 精度問題：使用 decimal 類型處理金額計算，避免浮點數精度問題
- 延遲優化：核心撮合路徑需要極低延遲，考慮使用 lock-free 數據結構