模組 02：整體架構鳥瞰圖在開始細節之前，先看清整個系統的全貌

flowchart LR
subgraph external_world["外部世界"]
exchange["交易所"]
data_provider["數據源"]
end

subgraph nautilus["NautilusTrader"]
direction TB
adapter_in["數據適配器"]
adapter_out["執行適配器"]
data_engine["數據引擎"]
exec_engine["執行引擎"]
risk_engine["風控引擎"]
cache["緩存"]
msgbus["消息總線"]
strategy["你的策略"]
portfolio["投資組合"]
end

external_world --> data_provider
external_world --> exchange
data_provider --> adapter_in
exchange --> adapter_in
adapter_in --> data_engine
data_engine --> msgbus
msgbus --> strategy
strategy --> msgbus
msgbus --> risk_engine
risk_engine --> exec_engine
exec_engine --> adapter_out
adapter_out --> exchange
exchange --> adapter_out
adapter_out --> exec_engine
exec_engine --> portfolio
data_engine --> cache
exec_engine --> cache
strategy -.-> cache

flowchart LR
            subgraph kernel["🧠 NautilusKernel — 系統內核大腦"]
            direction TB
            msgbus["📡 MessageBus<br/>消息總線"]
            cache["💾 Cache<br/>緩存"]
            msgbus --- cache
            end

            subgraph engines["⚙️ 核心引擎組"]
            direction TB
            data["📊 DataEngine<br/>數據引擎"]
            exec["⚙️ ExecutionEngine<br/>執行引擎"]
            risk["🛡️ RiskEngine<br/>風控引擎"]
            data --- exec --- risk
            end

            subgraph management["💰 資金與策略"]
            direction TB
            port["💰 Portfolio<br/>投資組合"]
            strat["🧩 Strategy<br/>你的策略"]
            port --- strat
            end

            kernel --> engines
            engines --> management

            style kernel fill:#0f1419,stroke:#4fc3f7,stroke-width:2px
            style engines fill:#0f1419,stroke:#ffa726,stroke-width:1px
            style management fill:#0f1419,stroke:#ab47bc,stroke-width:1px

flowchart TB
            subgraph common["🔄 通用核心 (NautilusKernel)"]
            kernel["MessageBus + Cache + DataEngine<br/>+ ExecutionEngine + RiskEngine + Portfolio"]
            end

            subgraph bt["📊 回測環境 (Backtest)"]
            bt_data["歷史數據文件"]
            bt_venue["模擬交易所<br/>SimulatedExchange"]
            end

            subgraph sb["🏖️ 沙箱環境 (Sandbox)"]
            sb_data["即時市場數據"]
            sb_venue["模擬交易所<br/>SimulatedExchange"]
            end

            subgraph lv["🔴 實盤環境 (Live)"]
            lv_data["即時市場數據"]
            lv_venue["真實交易所<br/>Live Exchange"]
            end

            bt --> common
            sb --> common
            lv --> common

flowchart LR
            subgraph python_pkg["📦 Python / Cython 層<br/>(nautilus_trader/)"]
            direction TB
            p_logic["交易策略與指標<br/>(trading/ / indicators/)"]
            p_model["領域模型封裝<br/>(model/)"]
            p_engine["引擎介面與配置<br/>(core/ / data/ / exec/)"]
            p_logic --- p_model --- p_engine
            end

            subgraph bridge["🔗 橋接層<br/>(Cython + PyO3)"]
            direction TB
            ffi["C FFI 介面"]
            binding["Python 綁定"]
            ffi --> binding
            binding --> ffi
            end

              subgraph rust_pkg["🦀 Rust 核心層<br/>(crates/)"]
              direction TB
              r_engines["核心引擎組件<br/>(data / execution / risk)"]
              r_base["基礎設施與內核<br/>(core / model / common)"]
              r_infra["底層服務<br/>(network / persistence)"]
              r_engines --- r_base --- r_infra
              end

              python_pkg --> bridge
              bridge --> python_pkg
              bridge --> rust_pkg
              rust_pkg --> bridge

                  style bridge fill:#1a1f2e,stroke:#ab47bc,stroke-width:2px
                  style python_pkg fill:#0f1419,stroke:#4fc3f7,stroke-width:1px
                  style rust_pkg fill:#0f1419,stroke:#ef5350,stroke-width:1px

