12. Live Trading S1.3 Design Philosophy and Architecture

This article explains, from a design perspective, the live trading refactor approach for S1.3: why the layering is done this way, how compatibility is maintained, and how these designs help with future extensions.

12.1. 0. 文档定位

  • This document is a design specification, not a user tutorial.

  • It focuses on answering “why we do it this way”, rather than “how to operate step by step”

  • If you need a hands-on path, please go to live_trading/2-configuration-and-run.md and tutorials/8-live-trade-risk-and-broker-walkthrough.md

12.2. 1. 设计目标

  • Without breaking existing user flows, improve the verifiability and auditability of the live path

  • Move risk control forward to “before placing orders and writing to the database”

  • Abstract the Broker adapter layer to reserve a stable boundary for future integration with real broker front ends

12.3. 2. 分层结构

The live-related responsibilities of S1.3 can be abstracted as:

  • Operator: strategy execution scheduling and signal source

  • Trader: materialize order intent, risk gating, and execution coordination

  • RiskManager: pure logical rule evaluation, no IO dependencies

  • Broker: submit, cancel, report, and connection semantics

  • trade_io: contract validation for order/trade data

12.4. 3. 关键设计原则

3.1 Contract-first

Validate the order dict and fill dict at the boundary to avoid silent errors caused by “it still runs even when the structure is wrong”.

3.2 Shift risk controls left

Risk assessment is completed before writing to the database and enqueueing, so rejected orders do not contaminate execution data.

3.3 Adapter decoupling

Carry future integrations via the broker adapter API to reduce coupling between Trader and specific broker systems.

3.4 Auditable

Rejection reasons are externally visible via rule_id and an English reason, supporting ops search and post-incident review.

12.5. 4. 典型疑难点与取舍

4.1 Rejection-order compatibility semantics

Maintain backward compatibility (rejections can appear as empty results) while improving visibility (CLI/TUI summary + logs).

4.2 Coexistence of new and legacy flows

Keep the legacy queue compatibility path to avoid regression risk from a one-shot migration.

4.3 State consistency

In partial-fill scenarios, status should be based on the cumulative filled volume to reduce semantic discrepancies observed by users.

12.6. 5. 与 S2.1 的关系

S1.3 is not the end point of broker integration, but the foundational groundwork:

  • Stabilize the interface boundaries first

  • Then gradually connect to real broker systems.

  • Finally, extend capabilities without breaking upstream usage.

12.7. 6. 对用户行为的影响

  • Configuration errors are exposed earlier.

  • Rejection reasons are easier to pinpoint.

  • State changes during live operation are easier to explain.

  • The cost of extending third-party brokers is more controllable.

12.8. 7. 相关阅读

  • Module overview: live_trading/1-overview.md

  • Operation and configuration: live_trading/2-configuration-and-run.md

  • Risk control and state: live_trading/3-risk-and-order-lifecycle.md

  • Broker integration: live_trading/4-broker-adapter-and-integration.md