美股-后端服务模块

后端服务模块（backend/）

FastAPI 后端负责加载离线快照数据，提供查询、过滤、排序等 API，支持实时数据推送、预警系统、信号产品系统、因子回测和宏观/板块数据接口。

目录结构

text 复制代码

backend/
├── main.py               # FastAPI 应用入口，路由注册，生命周期管理
├── prod_app.py           # 生产环境应用（含静态文件服务）
├── loader.py             # 数据加载、缓存、查询引擎
├── meta.py               # 元数据与筛选分组定义
├── presets.py            # 多时间周期预设策略定义
├── market_hours.py       # 美股交易时段与假日日历
│
│  # ── 实时数据 ──
├── rt_api.py             # 实时数据 API 路由
├── rt_hub.py             # 实时推送中心（WebSocket 编排）
├── rt_ws.py              # WebSocket 端点（设备注册、订阅管理）
├── rt_aliyun_ticker.py   # 阿里云行情后台 Ticker
│
│  # ── 预警系统 ──
├── alerts_api.py         # 预警 API 路由（CRUD + 事件查询）
├── alerts_db.py          # SQLite 存储层（规则、事件、设备）
├── alert_engine.py       # 预警引擎（规则评估、状态管理）
├── alert_dispatcher.py   # 预警分发器（WebSocket 推送）
├── alert_evaluators.py   # 规则评估器（6 种预警类型）
├── alert_models.py       # 数据结构（AlertRule, AlertEvent 等）
├── alerts_presets.py     # 预警模板（6 种预设规则）
│
│  # ── 信号产品系统 ──
├── signal_product_api.py    # 信号产品 API 路由（候选池、信号、绩效、模拟交易）
├── signal_product_models.py # 信号数据模型（Candidate/Signal/Outcome/Position）
├── signal_product_db.py     # 信号 SQLite 持久化（4 表：candidates/signals/outcomes/positions）
├── signal_entry_engine.py   # 盘中信号入场评估引擎
│
│  # ── 回测系统 ──
├── backtest_api.py       # 因子回测 API 路由（IC 评估、绩效分析）
│
│  # ── 数据接口 ──
├── screener_api.py       # 选股器 API（排名、评分）
├── macro.py              # 宏观经济指标接口
├── sectors.py            # 板块轮动数据接口
│
│  # ── 工具 ──
├── app/factors/
│   └── date_utils.py     # 日期格式工具（YYYYMMDD 标准化）
└── test_*.py             # 测试文件

启动流程

text 复制代码

应用启动
  ↓
加载 config.yaml（实时数据 + 预警配置）
  ↓
load_snapshot()  → 缓存到 _SNAPSHOT_CACHE
load_history()   → 缓存到 _HISTORY_CACHE
  ↓
初始化 RTManager（实时数据管理器）
初始化 RTHub（推送中心）
初始化 AlertEngine + AlertDispatcher（预警引擎）
初始化 DeviceRegistry（WebSocket 设备注册）
初始化 SignalProductRepository（信号产品 SQLite）
  ↓
注册路由 + CORS 中间件
  ↓
可选：启动 Aliyun Ticker（后台定时获取行情）
  ↓
uvicorn 启动，监听 8000 端口

各文件详解

main.py --- 应用入口

FastAPI 应用的主入口，管理生命周期和路由。

生命周期：

启动时：加载配置、初始化实时数据管理器、RTHub 推送中心、预警引擎、信号产品仓库、加载快照和历史数据
关闭时：停止 Aliyun Ticker、清理资源

API 端点：

端点	方法	说明	参数
`/api/meta`	GET	返回筛选元数据（分组、标签、统计）	---
`/api/stocks`	GET	查询股票列表	filters, conditions, sort_by, sort_asc, offset, limit
`/api/pattern-stats`	GET	形态统计（触发次数、胜率、收益率）	---
`/api/combo-stats`	GET	多信号组合统计	---
`/api/stocks/{symbol}/history`	GET	单只股票历史 K 线	range (3m/6m/1y/2y)
`/api/stock/{symbol}`	GET	单只股票快照数据	---
`/api/stocks/{symbol}/fundamentals`	GET	单只股票基本面数据	---
`/api/presets`	GET	多时间周期预设策略列表	---

