量化交易系统开发实录（一）：项目启动与架构设计的五个关键决策

读者可以把这一篇作为整个系列的系统入口：先看清量化交易桌面系统的边界、数据语义、交易时段归属、回测实盘接口和 AI 协作边界，再进入后续文章中的缺陷、测试、性能、重构和 AI 工程化。

这不是一篇“如何快速写策略”的入门教程。真正需要先解决的问题是：行情数据从哪里进入，交易时间语义由谁负责，分层 K 线在哪里聚合，策略层能否同时用于回测和实盘，AI 生成的代码如何被架构边界约束。只有这些问题先回答清楚，后面所有具体实现才不会变成局部补丁。

适合谁读

量化交易系统的早期风险，往往不是“缺少某个工具”，而是过早把所有问题都交给策略代码解决。行情治理、交易时段、指标计算、信号判断、回测输入、实盘反馈和界面刷新一旦混在一起，系统短期看起来灵活，长期会变得难以解释、难以复现，也难以维护。

本文关注的是这些问题背后的工程判断：数据语义是否应该集中管理，策略是否只消费稳定结果，职责边界是否会因为实现方便而被合并，接口设计是否能够同时支撑回测和实盘。

因此，这篇文章不会从技术栈清单开始，而是从系统边界开始。后续关于缺陷复盘、测试策略、性能治理、架构重构和 AI 工程化的讨论，都会建立在同一条主线上：先让边界稳定，再让实现演进。

系列阅读顺序

推荐按 Part1 -> Part2 -> Part3 -> Part4 -> Part5 -> Part6 -> Part7 阅读。Part1 建立系统边界，Part2 和 Part3 暴露真实 Python 工程缺陷库，Part4 把缺陷转成测试防线，Part5 处理性能治理，Part6 复盘架构演进，Part7 最后讨论 AI 工程化如何增强整个闭环。

这条阅读顺序不是文章编号的简单排列，而是读者认知负担的递进。先看系统边界，才能理解为什么某些 Python 小问题会在交易系统里放大；先看真实缺陷，测试篇才不会变成抽象测试金字塔；先有测试和性能证据，重构篇里的边界移动才有依据；最后再看 AI 工程化，才能判断哪些工作可以交给 AI，哪些决策必须留在人手里。

如果读者只想快速判断本系列是否适合自己，可以先读这一篇的系统全景图和 Part6 的架构演进图。如果读者正在修某个具体 bug，可以先在 Part2 与 Part3 中按风险族群回查；但回查之后仍建议回到 Part1，确认这个 bug 属于数据接入、领域模型、策略层、执行层、回测层还是展示层。

系统入口：先定义边界，再讨论实现

Micang Trader 可以被理解为一个模块化可扩展的分层信号研判实时量化交易系统。基于 vn.py 定制开发，继承了 vn.py 模块化架构优势，可以接入多个市场数据，同时可按需对特定交易市场的数据处理流程做深度定制，并通过桌面 UI 展示行情、指标、策略状态和运行结果。

项目启动时常见的工程风险之一，是过早把“先让策略跑起来”当成系统设计的替代品。短期看，策略代码确实能很快形成反馈；但如果数据接入、周期转换、交易时段归属、指标计算、图表渲染和订单执行缺少清晰边界，它们就容易逐渐挤到同一个类或同一条调用链里。等回测结果和实盘行为不一致时，问题定位会变得困难：到底是数据、指标、策略、执行还是 UI 造成了偏差，往往已经很难快速判断。

更稳妥的启动方式，是先把系统拆成几个可推理的边界：

• 行情入口只负责接收外部数据，不决定交易日语义。
• 交易时段模型负责把物理时间映射为交易日、日盘、夜盘和强制收盘点。
• 分层聚合服务负责从低周期数据生成高周期事件，并保证聚合逻辑唯一。
• 策略核心只消费稳定事件和指标视图，不反向查询 GUI 或数据库。
• 执行层负责订单、撮合、网关和真实交易差异，不污染策略接口。
• 回测适配器和实盘适配器都转换为同一套事件协议。
• 桌面监控只呈现状态、行情和诊断结果，不拥有数据语义。