flowchart LR
            subgraph layer_found["🧱 基礎層"]
            direction TB
            core["core"]
            model["model"]
            common["common"]
            model --> core
            common --> model
            end

            subgraph layer_infra["🏗️ 基建與引擎"]
            direction TB
            serialization["serialization"]
            persistence["persistence"]
            data["data"]
            execution["execution"]
            risk["risk"]
            portfolio["portfolio"]
            serialization --> model
            persistence --> serialization
            data --> common
            execution --> common
            risk --> portfolio
            portfolio --> common
            end

            subgraph layer_runtime["🚀 運行與擴展"]
            direction TB
            system["system"]
            trading["trading"]
            backtest["backtest"]
            live["live"]
            adapters["adapters"]
            pyo3["pyo3"]
            backtest --> system
            live --> system
            live --> trading
            adapters --> live
            pyo3 --> adapters
            end

            layer_found --> layer_infra
            layer_infra --> layer_runtime

            style layer_found fill:#0f1419,stroke:#4fc3f7,stroke-width:1px
            style layer_infra fill:#0f1419,stroke:#ffa726,stroke-width:1px
            style layer_runtime fill:#0f1419,stroke:#ef5350,stroke-width:1px

sequenceDiagram
            participant Exchange as 🏦 交易所
            participant DC as 📡 DataClient
            participant DE as 📊 DataEngine
            participant Cache as 💾 Cache
            participant MB as 📡 MessageBus
            participant Strategy as 🎯 你的策略

            Exchange->>DC: WebSocket 推送原始報價
            DC->>DC: 轉換為標準格式 (QuoteTick)
            DC->>DE: 傳入標準化數據
            DE->>Cache: 存入緩存
            DE->>MB: 發布數據事件
            MB->>Strategy: 推送給訂閱了該品種的策略
            Strategy->>Strategy: 執行策略邏輯
            Note over Strategy: 決定是否下單

sequenceDiagram
            participant Strategy as 🎯 你的策略
            participant MB as 📡 MessageBus
            participant Risk as 🛡️ RiskEngine
            participant EE as ⚙️ ExecutionEngine
            participant EC as 🔌 ExecutionClient
            participant Exchange as 🏦 交易所
            participant Portfolio as 💰 Portfolio
            participant Cache as 💾 Cache

            Strategy->>MB: 發送下單命令 (SubmitOrder)
            MB->>Risk: 風控檢查
            Risk->>Risk: 驗證風險限制
            alt 風控通過
            Risk->>EE: 轉發命令
            EE->>EC: 路由到對應交易所
            EC->>Exchange: 提交訂單 (REST/WS)
            Exchange-->>EC: 訂單確認
            EC->>EE: 回報 OrderAccepted 事件
            EE->>Cache: 更新訂單狀態
            EE->>MB: 發布事件
            Exchange-->>EC: 成交回報
            EC->>EE: 回報 OrderFilled 事件
            EE->>Portfolio: 更新持倉和盈虧
            EE->>Cache: 更新狀態
            EE->>MB: 發布事件
            MB->>Strategy: 通知成交
            else 風控拒絕
            Risk->>MB: 發布 OrderDenied 事件
            MB->>Strategy: 通知被拒絕
            end

flowchart TB
            A["1️⃣ 系統啟動<br/>NautilusKernel 初始化所有組件"] --> B["2️⃣ 連接數據源<br/>DataClient 連接交易所 WebSocket"]
            B --> C["3️⃣ 訂閱數據<br/>策略告訴 DataEngine 它需要哪些數據"]
            C --> D["4️⃣ 接收行情<br/>數據到達策略的 on_quote_tick / on_bar 回調"]
            D --> E["5️⃣ 策略決策<br/>策略分析數據、計算指標、生成信號"]
            E --> F{"6️⃣ 是否下單？"}
            F -->|"是"| G["7️⃣ 風控檢查<br/>RiskEngine 驗證訂單"]
            F -->|"否"| D
            G --> H["8️⃣ 執行訂單<br/>ExecutionEngine 透過適配器下單"]
            H --> I["9️⃣ 更新狀態<br/>Cache + Portfolio 更新"]
            I --> D