loader.py --- 数据引擎

核心数据模块，负责 parquet 加载、内存缓存和查询处理。

缓存机制：

text 复制代码

data.parquet  →  _SNAPSHOT_CACHE (DataFrame)  →  内存常驻
history.parquet → _HISTORY_CACHE (DataFrame)  →  内存常驻

全局变量 _SNAPSHOT_CACHE / _HISTORY_CACHE 实现懒加载
首次访问时从磁盘加载，后续直接读内存

查询流程：

text 复制代码

query_stocks(filters, conditions, sort_by, sort_asc, offset, limit)
  ↓
_apply_filters()      →  按标志列筛选（value=1）
  ↓
_parse_conditions()   →  解析 JSON 条件（支持 <, <=, >, >=, =）
  ↓
_apply_conditions()   →  应用连续值条件过滤
  ↓
排序 + 分页
  ↓
_to_records()         →  转换为 JSON 格式返回

列分类：

类别	说明	示例
REQUIRED_COLUMNS	必需字段	trade_date, symbol, name
CONTINUOUS_FILTER_COLUMNS	连续值列	ret_1d, ma5, forward_pe, piotroski_score, value_quality_score, altman_z_score, rsi_14, macd_dif, mfi_14...
SORTABLE_COLUMNS	可排序字段	signal_score, market_cap, piotroski_score, value_quality_score, altman_z_score...
PATTERN_FLAG_COLUMNS	形态标志列	96+ 个二值指标（含 ind_macd_bull_cross, ind_rsi_oversold, ind_bb_squeeze 等）

meta.py --- 元数据定义

定义前端的筛选分组结构和统计信息。

筛选分组：

分组 ID	名称	指标数	示例指标
single_candle	单 K 形态	7	bull_candle, hammer, doji
double_candle	双 K 形态	3	bullish_engulfing, inside_bar
triple_candle	三 K 形态	2	three_white_soldiers
trend_structure	趋势结构	6	ma_bull, platform_breakout
volume_volatility	量价波动	4	volume_breakout, vol_contraction
momentum	动量	4	break_high_20, consec_up_3
valuation	估值指标	5	forward_pe, peg_ratio
financials	财务指标	8	roe, profit_margin, revenue_growth
fundamental_quality	基本面质量	3	fund_piotroski_strong, fund_value_quality, risk_financial_distress
advanced_indicators	高级技术指标	20+	ind_macd_bull_cross, ind_rsi_oversold, ind_bb_squeeze, ind_mfi_oversold 等

核心函数：

build_meta_response() --- 构建完整的元数据响应（含统计）
build_pattern_stats_response() --- 形态命中统计和标签
_count_indicator_hits() --- 计算各指标命中数量

signal_product_api.py --- 信号产品 API

信号产品系统的 REST API，覆盖候选池、入场信号、绩效追踪和模拟交易全流程。

端点	方法	说明
`/api/signals/status`	GET	信号系统状态（活跃信号数、今日候选数、日期）
`/api/signals/candidates`	GET	每日候选股列表（支持按日期/自选股/股票代码过滤）
`/api/signals/active`	GET	当前活跃（持仓中）信号列表
`/api/signals/history`	GET	信号历史（分页，含已平仓信号）
`/api/signals/performance/summary`	GET	聚合绩效指标（胜率、收益率、Sharpe）
`/api/signals/evaluate`	GET	用实时数据评估今日全部候选股
`/api/signals/evaluate/{symbol}`	GET	用实时数据评估单只候选股
`/api/signals/portfolio`	GET	模拟持仓列表
`/api/signals/portfolio/follow`	POST	跟随信号开仓（模拟交易）
`/api/signals/portfolio/{position_id}/close`	POST	平仓（模拟交易）

signal_product_models.py --- 信号数据模型

信号产品管线的全部数据结构。

核心数据类：

数据类	说明	关键字段
`CandidateRecord`	每日候选股	candidate_id, symbol, rank, offline_score, 各维度评分, 风险标签
`SignalRecord`	盘中入场信号	signal_id, candidate_id, symbol, entry/stop/target 价格, trigger_reasons
`SignalOutcome`	信号绩效追踪	forward_return_1d/3d/5d/10d, MFE, MAE, hit_stop, hit_target
`PaperPosition`	模拟交易仓位	symbol, entry_price, quantity, stop/target, unrealized_pnl