这张系统全景图回答的是“哪些模块不能直接互相耦合，它们必须如何通过事件引擎和事件契约协作”。在单进程事件驱动架构里，行情入口、数据治理、K 线处理、策略、风控执行、回测和桌面监控不应该互相读取内部状态，而应该通过 vn.py 事件引擎发布和订阅标准事件。否则，策略层一旦直接读数据库、直接控制 UI、直接判断自然日切分，任何业务规则变化都会穿透多个模块。比如夜盘规则变化会影响 K 线生成，K 线生成又会影响指标，指标再影响信号，信号最终影响订单。边界不清时，这条链路上的任何修复都可能制造新的不一致；事件引擎的价值，就是把这些变化约束在稳定的事件契约里。

因此，架构设计的第一步不是选择更多工具，而是先明确系统边界。交易接入、数据治理、策略判断、执行反馈、回测验证和界面展示应当各自承担清晰职责。工具只是实现手段，真正决定系统可维护性的，是业务语义是否稳定、数据质量是否可信，以及模块之间的边界是否足够清楚。

决策一：vn.py 不是黑盒，数据语义必须外移

如果你正在用 vn.py 开发交易系统，最大风险通常不在框架本身，而在“把所有事情都写进 CtaTemplate”。一开始这样做很快，但项目一变大，策略类会同时承担太多职责：读数据、修数据、判交易日、算信号、下指令。代码能跑，但很难测，也很难定位问题。

你可以用一个简单标准判断：策略类到底在“做交易判断”，还是在“兼任数据工程”。如果策略里充满数据查询、数据修复、时间归属判断，那么后续每次改规则都会牵一发而动全身。

更稳妥的边界是：vn.py 继续负责事件与交易接口，数据规则由独立数据服务集中管理。策略只读取稳定输入并做买卖判断，不直接处理底层数据细节。

# 示意代码，非实际生产代码
# 不推荐：策略里直接处理数据细节
class BadStrategy(CtaTemplate):
    def on_tick(self, tick: TickData):
        rows = self.db.load_recent_ticks(tick.vt_symbol, limit=500)
        clean_rows = fill_missing_values(rows)
        trading_day = resolve_trading_day(tick.datetime)
        signal = calc_signal(clean_rows, trading_day)
        if signal == "buy":
            self.buy(tick.ask_price_1, 1)

# 推荐：数据服务只提供一致数据视图，信号由策略计算
data_service = MarketDataService(symbol="HSI")

class GoodStrategy(CtaTemplate):
    def __init__(self, data_service: MarketDataService):
        super().__init__()
        self.data_service = data_service

    def on_bar(self, bar: BarData):
        view = self.data_service.get_view(bar.vt_symbol)
        if not view.ready:
            return

        signal = calc_signal(view.indicators, view.trading_day)
        if signal == "buy":
            self.buy(bar.close_price, 1)

strategy = GoodStrategy(data_service)

这里要特别强调：一致视图只负责“同一时点输入一致”，不负责“输出交易信号”；信号始终由策略层按业务规则计算。这样做的代价是前期要多做一层基础设施；收益也很直接：第一，策略代码更短、更像业务规则；第二，数据规则只维护一份，不会在不同策略里各改一版；第三，测试可以先测数据服务，再测策略判断，问题定位更快。

你可以用三个信号检查项目是否开始失控：策略类里是否直接写 SQL 或文件读取；策略类是否自己处理交易日和时间归属；同一套数据清洗逻辑是否在多个策略里重复出现。出现这些信号时，优先做边界拆分，通常比继续加参数更有效。

决策二：数据是基石，聚合规则必须按商业软件标准建设

