系统架构设计方案 Codex 版
由 Codex 独立生成 · 务实轻量路线
一 · 系统分层与模块总览(6 层 14 模块)
L0
基础设施层
ConfigStore
Scheduler
EventBus
配置读写 / 定时调度 / 内部事件解耦(横切关注点)
L1
数据采集层
ExchangeAdapter
KlineCache
OHLCV K 线数据(内存热路径 + 磁盘全量历史)
L2
分析计算层
TrendModule
KeyLevelModule
趋势结果(TrendResult)+ 关键位列表(KeyLevelList)
L3
信号决策层
SignalModule
PlanModule
入场信号(Signal)+ 交易计划(TradePlan,含 RR 达标校验)
L4
执行与监控层
OrderExecutor
PositionMonitor
订单记录 + 实际出场价 + 盈亏结果
L5
输出层
ChartServer
Notifier
ReviewStore
二 · 模块职责边界
L0 基础设施层
| 模块 | 职责 | 边界 |
|---|---|---|
| ConfigStore | 持久化任务配置;提供 CRUD API;广播配置变更事件 | 只管配置读写,不执行分析 |
| Scheduler | 按交易对×周期订阅 K 线收盘;驱动 L1→L3 链路触发 | 只负责定时触发,不做业务判断 |
| EventBus | 内存内轻量事件总线:kline_closed / analysis_done / signal_fired / order_filled | 仅内存传递,不持久化事件 |
L1 数据采集层
| 模块 | 职责 | 边界 |
|---|---|---|
| ExchangeAdapter | 封装 CCXT;按任务配置拉取 OHLCV;统一为内部 Kline 结构;处理重试和限速 | 只负责网络 I/O,不做计算 |
| KlineCache | 按 (symbol, timeframe) 切片存储;内存热路径(近 2×window 根)+ 磁盘全量历史;增量合并去重;提供滑动窗口查询 | 只管存取,不调用交易所 |
L2 分析计算层
| 模块 | 职责 | 边界 |
|---|---|---|
| TrendModule | 读取趋势周期 K 线;运行配置算法(默认 EMA 三均线);输出 TrendResult;算法可插拔 | 不直接调用 ExchangeAdapter,不感知关键位 |
| KeyLevelModule | 扫描趋势+交易双周期 K 线;运行关键位算法(聚类/S-R Flip/价格密度);输出 KeyLevelList;算法可插拔 | 不感知趋势结果,两者并行运行 |
L3 信号决策层
| 模块 | 职责 | 边界 |
|---|---|---|
| SignalModule | 等 TrendResult + KeyLevelList 就绪;检测价格是否进入关键区间并出现反转形态(Pin Bar 等);输出 Signal | 只管形态识别,不做仓位计算 |
| PlanModule | 接收 Signal;计算入场/止损/止盈;RR 校验在此处(不在 SignalModule);达标则生成 TradePlan | 只在 Signal 存在时运行;不调用交易所 |
L4 执行与监控层
| 模块 | 职责 | 边界 |
|---|---|---|
| OrderExecutor | 读取 TradePlan;受 auto_trade 开关控制:False 时只推通知不下单;True 时发送订单;记录实际成交价 | 不修改 TradePlan |
| PositionMonitor | 持续轮询持仓;检测止损/止盈命中;发平仓指令;记录实际出场价和盈亏 | 只监控已开仓 symbol,不生成新信号 |
L5 输出层
| 模块 | 职责 | 边界 |
|---|---|---|
| ChartServer | 提供 HTTP API 输出交互式图表数据(K 线 + 均线 + 关键位填充矩形);支持算法方案切换 | 只读不写,不触发分析 |
| Notifier | 监听 EventBus 的 signal_fired / order_filled / position_closed;格式化后用 httpx POST Webhook 推送 Discord | 单向推送,无状态 |
| ReviewStore | 交易结束后归档 TradePlan + 实际执行记录;提供历史胜率/盈亏统计查询 | 只做归档和读取,不影响主链路 |
三 · 模块依赖关系图
Scheduler调度器
触发行情拉取
ExchangeAdapter行情接入
→
KlineCacheK 线缓存
数据就绪,触发分析
并行运行 · 互不依赖
TrendModule趋势分析
KeyLevelModule关键位识别
两者均就绪后合并
SignalModule信号检测
有信号 · Signal
PlanModule计划生成
RR 达标 · TradePlan
同时输出
OrderExecutor下单执行
auto_trade=True 时
Notifier通知推送
← EventBus · signal_fired
持仓追踪
PositionMonitor持仓监控
止盈 / 止损命中
平仓后
ReviewStore复盘归档
Notifier通知推送
← EventBus · position_closed
ChartServer图表服务
只读获取 KlineCache · TrendModule · KeyLevelModule 的数据,不参与主链路,不触发任何分析
- TrendModule 和 KeyLevelModule 并行运行,互不依赖;SignalModule 需等两者都就绪
- EventBus 作为异步解耦通道,Notifier 不直接引用上游模块
- ConfigStore 向所有模块提供配置,是唯一配置来源
四 · 核心数据结构(Python dataclass)
L0 · TaskConfig
@dataclass class TaskConfig: task_id: str; symbol: str # "BTC/USDT:USDT" trend_timeframe: str # "4h" entry_timeframe: str # "15m" window_size: int # K线窗口数 trend_algo: str; trend_params: dict # "ema_triple" | {"periods": [21,55,144]} keylevel_algo: str; keylevel_params: dict signal_direction: str # "long" | "short" | "both" signal_algo: str; signal_params: dict position_mode: str # "fixed" | "percent" position_value: float; min_rr_ratio: float exchange_id: str; api_key: str; api_secret: str auto_trade: bool; discord_webhook: str; enabled: bool
L2 · TrendResult & KeyLevel
@dataclass class TrendResult: task_id: str; symbol: str; timeframe: str direction: str # "bullish" | "bearish" | "sideways" strength: float # 预留字段,当前固定 1.0 ema_values: dict # {"ema21": 80200, "ema55": 79500, ...} computed_at: int # timestamp ms @dataclass class KeyLevel: center: float; upper: float; lower: float level_type: str # "support" | "resistance" | "flip" touch_count: int; score: float
L3 · Signal & TradePlan
@dataclass class Signal: task_id: str; symbol: str direction: str # "long" | "short" pattern: str # "pin_bar" | ... trigger_kline: Kline; triggered_level: KeyLevel fired_at: int @dataclass class TradePlan: plan_id: str; task_id: str; signal: Signal entry_price: float; stop_loss: float; take_profit: float rr_ratio: float; position_size: float; position_unit: str created_at: int status: str # "pending"|"active"|"closed"|"discarded"
L4 · Order & TradeResult
@dataclass class Order: order_id: str; plan_id: str; exchange_order_id: str side: str; price: float; size: float filled_price: float | None status: str # "open"|"filled"|"cancelled" created_at: int @dataclass class TradeResult: plan_id: str; entry_order: Order; exit_order: Order pnl: float; pnl_percent: float exit_reason: str # "take_profit"|"stop_loss"|"manual" closed_at: int
L5 · ReviewRecord
@dataclass class ReviewRecord: review_id: str; trade_result: TradeResult; trade_plan: TradePlan tech_notes: str; position_notes: str; mindset_notes: str created_at: int
五 · 数据流向(主链路)
用户配置任务
ConfigStore.save(TaskConfig)
任务配置持久化
每根 K 线收盘 · Scheduler 定时触发
ExchangeAdapter.fetch_ohlcv()
拉取行情数据
→
KlineCache.merge()
更新 K 线缓存
并行计算
TrendModule.compute()
计算趋势方向
→ TrendResult
KeyLevelModule.compute()
识别关键位区间
→ KeyLevelList
两者均就绪
SignalModule.detect()
检测入场信号
有信号 · Signal 对象
PlanModule.build()
生成交易计划
RR 达标 · TradePlan 对象
同时执行
OrderExecutor.place()
开仓下单
auto_trade=True 时
Notifier.push()
Discord 通知
signal_fired 事件
PositionMonitor.watch()
追踪持仓状态
止损 / 止盈命中
OrderExecutor.close()
执行平仓
平仓后
ReviewStore.archive()
归档交易记录
Notifier.push()
Discord 通知
position_closed 事件
六 · 关键设计决策
混合调度模式(定时轮询 + 事件解耦)
Scheduler 基于定时轮询(每隔 N 秒检查 K 线收盘),简单可靠,避免 WebSocket 断连导致漏单;内部模块间通过 EventBus 事件驱动,解耦且可扩展。
KlineCache 双层存储
内存层(dict):最近
磁盘层(SQLite + WAL 模式):全量历史,供回测和图表,WAL 支持并发读。
写入时先更内存,再异步刷磁盘;读取优先内存。
window_size × 2 根 K 线,供计算热路径,读写极快。磁盘层(SQLite + WAL 模式):全量历史,供回测和图表,WAL 支持并发读。
写入时先更内存,再异步刷磁盘;读取优先内存。
RR 校验在 PlanModule,不在 SignalModule
SignalModule 只管"是否有形态",与仓位管理逻辑完全解耦。PlanModule 可以独立调整 RR 规则,不影响信号检测逻辑。两者可以独立演进和测试。
自动下单双保险
auto_trade=False 时 OrderExecutor 只记录 TradePlan、推送 Discord 通知,不发送任何订单,防止网络抖动或配置错误时意外下单。后续可扩展为在 Discord 回复命令触发下单。算法策略模式(Strategy Pattern)
TrendModule / KeyLevelModule / SignalModule 均可插拔:每个算法实现同一接口
compute(klines, params) -> Result;TaskConfig 存算法名字符串,运行时注册表动态加载。支持 A/B 对比:同一任务可配置多套算法并行跑,结果独立存储。配置集中,下游只读
所有运行参数集中在 TaskConfig,下游模块只读不改,通过 ConfigStore 订阅变更事件。避免各模块维护自己的配置副本;配置变更后 Scheduler 自动重载受影响任务。起步用 JSON 文件(tasks.json),够用后迁移 SQLite。
回测模式(Scheduler 注入历史 K 线)
回测时 Scheduler 注入历史 K 线替代实时拉取,其他所有模块无需改动。KlineCache 的磁盘层直接服务于回测,分析链完全复用。
七 · 技术选型
| 层次 | 选型 | 理由 |
|---|---|---|
| 语言 | Python 3.11+ | 现有代码为 Python;CCXT/pandas/numpy 量化生态成熟 |
| 交易所接入 | CCXT 6.x | 统一接口,支持 OKX/Binance/Bybit;项目已在用 |
| K 线存储 | SQLite + WAL 模式 | 单文件部署;WAL 支持并发读;够用到百万级 K 线 |
| 配置持久化 | JSON 文件起步 → SQLite | 起步最简单,够用后无缝迁移 |
| 任务调度 | APScheduler 3.x | 支持 cron/interval;内存调度,不引入 Redis |
| 事件总线 | asyncio.Queue 或 blinker | 轻量;单进程内足够;不引入消息队列 |
| HTTP API / 图表 | FastAPI + Uvicorn | 异步;自动 OpenAPI 文档 |
| 图表渲染 | ECharts(前端)+ Python 生成 JSON | 已有 HTML 图表基础;ECharts 支持 K 线 + 填充矩形 |
| Discord 推送 | httpx POST Webhook | 无需 discord.py 全功能库;足够推送消息 |
| 测试 | pytest + pytest-asyncio | 主流;支持异步测试 |
| 部署 | Docker Compose(Oracle 远端) | 单机部署,进程隔离 |
八 · 实施路线图
Phase 1 · 已上线
核心分析链路
- L0 ConfigStore(tasks.json)
- L1 ExchangeAdapter + KlineCache
- L2 TrendModule(EMA 三均线)
- L2 KeyLevelModule(S/R Flip)
- L5 ChartServer(HTML 静态图表)
Phase 2 · 下一步
信号检测与计划生成
- L0 EventBus(asyncio.Queue 实现)
- L0 Scheduler(APScheduler 封装)
- L3 SignalModule(Pin Bar 检测起步)
- L3 PlanModule(入场/止损/止盈/RR 校验)
- L5 Notifier(Discord Webhook 推送信号)
完成标志:Discord 收到格式化信号通知,包含交易对、方向、入场价、止损、止盈、盈亏比。
Phase 3
手动执行 + 基础复盘
- L4 OrderExecutor(auto_trade=False 仅记录)
- L4 PositionMonitor(价格监控 + 人工确认平仓)
- L5 ReviewStore(归档 + 基础胜率统计)
完成标志:完整走通一笔模拟交易,从信号到归档全程有记录。
Phase 4
自动执行与完整闭环
- L4 OrderExecutor(auto_trade=True 全自动)
- L4 PositionMonitor(止损/止盈自动触发)
- L5 ReviewStore(多维度统计 + 参数优化建议)
- L0 ConfigStore UI(任务管理页面)
完成标志:系统可 7×24 无人值守运行,每笔交易自动开仓、止损/止盈、归档。
九 · 目录结构
crypto_trader/
├── config/
│ └── tasks.json # 任务配置持久化(起步)
├── core/
│ ├── config_store.py # L0 ConfigStore
│ ├── scheduler.py # L0 Scheduler
│ └── event_bus.py # L0 EventBus
├── ingestion/
│ ├── exchange_adapter.py # L1
│ └── kline_cache.py # L1(内存热路径 + SQLite 磁盘)
├── analysis/
│ ├── trend/
│ │ ├── base.py # 算法接口
│ │ └── ema_triple.py # EMA 三均线实现
│ └── keylevel/
│ ├── base.py
│ └── sr_flip.py # S/R Flip 实现
├── signal/
│ ├── signal_module.py # L3 SignalModule
│ ├── plan_module.py # L3 PlanModule
│ └── patterns/
│ └── pin_bar.py
├── execution/
│ ├── order_executor.py # L4
│ └── position_monitor.py # L4
├── output/
│ ├── chart_server.py # L5
│ ├── notifier.py # L5(httpx Webhook)
│ └── review_store.py # L5
├── models/
│ └── types.py # 所有 dataclass 定义
├── tests/
└── main.py # 启动入口
十 · 扩展预留
| 扩展方向 | 预留设计 |
|---|---|
| 多交易所并发 | ExchangeAdapter 按 exchange_id 实例化;KlineCache 以 (exchange, symbol, timeframe) 为键 |
| 多算法 A/B 测试 | TaskConfig 支持 algo_variants: list;Analysis 层并行运行,结果分别存储 |
| 回测模式 | Scheduler 注入历史 K 线替代实时拉取;其他模块无需改动 |
| Web 管理后台 | FastAPI 路由扩展,ConfigStore 暴露 REST API |
| 趋势强度分值 | TrendResult 预留 strength: float 字段,PlanModule 据此调整仓位比例 |