MMK system guide

mm-workflow

呢頁係 v-mm/mm-hub/crypto-mm-server-v 嘅操作地圖，目標係幫你由「呢份 server 下載版有咩」一路睇到「點安全修改 algo」。內容根據 MMK_System_Documentation_ZH.md、QUICK_START_ZH.md、ARCHITECTURE.md 同主要 C++ 檔案整理。

閱讀路線

1. 先建立模型系統做咩、幾個大模組點分工。 2. 啟動流程由 binary、XML、MongoDB 到策略 Start。 3. 行情與訂單流Quote 點入策略，Order 點回報和持久化。 4. Algo 原理期現套利、depth weighted price、下單與改單。 5. 點入手改應先睇邊啲檔、改邊層最安全。 6. 安全試驗dry-run、mock、testnet、避免真倉事故。

1. Mental Model：呢個系統係咩

MMK Trading System 係一個 C++17 / CMake 寫嘅 Bybit 交易系統，主要目標係做 spot-perpetual arbitrage。佢唔係單一 script，而係由 manager、connector、strategy、persistence 幾層組成。

mmk_config.xml + MongoDB
        |
        v
MMKManager
  |-- TradeManager ------ OrderManager ------ LMDB / MongoDB
  |        |
  |        +-- BybitWssTrade / Bybit REST
  |
  |-- MarketDataManager -- BybitMarketData
  |
  +-- StrategyBase ------- MultiFutSpotArbStrategy_Update

git/MMK/MMKTradingSystem主要 C++ 源碼樹。

mongodb_backup/MMKDBMongoDB collections backup，包括 Instruments、StrategyParameter、Orders。

testPython / C 測試與 connectivity 示例。

git_bk完整備份樹，體積大，主要作對照用途。

2. 啟動流程：由 binary 到策略開始跑

入口 binary 係 maintest/mkk_system_test.cc。佢建立 MMKManager，讀 ./mmk_config.xml，註冊 MultiFutSpotArbStrategy_Update，再呼叫 Start()。

1mkk_system_test建立 MMKManager，指定 config file。

2MMKManager::Init()解析 XML，連 MongoDB，讀 Instruments / StrategyParameter。

3OrderManager::Start()開 LMDB database：orders / positions。

4TradeManager::Start()啟動 Bybit trade provider，準備收 private order updates。

5MarketDataManager::Start()啟動 Bybit market data websocket。

6Strategy::Start()訂閱行情與訂單，開 TradingPairsWork / CheckOrder 兩條策略 thread。

最重要入口檔

maintest/mkk_system_test.cc真正 main function。改想跑邊個 strategy，先睇呢度。

trading/mmk_manager.ccInit / Start / RegisterStrategy，系統 orchestration。

strategy/multi_fut_spot_arb_strategy_update.cc當前主要策略。

3. 行情流與訂單流

Market Data Flow

Bybit public WS
  -> bybit_md.cc parses book / ticker
  -> MarketDataManager::OnQuote()
  -> Strategy::OnQuote(PriceDepth)
  -> quote queue
  -> TradingPairsWork()

行情唔應該直接喺 websocket callback 入面做重計算；策略用 queue 將 I/O 路徑同計算路徑分開，減低阻塞。

Order Lifecycle

Strategy::SendOrder()
  -> TradeManager::SendOrder()
  -> BybitWssTradeApi::SendOrder()
  -> Bybit ACK / private update
  -> TradeManager::OnOrder()
  -> OrderManager async write
  -> Strategy::OnOrder()

本地狀態、交易所回報、LMDB 持久化要一致。任何改單、撤單、成交解析改動，都要同時考慮三者。

持久化點樣分工

MongoDB：偏配置與歷史資料，特別係 Instruments、StrategyParameter、Orders。
LMDB：偏低延遲本地狀態，保存 order / position，用於重啟 recovery。
XML：config/mmk_config.xml 提供 provider、MongoDB URL、LMDB path、Bybit key 等啟動配置。此檔可能有 secret，不應提交或展示內容。