CandidateRecord 风险门控：

HARD_RISK_FLAGS = {"low_liquidity", "abnormal_volatility", "weekly_downtrend"}
is_eligible() --- 检查评分阈值和无硬性风险标记

signal_product_db.py --- 信号 SQLite 存储

信号产品系统的持久化层，使用 SQLite WAL 模式。

数据表：

表	用途	关键索引
candidates	每日候选股打分结果	date, symbol
signals	盘中入场信号	date, symbol, status
signal_outcomes	后验绩效（MFE/MAE/前向收益）	signal_id, symbol
paper_positions	模拟交易仓位	symbol, status

特性：WAL 模式并发、JSON 序列化、UPSERT 更新。

signal_entry_engine.py --- 盘中信号入场引擎

评估是否为候选股生成盘中入场信号。

4 重入场门控（全部通过才生成信号）：

门控	函数	条件
VWAP 门控	`_gate_price_above_vwap()`	当前价 > VWAP
动量门控	`_gate_momentum()`	最新价 > 3根 Bar 前价格
量能门控	`_gate_volume_surge()`	成交量 ≥ 1.5 × 近期均量
波动率门控	`_gate_realized_volatility()`	实现波动率 < 4%

可配置参数：

参数	默认值	说明
min_offline_score	70	最低离线评分阈值
min_intraday_score	70	最低盘中评分阈值
default_stop_pct	0.04	默认止损比例（4%）
default_reward_risk_ratio	2.0	默认盈亏比
volume_surge_threshold	1.5	量能突破倍数
max_realized_volatility	0.04	最大允许实现波动率（4%）

核心函数：

evaluate_entry_signal() --- 主评估函数
compute_intraday_score() --- 计算 0-100 盘中评分
build_trade_plan() --- 根据配置计算止损/目标价

backtest_api.py --- 因子回测 API

因子评估和策略绩效的 REST API。

端点	方法	说明
`/api/backtest/factors`	GET	因子评估（IC/ICIR 统计、IC 分布）
`/api/backtest/performance`	GET	策略绩效（NAV、Sharpe、回撤、月度收益）
`/api/backtest/compare`	GET	多策略对比
`/api/backtest/cache/clear`	POST	清除计算缓存

预定义因子：momentum_20d, momentum_5d, rsi_14, volume_ratio_5

绩效指标：NAV 曲线、Sharpe/Calmar 比率、最大回撤、年化收益/波动率、胜率、超额收益

presets.py --- 多时间周期预设策略

定义跨日/周/60 分钟的多时间周期共振策略。

4 种预设策略：

预设	说明
trend_following	趋势追踪（多周期均线共振）
pullback_buy	回调买入（趋势确认 + 回踩支撑）
momentum_breakout	动量突破（多周期突破共振）
value_quality	价值质量（基本面 + 技术面共振）

每个预设在日/周/60 分钟三个周期分别定义 conditions，后端根据快照数据计算匹配度并返回评分。

market_hours.py --- 交易时段

美股交易时段感知工具。

功能：

判断当前交易时段（盘前/盘中/盘后/空闲）
美东时区处理（America/New_York）
内置假日日历（2026-2027 年）
决定实时数据获取策略（空闲时段暂停）

rt_api.py --- 实时数据路由

提供盘中实时数据的 API 端点。

端点	说明	可用性
`/api/rt/quotes`	获取实时报价	免费
`/api/rt/ranking`	实时排名	付费
`/api/rt/kline`	分钟 K 线	付费
`/api/rt/scan`	全市场扫描	付费
`/api/rt/status`	服务状态查询	免费
`/api/rt-prices`	轻量价格轮询端点	免费

rt_hub.py --- 实时推送中心

实时报价的核心编排模块，连接上游数据源和下游 WebSocket 客户端。

功能：

管理所有 WebSocket 客户端连接
处理订阅/取消订阅（每个客户端可订阅不同股票）
接收上游推送并广播给订阅的客户端
交易时段感知（非交易时段自动暂停推送）

rt_ws.py --- WebSocket 端点

提供 /ws/rt WebSocket 端点供前端连接。

功能：