量化交易系统的上层能力最终都依赖数据质量。策略、指标、回测、风控和图表展示看起来属于不同模块，但它们共同依赖同一件事：系统是否能稳定、可解释、可审计地处理行情数据。如果数据入口、交易日历、交易时段、缺失值、聚合窗口和异常修复规则没有先被定义清楚，后面的策略优化很容易变成在错误数据上做精细计算。

这里最容易被低估的是“数据聚合规则”的工程标准。它不应该只是一个 resample 调用，也不应该散落在策略、图表和回测脚本里。商业软件级别的实现必须明确回答几个问题：不同交易市场的交易日历如何维护，日盘、夜盘、半日市、节假日和临时休市如何处理，窗口边界如何关闭，缺失行情如何标记，异常 tick 如何过滤，补齐数据是否允许进入实盘链路，以及所有规则如何被测试和审计。

如果这些规则只靠经验写在策略里，系统短期看起来可以运行，长期一定会产生隐性分叉。某个策略自己生成 30 分钟 K 线，另一个图表组件直接读取 1 小时 K 线，回测脚本再使用另一套 Pandas 逻辑生成历史数据。三套结果都可能“看起来合理”，但只要交易时段、窗口归属或缺失值策略稍有差异，指标和信号就会在边界位置悄悄漂移。

# 示意代码，非实际生产代码
# 错误：数据聚合规则散落在策略、图表和回测脚本里
strategy_30m = strategy.aggregate_30m(min_bars)
chart_1h = chart.load_hour_bars(symbol)
backtest_daily = history.resample("1D")

# 推荐：交易日历、交易时段和聚合规则由数据服务统一签收
data_service = MarketDataService(
    calendar=ExchangeCalendar("HKFE"),
    session_model=TradingSessionModel("HKFE"),
    aggregation_policy=AggregationPolicy(
        window_boundary="left-closed-right-open",
        missing_value="mark_and_skip",
        outlier_filter="exchange_rule",
    ),
)
stable_bar = data_service.publish_stable_bar(raw_tick)

更可靠的做法是把数据处理当成系统基础设施，而不是策略辅助函数。原始行情进入系统后，先经过统一的数据清洗、交易日历、交易时段、窗口归属和聚合规则，再输出稳定的数据事件。策略层不应该关心这些数据是如何补齐、如何聚合、如何处理特殊交易日的；它只应该消费已经通过数据服务签收的稳定结果。

这张图回答的是“数据规则里最容易出错的时间归属问题”。策略真正需要的不是原始时间戳，而是已经签收的业务语义：timestamp + trading_day + session_phase + force_close_at。timestamp 负责事实记录，trading_day 负责业务归属，session_phase 负责时段语义，force_close_at 负责风险边界。先把这层语义固定住，后续指标和信号才不会被自然日切分悄悄污染。

这项投入在早期会显得“慢”，因为它需要更多基础设施代码、更多测试用例和更多边界规则。但这正是量化交易系统最值得投入的地方。数据层越可靠，策略层越简单；聚合规则越集中，回测和实盘越容易保持一致；交易市场规则越明确，未来支持更多品种、更多市场和更多交易时段时，系统越不容易失控。

决策三：充分利用事件引擎，让业务严格按事件驱动

vn.py 的核心价值之一是事件引擎。真正可维护的量化系统，不应该让模块之间互相直接调用、互相查询状态、互相拼接数据，而应该让业务围绕事件流转。行情到达、K 线生成、订单发出、成交回报、持仓变化、风控触发、UI 更新，都应该通过明确的事件进入系统，而不是通过隐式共享状态完成协作。

事件驱动的意义不只是“把消息发出去”，而是让系统边界更清楚。数据服务只负责发布稳定行情事件，策略引擎只订阅自己需要的市场事件，风控模块只关心订单和持仓事件，执行模块只处理交易指令和回报事件，UI 只订阅展示所需的状态更新。每个模块都高内聚，只处理自己的职责；模块之间通过事件协议协作，避免直接依赖彼此内部实现。