4. Algo 原理：MultiFutSpotArbStrategy_Update

核心想法係同時觀察現貨與永續合約。當兩邊價格差扣除 fee、目標 profit、depth impact 後仍有空間，就掛 maker order；如果價格移走，CheckOrder() 會推動 amend。

A接收 quoteOnQuote() 更新 latest book，再推入 quote queue。

B計算可交易價格用 depth in USD 估算加權平均，避免只睇 best bid/ask 被薄盤誤導。

C扣成本和目標利潤考慮 maker / taker cost、Bid_Aim_Profit、Ask_Aim_Profit。

D決定下單/不下單檢查 Max_Position、N_Split、position threshold。

E監控與改單CheckOrder() 持續比較目標價與現有 order price。

F成交後更新狀態OnOrder() 更新策略內部 order / position，並交由 OrderManager persist。

核心參數

參數	用途	改動風險
`Trading_Pairs_ID`	一組 spot/swap pair 的策略識別。	中，影響 map key 與 recovery。
`Spot_Symbol` / `Swap_Symbol`	現貨與永續合約 symbol。	高，需對齊 Instruments 與 Bybit category。
`Max_Position`	最大 exposure。	高，風控核心。
`N_Split`	拆單數量。	中，影響 order size 與掛單頻率。
`Depth_In_USD`	計算 depth weighted price 的深度。	中，影響信號穩定性。
`Bid_Aim_Profit` / `Ask_Aim_Profit`	開單需要嘅目標利潤。	高，直接控制交易頻率與 edge。

5. 想入手修改，應該先睇邊度

改策略邏輯

strategy/multi_fut_spot_arb_strategy_update.cc
strategy/multi_fut_spot_arb_strategy_update.h
strategy/parameter.h

先加 metric/log，再改信號；唔好一開始就改 trade connector。

改交易所對接

connectivity/bybit/bybit_wss_trade.cc
connectivity/bybit/bybit_rest_trade.cc
connectivity/bybit/bybit_md.cc
connectivity/msgtype/msgtype.h

任何 order status parsing 改動都要保守，特別係 amend fail、partial fill、cancel reject。

改持久化 / recovery

trading/order_manager.cc
db/lmdb/*
db/mongodb/*

重啟後狀態一致性係交易系統生命線。改呢層要先設計 rollback/reconcile。

改 build / 測試入口

CMakeLists.txt
maintest/CMakeLists.txt
maintest/bybit_md_test.cc
maintest/bybit_td_test.cc

目前主要 target 係 mkk_system_test，其他 test target 有部分被註解。

6. Build / Run / Test 注意事項

cd git/MMK/MMKTradingSystem
mkdir -p build
cd build
cmake ..
make

# 注意：server 版 run_mkk_system_test.sh 使用 /home/cloud-user/... path
# 本地 sandbox 建議另寫 local run script，不要直接打 production config。

CMakeLists.txt 依賴 /opt/out-lib，包括 Boost、OpenSSL、glog、gtest、libwebsockets、LMDB、Mongo C driver 等。
config/mmk_config.xml 係本地私有配置，可能含 API key、private key、MongoDB URL。
如果只想睇行情，先由 market data test / orderbook example 入手，唔好一開始跑完整 trading strategy。
如果要試下單路徑，先加 dry-run adapter 或 mock provider，確認 order payload、state transition、persist 行為。

7. 安全試驗建議

永遠先隔離 config使用 testnet / read-only key / local MongoDB，避免連到 production DB 或真倉 key。

先做 market-data-only驗證 websocket、orderbook rebuild、quote queue，再逐步接 strategy。

加 dry-run trade layerTradeManager 前或 Bybit adapter 內加開關，只 log order，不送 API。

保存 snapshot每次實驗前記錄 config、MongoDB dump、LMDB path、git diff。

異常先 haltsubmit/cancel/amend/recovery 失敗時應進入安全停機，不好假裝 flat。

一個改動一個假設先加觀測，再調參數，再改交易行為，避免同時改多層。