Fire 工程架构

分层架构

Fire 采用清晰的分层架构，后端四层、前端四层，依赖方向自上而下。

后端分层

flowchart TD
    subgraph "API Layer"
        REST[REST Endpoints]
        WS[WebSocket Endpoints]
        MW[Middleware]
    end

    subgraph "Service Layer"
        TS[TradingService]
        WS_SVC[WebSocketService]
        Other[其他业务服务]
    end

    subgraph "Repository Layer"
        FR[FlowRepository]
        BR[BrokerRepository]
        TR[TradingRepository]
    end

    subgraph "Infrastructure Layer"
        Redis[(Redis)]
        Broker[券商 API]
        Config[配置管理]
    end

    REST --> TS
    WS --> WS_SVC
    MW --> TS
    TS --> FR
    TS --> TR
    FR --> Redis
    BR --> Redis
    TS --> Broker

层级	职责	主要组件	依赖方向
API 层	请求处理、路由、序列化	endpoints, middleware	→ Service
Service 层	业务逻辑、事务管理	services, validators	→ Repository
Repository 层	数据访问抽象	repositories	→ Infrastructure
Infrastructure 层	技术实现、外部集成	database, cache, broker	无依赖

前端分层

flowchart TD
    subgraph "View Layer"
        Pages[Pages]
        Components[Components]
    end

    subgraph "State Layer"
        Context[Context]
        Hooks[Hooks]
    end

    subgraph "Service Layer"
        API[API Services]
        WS[WebSocket Services]
    end

    subgraph "Utils Layer"
        Client[HTTP Client]
        Helper[Helpers]
    end

    Pages --> Context
    Components --> Hooks
    Context --> API
    Hooks --> API
    API --> Client
    WS --> Client

层级	职责	主要组件	依赖方向
View 层	UI 渲染、用户交互	pages, components	→ State
State 层	状态管理、业务逻辑	contexts, hooks	→ Service
Service 层	API 封装、数据转换	services	→ Utils
Utils 层	通用工具、基础设施	api-client, helpers	无依赖

核心目录详解

core/ 模块结构

backend/core/ 是系统核心业务逻辑所在，其中 core/trading/ 是最重要的交易核心模块。

core/
├── trading/                # 交易核心模块
│   ├── mtf/                # 多时间框架核心
│   │   ├── flow_runtime.py         # Flow 节点图执行引擎
│   │   ├── flow_validator.py       # Flow 配置验证器
│   │   ├── director.py             # Director 模块
│   │   ├── executor.py             # Executor 模块
│   │   ├── sizing_policy.py        # 仓位计算策略
│   │   ├── position_manager.py     # 仓位管理器（约束层叠）
│   │   ├── data_stream.py          # 数据流抽象层
│   │   ├── registry.py             # 策略注册器
│   │   └── models/                 # 数据模型
│   ├── engines/            # 交易引擎
│   │   ├── trading_engine.py           # 订单执行引擎
│   │   ├── trading_session_engine.py   # 会话管理引擎
│   │   ├── simulation_engine.py        # 模拟引擎
│   │   └── historical_data_manager.py  # 历史数据管理
│   ├── strategies/         # 策略实现
│   │   ├── indicators/             # 技术指标
│   │   │   ├── pandas_ta_wrapper.py    # pandas-ta 封装
│   │   │   └── cache.py                # 指标缓存
│   │   ├── momentum/               # 动量策略组
│   │   ├── trend/                  # 趋势策略组
│   │   ├── mean_reversion/         # 均值回归策略组
│   │   └── volume/                 # 成交量策略组
│   ├── risk/               # 风险控制
│   │   └── risk_engine.py          # 风险引擎
│   └── services/           # 交易服务
│       ├── risk_guard.py           # 风险守卫
│       └── alert_system.py         # 告警系统
├── repositories/           # 数据访问层
│   ├── flow_repository.py          # Flow 配置 CRUD
│   ├── broker_repository.py        # 券商配置
│   └── trading_repository.py       # 交易记录
├── services/               # 业务服务
│   ├── trading_service.py          # 交易服务
│   └── market_data_service.py      # 市场数据服务
└── models/                 # 数据模型