如果系统没有充分利用事件引擎，很容易退化成强耦合结构。策略直接查数据库，图表直接调用数据聚合函数，风控直接读取策略内部变量，执行模块反向修改策略状态。短期看代码少，长期看每次改动都会牵动多个模块，问题也很难定位：一次信号异常到底是数据问题、策略问题、风控问题，还是 UI 刷新问题，很难沿着清晰链路回查。

# 示意代码，非实际生产代码
# 推荐：业务模块通过事件协议协作，而不是直接互相调用内部状态
event_engine.register(EventType.STABLE_BAR, strategy_engine.on_bar)
event_engine.register(EventType.SIGNAL, risk_engine.on_signal)
event_engine.register(EventType.ORDER_REQUEST, execution_engine.on_order_request)
event_engine.register(EventType.TRADE, portfolio_engine.on_trade)

event_engine.put(EventType.STABLE_BAR, stable_bar_event)

更稳妥的结构是：基础数据服务发布行情事件，聚合服务发布稳定 K 线事件，策略引擎消费市场事件并发布信号事件，风控模块消费信号和账户事件并发布可执行指令，交易适配器负责把指令转换为具体网关调用，再把订单和成交回报重新发布为事件。业务只能沿事件流向前推进，不能绕过事件引擎直接修改其他模块状态。

这张图回答的是“事件驱动下业务怎样向前推进”。行情事件进入数据服务后，先形成一致数据视图，再进入策略判断；策略输出信号，风控输出可执行指令，执行层输出委托与成交回报，监控层只订阅状态变化。重点不是模块之间谁先调用谁，而是所有协作都必须经过事件契约。

这个原则会让系统更容易测试和扩展。测试时可以直接构造事件输入，验证模块输出事件是否正确；排查问题时可以沿事件链路追踪每一步；新增策略、风控规则或 UI 展示时，也只需要订阅稳定事件，而不是侵入已有模块。对一个长期维护的交易系统来说，事件驱动不是风格选择，而是保持松耦合、高内聚和可审计性的基础约束。

决策四：回测与实盘必须共享策略事件协议

量化系统最大的维护负担之一，是回测和实盘逻辑分叉。典型症状包括：回测通过了，实盘跑不通；实盘出现的问题，回测复现不了；同一套策略在回测和实盘中使用不同指标实现；回测参数和实盘参数在两个配置入口里逐渐偏离。

根因通常不是某个函数写错，而是数据流模型不同。回测经常是拉模型：策略主动遍历历史数据；实盘通常是推模型：交易所或网关推送 Tick、Bar、订单和成交事件。如果策略代码分别适配这两种模型，就会出现两套状态机。等系统变大后，读者很难判断某个策略表现差异来自市场环境，还是来自回测和实盘代码路径不同。

更可靠的抽象是统一事件流。回测引擎把历史数据转换为事件流，实盘引擎把实时数据转换为事件流，策略层只实现同一个 on_market_event(event) 或 on_bar(event) 接口。回测和实盘差异留在适配器里，而不是进入策略核心。

# 示意代码，非实际生产代码
class UnifiedStrategy:
    def on_bar(self, event: BarEvent):
        # 不管事件来自回测还是实盘，策略都只面对统一协议
        pass

backtest_engine = BacktestEngine(strategy)
backtest_engine.run(historical_events)

live_engine = LiveEngine(strategy)
live_engine.run(live_event_feed)

这张图回答的是“怎样避免同一套策略写两遍”。历史事件流和实盘事件流都进入 UnifiedStrategy，策略输出再分别交给模拟撮合或真实委托。策略层不需要知道自己处在回测还是实盘，只需要响应标准化后的市场事件、订单事件和状态事件。