设备注册与断线清理
subscribe/unsubscribe 消息处理
ping/pong 心跳检测
连接状态追踪

rt_aliyun_ticker.py --- 阿里云 Ticker

后台定时任务，通过阿里云 API 获取实时行情并合并到快照缓存。

特性：

可配置更新间隔（默认 60 秒）
交易时段感知（盘前显示 after_price，盘中显示 price，盘后显示 after_price）
支持启动/停止控制
通过 config.yaml 中的 aliyun_ticker_enabled 开关

alerts_api.py --- 预警 API

预警系统的 REST API 接口。

端点	方法	说明
`/api/alerts/rules`	GET	获取预警规则列表
`/api/alerts/rules`	POST	创建预警规则
`/api/alerts/rules/{id}`	DELETE	删除预警规则
`/api/alerts/events`	GET	获取触发事件历史（分页）
`/api/alerts/presets`	GET	获取预警模板列表

参数验证：每设备最多 50 条规则，规则类型和参数校验。

alerts_db.py --- 预警 SQLite 存储

预警系统的持久化存储层。

数据表：

表	用途
devices	设备注册信息
alert_rules	预警规则（类型、参数、状态）
alert_events	触发事件记录

特性：

WAL 模式支持并发读写
事件自动清理（默认保留 30 天）
外键级联删除

alert_engine.py --- 预警引擎

核心预警处理模块，负责规则评估、状态管理和事件分发。

工作流：

text 复制代码

实时报价到达
  ↓
遍历所有 armed 状态的规则
  ↓
alert_evaluators 评估条件
  ↓
条件满足 → 触发事件
  ├── 状态变为 fired
  ├── 写入 SQLite (alert_events)
  └── alert_dispatcher → WebSocket 推送到前端

alert_evaluators.py --- 规则评估器

6 种预警类型的条件评估逻辑。

评估器	类型	说明
价格变动	price_change	涨跌幅超过阈值（如 ±3%）
突破新高	breakout_high	价格突破指定高点
跌破新低	breakout_low	价格跌破指定低点
成交量异动	volume_spike	成交量超过 N 倍均值
均线交叉	ma_cross	短期均线穿越长期均线
52 周高低	week52_high_low	接近或突破 52 周高低点

alert_models.py --- 数据结构

预警系统的类型定义。

AlertRule --- 用户创建的预警规则
CompiledRule --- 编译后的规则（含评估器）
AlertEvent --- 触发的事件记录
AlertPreset --- 预警模板

alerts_presets.py --- 预警模板

6 种预定义预警模板，方便用户快速创建规则：

模板	说明
急涨急跌	涨跌幅超过阈值
突破新高	价格突破近期高点
跌破新低	价格跌破近期低点
放量异动	成交量异常放大
均线金叉	短期均线上穿长期均线
52 周新高	接近 52 周最高价

alert_dispatcher.py --- 预警分发器

将触发的预警事件通过 WebSocket 推送到对应设备的前端。

维护设备 ID → WebSocket 连接的映射
Best-effort 交付（连接断开则跳过）
与 AlertEngine 事件回调对接

screener_api.py --- 选股器 API

提供选股结果和评分排名接口。

端点	方法	说明
`/api/screener/status`	GET	选股器运行状态
`/api/screener/results`	GET	排名结果列表
`/api/screener/stock/{symbol}`	GET	单只股票评分详情

macro.py --- 宏观指标接口

读取 macro.parquet 并提供宏观指标 API。

端点	方法	说明
`/api/macro`	GET	获取宏观指标数据

返回内容：

各指标（VIX、10Y、DXY、SPX）的最新值和变化
风险等级分类：calm（平静）/ normal（正常）/ risk（风险）
缓存机制（mtime 感知，文件更新自动刷新）

sectors.py --- 板块轮动接口

读取 sectors.parquet 并提供板块轮动数据 API。

端点	方法	说明
`/api/sectors`	GET	获取板块轮动数据

返回内容：

11 个板块 ETF + 3 个风格 ETF 的排名
20 日 / 60 日收益率
相对 SPY 基准的相对强弱
动量评分

prod_app.py --- 生产环境包装

在主应用基础上增加静态文件服务。如果 static/ 目录存在，自动挂载为静态资源路由。

运行命令

bash 复制代码

cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000