核心架构说明

Director：基于大周期（如 4h）判断市场状态，输出仓位约束（max_long_ratio, max_short_ratio）
Executor：基于小周期（如 1h）寻找入场时机，输出目标仓位（target_ratio）
PositionManager：约束层叠引擎，按优先级应用各类约束
FlowRuntime：节点图执行引擎，支持拓扑排序和并行执行

数据层设计

Redis 存储结构

Fire 使用 Redis 作为主要数据存储，支持会话管理、配置持久化和缓存。

Flow 配置存储

# Flow 配置
key: "fire:flows"
type: Hash
field: flow_id
value: JSON 序列化的 FlowConfig

# 示例
HGET fire:flows "flow_abc123"
# 返回 FlowConfig JSON

会话状态存储

# 交易会话状态
key: f"session:{session_id}"
value: JSON 序列化的 SessionState

# PositionManager 状态
key: f"pm_state:{session_id}:{symbol}"
value: {
    "stop_loss_price": 150.0,
    "take_profit_price": 180.0,
    "trailing_stop_activated": true,
    "entry_price": 160.0,
    "entry_time": "2025-12-01T10:00:00Z"
}

券商配置存储

# 券商配置
key: f"broker:{broker_id}"
value: JSON 序列化的 BrokerConfig

FlowConfigRepository 接口

class FlowConfigRepository:
    def get_all(self) -> List[FlowConfig]:
        """获取所有 Flow 配置列表"""
        pass

    def get_by_id(self, flow_id: str) -> Optional[FlowConfig]:
        """获取单个 Flow 配置"""
        pass

    def create(self, flow: FlowConfig) -> str:
        """创建 Flow，返回 flow_id"""
        pass

    def update(self, flow_id: str, updates: Dict) -> bool:
        """更新 Flow 配置（版本号递增）"""
        pass

    def delete(self, flow_id: str) -> bool:
        """删除 Flow 配置"""
        pass

数据流供给

市场数据源

Fire 支持多种数据源接入：

数据源	用途	模式
LongPort API	券商实时/历史行情	实盘交易
Redis 缓存	历史数据存储	回测
WebSocket	实时行情推送	实时交易

数据流架构

flowchart TD
    subgraph "数据源层"
        LP[LongPort API<br/>券商接口]
        REDIS[(Redis<br/>数据存储)]
        WS[WebSocket<br/>实时推送]
    end

    subgraph "适配器层"
        CF[ClientFactory<br/>客户端工厂]
        QA[QuoteAdapter<br/>行情适配器]
    end

    subgraph "处理层"
        HDM[HistoricalDataManager<br/>历史数据管理]
        DS[DataStream<br/>数据流抽象]
    end

    subgraph "消费层"
        DIR[Director]
        EXE[Executor]
    end

    LP --> CF
    REDIS --> QA
    WS --> QA
    CF --> QA
    QA --> HDM
    HDM --> DS
    DS -->|4h K线| DIR
    DS -->|1h K线| EXE

    style DS fill:#e1f5ff

DataStream 接口

DataStream 为不同时间周期的组件提供统一的数据访问接口：

class DataStream(ABC):
    """多时间框架数据流抽象"""

    @abstractmethod
    async def get_candles(
        self,
        symbol: str,
        timeframe: str,  # "1m", "15m", "1h", "4h", "1d"
        count: int
    ) -> List[CandleData]:
        """获取指定周期的 K 线数据"""
        pass

    @abstractmethod
    async def subscribe(
        self,
        symbol: str,
        timeframes: List[str],
        callback: Callable
    ) -> None:
        """订阅多周期数据更新"""
        pass

时间框架聚合

DataStream 支持从小周期数据聚合生成大周期数据：

源周期	目标周期	聚合方式
1m	15m	15 根 1m K 线合并
15m	1h	4 根 15m K 线合并
1h	4h	4 根 1h K 线合并
4h	1d	6 根 4h K 线合并

安全架构

认证与授权