统一事件协议还会影响指标实现。早期很多系统喜欢在回测中使用 Pandas 向量化计算，在实盘中使用循环增量计算。这样做可以让回测写起来更快，但可能造成浮点精度、窗口闭合、缺失数据和初始化状态不一致。更稳妥的原则是：回测可以用批量输入驱动事件流，但策略和指标计算应尽量共享同一套核心实现。即使回测慢一点，也比两套逻辑长期漂移更安全。

决策五：AI 可以加速实现，但不能替代架构签收

AI coding 工具很适合生成样板代码、补测试草稿、解释复杂函数、提取重复逻辑和做局部重构。对量化交易系统来说，这些能力很有价值，因为系统里存在大量数据类、配置解析、事件转换、日志记录、边界测试和重复性胶水代码。

但 AI 不应该直接承担架构决策。它不知道某个交易时段规则为什么重要，也不知道某个指标偏差在实盘中会造成什么后果。它可能给出看起来通用的订单状态管理方案，却忽略交易所回报差异；也可能给出简洁的 Pandas 实现，却忽略实时链路的延迟和内存压力；还可能把代码拆得很漂亮，却没有给出回测实盘一致性的证据。

更合适的人机协作方式，是先由人定义架构边界、接口契约和验收证据，再让 AI 在边界内生成候选实现。例如，不要问“怎么做订单回报处理”，而是给出清晰约束：“基于 vn.py 的 OrderData 和 TradeData，实现 OrderStateTracker；状态转移只允许 SUBMITTING -> NOTTRADED -> PARTTRADED -> ALLTRADED/CANCELLED/REJECTED；必须幂等处理重复回报；必须在网络抖动后通过回报重放恢复一致；必须输出带 order_id、source_ts、state_version 的事件；必须有断网重连、重复回报和乱序回报测试。”

这种提示方式的重点不是让 AI 少发挥，而是把自由度放在实现细节上，把系统语义留在接口和测试里。AI 可以生成 OrderStateTracker 的初稿，可以补充参数校验和边界测试，也可以重构重复代码；但它不能替代人判断“状态流转是否符合交易规则”“回测和实盘是否真的共用同一套协议”“性能优化是否改变了委托与回报的时序语义”。

K 线压缩是另一个典型例子。面对历史 K 线存储体积压缩 80% 的目标，AI 很可能优先推荐代码最简洁的 Pandas DataFrame 压缩方案。这个方案在离线分析里也许足够，但交易终端还要考虑读取速度、随机访问、内存占用、跨进程复用和回放延迟。最终是否选择自定义二进制格式、NumPy 数组、内存映射或其它方案，需要结合实际 I/O 模式和 benchmark，而不是只看代码短不短。

因此，AI 辅助开发在本系列中的定位很清楚：AI 负责候选实现，人负责架构边界、业务语义、风险判断和最终签收。Part7 会继续展开规格驱动、敏捷交付流程、人机质量门禁和证据闭环；在 Part1 里，读者只需要先记住一个原则：越是 AI 能快速生成代码，越需要先把不可让步的边界写清楚。

测试策略：先保护语义，再扩展实现

量化系统的测试不能只问“策略是否赚钱”。收益结果受市场环境、参数选择、手续费、滑点、样本区间和执行质量影响，不能直接等同于代码正确性。更基础的问题是：数据转换是否正确，交易日归属是否正确，高周期聚合是否正确，指标状态是否正确，回测和实盘是否走同一套事件协议。

测试可以按四层理解。第一层是单元测试，覆盖数据转换、交易时段归属、指标计算和工具函数，这些逻辑的输入输出确定，应该尽量明确断言。第二层是集成测试，覆盖从原始数据到策略信号、从信号到订单、从网络异常到降级恢复的关键路径。第三层是回测验证，用历史数据验证信号触发点、窗口归属和指标结果是否符合预期。第四层是模拟盘或沙箱运行，验证长时间运行下数据不丢、订单不乱、日志完整、异常可追踪。