flowchart LR
    subgraph "认证流程"
        Login[用户登录] --> Validate[验证凭据]
        Validate --> JWT[生成 JWT]
        JWT --> Store[存储 Token]
    end

    subgraph "请求验证"
        Request[API 请求] --> Extract[提取 Token]
        Extract --> Verify[验证 Token]
        Verify --> Check[检查权限]
        Check --> Process[处理请求]
    end

    Store --> Request

安全措施	实现方式	目的
身份认证	JWT Token (7天有效期)	验证用户身份
权限控制	RBAC 基于角色	控制资源访问
数据加密	HTTPS/TLS	传输安全
密码存储	bcrypt 哈希	防止明文泄露

Token 管理策略

策略	前端实现	后端实现
存储位置	localStorage	内存 + Redis
自动添加	ApiClient 拦截器	-
刷新机制	401 时重新登录	JWT 7 天过期
失效处理	401/403 自动跳转登录	返回标准错误响应

API 客户端认证

// 前端统一 API 客户端
class ApiClient {
    // 自动 Token 管理
    private buildHeaders(): HeadersInit {
        const token = localStorage.getItem('token');
        return {
            'Content-Type': 'application/json',
            'Authorization': token ? `Bearer ${token}` : ''
        };
    }

    // 统一错误处理
    private async handleResponse<T>(response: Response): Promise<T> {
        if (response.status === 401 || response.status === 403) {
            localStorage.removeItem('token');
            window.location.href = '/login';
            throw new Error('认证失败');
        }
        // ... 其他错误处理
    }
}

部署与运维

本地开发部署

系统目前支持本地开发部署，不涉及生产部署配置。

核心组件：

前端：Vite Dev Server (端口 3000) + HMR 热更新
后端：Uvicorn ASGI 服务器 (端口 8000) + --reload 自动重载
数据库：本地 Redis (端口 6379)
代理：Vite 内置 HTTP/WebSocket 代理

启动方式：

# 方式1: 使用启动脚本 (推荐)
./scripts/startup.sh              # 启动所有服务
./scripts/startup.sh --backend-only   # 仅启动后端
./scripts/startup.sh --frontend-only  # 仅启动前端
./scripts/startup.sh --stop          # 停止所有服务

# 方式2: 手动启动后端
cd backend && source venv/bin/activate
uvicorn main:app --reload --port 8000

# 方式3: 手动启动前端
cd frontend && npm run dev

开发特性：

前端 HMR (Hot Module Replacement) - 代码修改实时刷新
后端 Auto-reload - Python 文件修改自动重启
WebSocket 自动重连 - 后端重启时前端自动恢复连接
Vite Proxy - 自动转发 /api/* 和 /ws 到后端 8000 端口

日志架构

Fire 使用 Python 内置的 logging 模块进行日志记录。

日志级别：

DEBUG：调试信息
INFO：常规信息
WARNING：警告信息
ERROR：错误信息
CRITICAL：严重错误

日志存储：

应用日志：backend/logs/
系统日志：logs/backend.log

性能优化

前端优化：

代码分割：使用 Vite 动态导入实现按需加载
Tree Shaking：自动移除未使用的代码
懒加载：路由级别的组件懒加载

后端优化：

异步处理：FastAPI 原生异步支持
连接池：Redis 连接池复用
指标缓存：两级缓存减少重复计算

网络优化：

HTTP/2：支持多路复用
Keep-Alive：保持长连接

环境变量配置

基于 backend/infrastructure/config/settings.py：

环境变量	说明	默认值
`REDIS_HOST`	Redis 主机	localhost
`REDIS_PORT`	Redis 端口	6379
`REDIS_DB`	Redis 数据库编号	0
`LONGPORT_APP_KEY`	长桥 API Key	None
`LONGPORT_APP_SECRET`	长桥 API Secret	None
`LONGPORT_ACCESS_TOKEN`	长桥访问令牌	None
`JWT_SECRET_KEY`	JWT 签名密钥	your-jwt-secret-key-here

文档	内容
系统概览	系统简介、技术栈、核心概念
交易架构	DEP 核心架构、FlowRuntime、交易数据流
策略与风控	策略体系、PositionManager 约束、风险控制、策略开发指南

Fire Quantitative Trading System

基于现代技术栈的量化交易平台，支持股票交易、策略回测、风险管理等功能