跨交易日数据归一是一个值得优先测试的例子。假设周五夜盘持续到周六凌晨，周一早盘重新开盘，30 分钟线的起始时间不应该被自然日切分污染。测试不只是验证 PeriodAggregator 能生成结果，而是验证它在交易时段模型约束下生成正确窗口。

# 测试用例：跨交易日数据归一（示意代码，非实际生产代码）
def test_cross_day_aggregation():
    friday_night = create_bars("2024-01-05 23:00", "2024-01-06 03:00")
    monday_morning = create_bars("2024-01-08 09:15", "2024-01-08 10:00")

    aggregator = PeriodAggregator(period="30m")
    for bar in friday_night + monday_morning:
        result = aggregator.update(bar)
        if result:
            assert result.start_time == "2024-01-08 09:15"

这个测试背后的架构意义，比代码本身更重要。它说明交易时段模型必须先于聚合逻辑存在，聚合逻辑必须能被独立调用，测试必须能绕开 GUI 和真实网关。如果一个系统无法写出这种测试，通常说明它的领域边界还没有拆出来。

启动前 checklist：五个问题必须有明确答案

项目启动前，读者可以直接用下面五个问题检查架构是否足够清晰。

1. 数据层是否独立？

• 数据采集、存储、聚合和服务是否分模块。
• 策略是否只通过标准接口获取事件和指标。
• 更换数据源是否不需要修改策略核心。

2. 分层如何管理？

• 周期转换逻辑是否集中在一处。
• 不同周期的数据是否由统一时段模型归一。
• 新增周期是否不需要复制策略内聚合逻辑。

3. 回测和实盘是否统一？

• 策略代码在回测和实盘中是否共享同一套核心接口。
• 回测引擎是否模拟延迟、滑点和撮合等关键实盘差异。
• 实盘问题是否能通过事件回放在回测或测试环境中复现。

4. AI 辅助的边界在哪里？

• 哪些代码可以交给 AI 生成候选实现。
• 哪些接口、交易语义和风险判断必须人工签收。
• AI 生成代码是否必须经过测试、review 和 benchmark 证据。

5. 测试策略是什么？

• 单元测试覆盖哪些确定性领域逻辑。
• 集成测试覆盖哪些关键数据流和异常流。
• 回测验证使用哪些历史区间和手工参考结果。
• 模拟盘或沙箱运行需要持续多久才能进入下一阶段。

这份 checklist 的价值，是把项目启动从“先写起来看看”变成“先把不可逆风险降下来”。量化交易系统很少因为缺少一个工具而失败，更常见的失败原因是数据语义、时间语义、策略接口和测试证据在早期没有被固定下来。

总结：架构是为了让人脑能管理复杂度

AI 时代容易产生一个危险错觉：既然代码生成更快，前期架构就可以更随意。量化交易系统恰好相反。代码越容易被快速生成，越需要先定义清楚哪些边界不能被随意穿透。

清晰的架构并不是为了让目录结构看起来高级，而是为了让读者在真实问题出现时能快速定位：这是数据接入问题、交易时段问题、分层聚合问题、策略事件协议问题、执行适配问题，还是 UI 展示问题。定位越快，修复越不容易引入新的不一致。

后续文章会沿着这条主线展开。Part2 和 Part3 会把 Python 工程风险按真实 bugfix 归类；Part4 会把缺陷转化为测试防线；Part5 会讨论性能侦查、benchmark 和优化回退；Part6 会复盘架构演进、技术债务和 ADR；Part7 会讨论 AI 工程化如何把规格、实现、评审和验收组织成闭环。

如果读者只记住一个启动原则，那就是：交易系统不要从策略代码开始，而要从边界开始。先让数据语义、时间语义、事件协议和验证证据变得稳定，再让策略在这些稳定边界内演进。

参考资源

• vn.py 官方文档：https://www.vnpy.com
• 项目使用的 AI 开发流程：speckit（规格驱动开发）
• 项目使用的敏捷交付流程：BMAD（Breakthrough Method for Agile AI Driven Development）