xuangu API 端点路由速查
格式：§ | 端点路径 | HTTP方法 | 功能 | 数据源
本文分两层：
- §〇 按模块的全量端点索引 —— 机器生成，回答"有没有这个端点"
- §一起的高频端点速查 —— 人工撰写，回答"这个端点走哪条降级链、什么口径"
全量路由由
backend/app/api/自动发现注册（2026-10-07 统计：80 个模块 / 886 个操作声明， 含约 200 条include_in_schema=False的内部端点；§〇 表为滚动登记，未列出者以/openapi.json为准），逐条写进文档必然漂移，故索引只到模块 + 端点清单粒度； 参数与响应以http://localhost:6789/docs（Swagger UI）与/openapi.json为准。 高频端点（前端会用到的）必须补进下面的速查表。
〇、按模块的全量端点索引
生成方式（后端在跑时执行，输出即本节素材）：
"详细文档"列：✅ = 已有站内 API 参考；📎 = 见本文对应速查章节；— = 暂无专文，看 Swagger。
| 模块 | 前缀 | 操作数 | 职责 | 详细文档 |
|---|---|---|---|---|
| datamgr | /api/v1/datamgr | 209 | 管理端：逐股/批量下载、fox 融合与引擎调用、同步日志、调度触发、交易所数据 | ✅ datamgr-api · 📎 §5 §9 |
| db-admin | /api/v1/dbadmin | 72 | 数据库管理：表/列元数据、DDL、数据浏览与编辑、批量操作、导入导出、SQL 工作台（自动补全/引用表面板/历史收藏服务端化） | — |
| quant | /api/v1/quant | 36 | 技术指标、形态识别与形态目录、筹码分布、信号池、形态战绩 | 📎 §10.52~10.55 |
| market | /api/v1/market | 32 | 市场情绪/指数/概览/涨跌分布/资金流/行业排名/情绪阶段 | ✅ market-api |
| backtest-lab | /api/v1/backtest-lab | 25 | 回测实验室：策略清单、单次/批量回测、walk-forward、评估、轮动与信号串联、收益归因（成本/Brinson/时间）、缠论叠加 | — |
| settings | /api/v1/settings | 23 | 模型配置（多管理员）、Prompt、系统参数、缓存与状态 | — |
| factor | /api/v1/factor | 22 | 因子字典、14 套预设、打分筛选、个股命中 | 📎 §10.41~10.43 |
| bigv | /api/v1/bigv | 20 | 大V 文章采集、每日综述 AI 管道、规则核验 | — |
| stocks | /api/v1/stocks | 19 | 搜索、个股详情、K线、财务、VPA、AH 比价、策略体检 | ✅ stocks-api · 📎 §2 |
| checklist | /api/v1/checklist | 19 | 检查清单模板与实例（可复用投研核对流程） | — |
| sectors | /api/v1/sectors | 17 | 板块清单/成分/概念/自选板块/板块强度与轮动/分钟资金流 | 📎 §3 |
| strategies | /api/v1/strategies | 17 | 用户自建 SmartPick 规则策略：CRUD、字段、运行与快照 | — |
| auth | /api/v1/auth | 16 | 注册/登录/验证码/密码重置/个人资料/会话 | 📎 认证与通知 |
| macro | /api/v1/macro | 14 | 宏观总览、状态判读与判读战绩、维度×行业暴露矩阵、国债收益率曲线、股债利差 ERP、政策利率、财政税收、税率速查、资金面拥挤度、指数 PE 分位通道、宏观评分与回放验证 | 📎 §10.1~10.2k |
| tdx | /api/v1/tdx | 13 | TDX TCP 直连：盘口深度、财务快照、资金流、F10、板块、同步 | 📎 §8 |
| portfolio | /api/v1/portfolio | 13 | 持仓上传解析、交易分析、组合优化、持仓明细 | — |
| skills | /api/v1/skills | 12 | AI 技能目录、开关、排序、技能详情 | 📎 AI 能力 |
| system | /api/v1/system | 12 | 数据新鲜度体检、跨源核对、复权自检、TDX 离线诊断 | — |
| ths-f10 | /api/v1/ths-f10 | 12 | 同花顺 F10：概况/财务变动/股东/分红/主营构成 | — |
| favorites | /api/v1/favorites | 12 | 自选股增删查 + 研究候选池（四状态工作流） | 📎 §6 |
| etf | /api/v1/etf | 10 | ETF 自选、行情、持仓 | — |
| equity | /api/v1/equity | 10 | 股权结构：十大股东、业绩预告/快报、高管持股 | — |
| convertible-bond | /api/v1/convertible-bond | 9 | 可转债双低、债底安全边际、条款、票面、关键日期、募资用途 | 📎 §10.11~10.19 |
| hot-trending | /api/v1/hot-trending | 9 | 多类热榜聚合（股票/财经/科技/社交/视频） | — |
| index | /api/v1/index | 9 | 中证官方指数估值/权重/成分/结构 | 📎 §10.20~10.22 |
| tasks | /api/v1/tasks | 9 | 任务中心：总览、运行记录、事件、SSE 流、统计与清理 | 📎 任务中心 |
| realtime | /api/v1/realtime | 8 | 交易时段、热门股、板块热力图、盘中/偏离异动、资金流 | ✅ market-api |
| risk | /api/v1/risk | 8 | 股权质押、商誉、千股千评（排行 + 个股） | 📎 §10.3~10.10 |
| tactics | /api/v1/tactics | 8 | 6 类战法目录、信号扫描与快照 | — |
| thesis | /api/v1/thesis | 8 | 投资论点管理（自建/公开/复盘） | — |
| engine-signals | /api/v1/engine-signals | 7 | 引擎增强信号：美股→A股联动映射、跨系统信号仲裁 | — |
| mastery | /api/v1/mastery | 7 | 交易技艺进阶：技能树、里程碑、进度追踪 | — |
| performance | /api/v1/performance | 7 | 服务性能指标、缓存命中率、慢端点 | — |
| signal | /api/v1/signal | 7 | 个股信号：热门原因、资金流、龙虎榜、北向、解禁 | — |
| chat | /api/v1/chat | 6 | AI 对话、流式对话、个股深度分析、批量对比、快速估值 | 📎 §4 |
| compare | /api/v1/compare | 6 | 对比集（多股并排）CRUD | — |
| industry | /api/v1/industry | 6 | 申万行业分类清单/占比/K线 + 行业估值分位 | 📎 §10.23~10.47 |
| monitor | /api/v1/monitor | 6 | 异动监控规则 CRUD 与触发记录 | — |
| position | /api/v1/position | 6 | 持仓工具：交易计划、持仓诊断 | — |
| commodity | /api/v1/commodity | 5 | 商品现货-期货基差、品种 K线、54 品种覆盖 | — |
| futures | /api/v1/futures | 5 | 期货仓单排行/时序、会员持仓排名、期限结构 | 📎 §10.32~10.36 |
| health | /api/v1/health | 5 | 健康检查、数据源状态、降级事件、数据源目录、主动探测 | 📎 §11 |
| morning | /api/v1/morning | 5 | 晨报读取/撰写/刷新（含降级稿来源标注） | 📎 AI 能力 |
| news-signal | /api/v1/news-signal | 5 | 消息面规则判读留痕、规则级战绩自学习 | — |
| notifications | /api/v1/notifications | 5 | 站内通知未读数、列表、已读标记 | 📎 认证与通知 |
| review | /api/v1/review | 5 | 收盘复盘读取/撰写/刷新 | 📎 AI 能力 |
| scorecard | /api/v1/scorecard | 5 | 回测成绩单：来源目录、明细、分组战绩、个股战绩 | 📎 §10.56~10.60 |
| screener | /api/v1/screener | 5 | 条件 DSL 选股：查询、筛选项、预设、自然语言解析 | — |
| stream | /api/v1/stream | 5 | 实时推送会话、状态、启停 | — |
| alt-sources | /api/v1/alt-sources | 4 | 备用数据源（乐咕乐股对账 / 港股新股 IPO / 雪球私募） | 📎 §10.37~10.40 |
| builtin-strategies | /api/v1/builtin-strategies | 4 | 内置打分体系卡片、榜单、历史战绩（与 /strategies 分家） | 📎 §10.48~10.51 |
| hk-finance | /api/v1/hk-finance | 4 | 港股财务三表、主要指标、总览 | 📎 §10.28~10.31 |
| portfolio-inspection | /api/v1/portfolio/inspection | 4 | 持仓诊断：行业暴露、风格漂移、集中度 | — |
| pattern-similarity | /api/v1/pattern-similarity | 4 | 历史形态相似度匹配 | — |
| reports | /api/v1/reports | 4 | 研究报告生成、历史、HTML 产物 | — |
| ai-usage | /api/v1/ai-usage | 3 | AI 用量统计：Token 消耗、成本追踪 | — |
| analysis | /api/v1/analysis | 3 | 个股五维分析（含流式） | 📎 AI 能力 |
| catalyst | /api/v1/catalyst | 3 | 催化剂事件与刷新 | — |
| chokepoint | /api/v1/chokepoint | 3 | 卡脖子选股：产业链瓶颈定位、弹性分、多空信号 | — |
| earnings | /api/v1/earnings | 3 | 业绩检索与最新业绩 | — |
| industry-prosperity | /api/v1/industry-prosperity | 3 | 行业景气度时序 | — |
| left-side | /api/v1/left-side | 3 | 左侧交易信号 | — |
| market-turnover | /api/v1/market-turnover | 3 | 两市成交额历史、手工采集与回填 | — |
| mcp | /api/v1/mcp | 3 | MCP 服务端点与工具清单（REST 包装） | 📎 §7 |
| mispricing | /api/v1/mispricing | 3 | 错误定价信号 | — |
| reit | /api/v1/reit | 3 | 公募 REITs 列表、K线、详情 | 📎 §10.22~10.24 |
| research | /api/v1/research | 3 | 个股研报、EPS 预测、机构估值 | — |
(非 /api/v1) | /mcp, / | 3 | FastMCP Streamable HTTP 挂载、MCP 工具 REST 包装、根路由 | 📎 §7 |
| limitup | /api/v1/limitup | 2 | 涨停原因归因 | — |
| macro-regime | /api/v1/macro | 2 | 宏观判读留痕与前向收益复盘 | — |
| margin | /api/v1/margin | 2 | 个股两融历史、国家 ETF 份额 | — |
| margin-watch | /api/v1/margin | 2 | 两融异动监控 | — |
| trade-plan | /api/v1/trade-plan | 2 | 交易计划 | — |
| daily-plan | /api/v1/daily-plan | 1 | 今日计划总览 | — |
| earnings-window | /api/v1/earnings-window | 1 | 财报窗口：市场级业绩聚合（预告/快报 + 行业与个股盈利榜，2026-10-06 新增） | 📎 §10.61 |
| datamgr-freshness | /api/v1/datamgr | 1 | 数据新鲜度单源检测 | — |
| market-signal | /api/v1/market/signal | 1 | 市场级跨源信号 | — |
| price-levels | /api/v1/stocks | 1 | 个股关键价位（压力/支撑） | — |
| sentiment | /api/v1/sentiment | 1 | 个股情绪 | — |
| source-capabilities | /api/v1/datamgr/source-capabilities | 1 | 数据源能力清单 | — |
| volatility | /api/v1/volatility | 1 | 波动率总览 | — |
一、行情层（实时，不封IP优先）
🔴 「数据源」列写的是主源；这些端点的载荷常由多源拼成，逐段出处看响应里的 段级标签（
_indices_source/_breadth_source/_limit_source/_bins_source/_sectors_source/_cells_source），契约见数据契约 §十二。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 1.1 | /api/v1/market/sentiment | GET | 市场情绪（指数+涨跌比+情绪分数） | 指数：腾讯 → TDX；家数：TDX 全量 → 腾讯批量 → DB |
| 1.2 | /api/v1/market/indices | GET | 主要指数实时行情 | 腾讯（单请求全量核心指数）→ TDX |
| 1.3 | /api/v1/market/overview | GET | 市场概览 | TDX DB + 东财 |
| 1.4 | /api/v1/market/distribution | GET | 涨跌分布（家数 + 13 段） | TDX 证券列表全量 → 东财探针 → fox_stock_wide（统一自洽门禁） |
| 1.5 | /api/v1/realtime/hot-stocks | GET | 全市场涨幅榜 TOP N | L1 fox_stock_wide → L2 腾讯全市场 → L3 快照样本 → L4 东财 → L5 雪球人气榜 |
| 1.6 | /api/v1/realtime/sector-treemap | GET | 板块热力图 | DB 板块表现 → 腾讯 getRank(hy2) → 东财 |
| 1.7 | /api/v1/realtime/stock-changes | GET | 异动监控（火箭发射/封板等） | 东财 push2ex |
| 1.8 | /api/v1/realtime/trading-time | GET | 交易日历+交易时段 | 本地计算 |
| 1.9 | /api/v1/realtime/money-flow/{code} | GET | 个股资金流向（日级） | TDX tdx_moneyflow → 东财 push2his |
| 1.10 | /api/v1/realtime/abnormal-moves | GET | 三类异动聚合（竞价/盘中/偏离值，借鉴 tick-stock-panel）。竞价段 = 昨日涨停股在今日集合竞价的表现（窗口内今日池未成型，且 09:30 后成分不漂移）；非交易日/盘前 auction 返回空并附 auction_status（TDX 撮合序列不带日期，防止把昨日行情标成今日）。?limit=20&use_cache=false 绕过服务端分档 TTL 强制重算 | TDX 竞价(0x056A) + 东财 getYesterdayZTPool + 东财 push2ex + 龙虎榜 |
二、股票详情与搜索
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 2.1 | /api/v1/stocks/search | GET | 模糊搜索股票（编码/名称/拼音首字母与全拼，分页，keyword 参数；纯字母输入在编码/名称无命中时走拼音索引 pypinyin） | fox DB fox_stock_master |
| 2.2 | /api/v1/stocks/{code} | GET | 股票详情（实时+估值组装） | TDX → 腾讯 → DB 快照（估值口径腾讯优先） |
| 2.3 | /api/v1/stocks/{code}/kline | GET | 日K线（四层读路径：SQLite 快路径 → KlineStore（Parquet/DuckDB，含覆盖度守卫）→ fox_kline_daily → 实时降级链） | 腾讯 → TDX → 东财（北交所：新浪 → 东财） |
| 2.4 | /api/v1/stocks/{code}/finance | GET | 财务数据（季频） | fox 融合（新浪+TDX）→ 新浪实时 |
| 2.5 | /api/v1/stocks/{code}/finance-indicators | GET | 关键财务指标（78 项×12 期，refresh=true 强制实时） | 新浪 gjzb（vFD_FinanceSummary） |
| 2.6 | /api/v1/stocks/{code}/ah-premium | GET | AH 比价（仅 A+H 两地上市股票，配对表 183 对；未配对返回 matched=false） | 腾讯 A/H 行情 + whHKDCNY 汇率 |
| 2.7 | /api/v1/stocks/{code}/vpa | GET | VPA 量价分析（健康度+偏多/偏空观察+证据链，2026-09-06 对标 dragon_quant） | 腾讯日K（fox 兜底） |
| 2.8 | /api/v1/stocks/index | GET | 全量股票轻量索引（header 本地搜索数据源；行结构 [code,name,market,industry,拼音首字母,拼音全拼]，拼音列与 §2.1 同源同缓存；ETag/304 + 1h 缓存，DB 不可用返回 X-Degraded 空索引） | fox DB fox_stock_master + pypinyin |
三、信号层（资金/龙虎/解禁/行业）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 3.1 | /api/v1/market/industry-rank | GET | 行业涨跌排名 | 腾讯 getRank → 新浪 → 东财 push2 → TDX 板块 |
| 3.2 | /api/v1/market/fund-flow | GET | 市场资金流向 | TDX（主源，DB 优先）→ 东财 push2his |
| 3.3 | /api/v1/sectors/{board_code}/stocks | GET | 板块成分股列表 | 东财 push2 |
| 3.4 | /api/v1/sectors/{board_code}/concepts | GET | 板块核心概念 | 东财 push2 |
| 3.5 | /api/v1/market/backtest/strategies | GET | 回测策略列表 | DB |
| 3.6 | /api/v1/datamgr/market/lhb-branch-stat | GET | 龙虎榜营业部上榜统计（N 日聚合，2026-09-06 新增） | 东财 datacenter 席位明细 |
| 3.7 | /api/v1/datamgr/market/dragon-score | GET | 五维「识别真龙」评分（门槛否决+加权聚合，2026-09-06 对标 dragon_quant） | 东财涨停池 + 选股器宽表 + 腾讯 1 分K |
| 3.8 | /api/v1/datamgr/market/dragon-review | GET | 真龙回测成绩单（断板日最低价买入 + 收益/回撤窗口 + 汇总统计，2026-09-06 对标 dragon_quant review） | fox_kline_daily（本地 DB） |
| 3.9 | /api/v1/datamgr/market/dragon-score-history | GET | 历史评分多条件筛选（日期/关键词/状态/连板/分数范围，读 app_dragon_score） | DB |
| 3.10 | /api/v1/datamgr/market/dragon-review-curve | GET | 多日真龙回测汇总曲线（胜率漂移监控，缓存 10 分钟） | DB 日K |
| 3.11 | /api/v1/datamgr/market/industry-rotation | GET | 行业轮动（最近两期快照对比：排名变化/5日涨幅/主力净流入/领涨股，2026-09-06 借鉴 tick-stock-panel） | DB 快照（16:35 落库） |
| 3.12 | /api/v1/market/regime | GET | 当日市场情绪阶段快照（九阶段合成，优先读落库） | 实时分析 → DB |
| 3.13 | /api/v1/market/phase-history | GET | 情绪阶段历史（行/阶段段/当前持续/转移分布，15:45 落库） | DB |
| 3.14 | /api/v1/datamgr/schedule/product-freshness | GET | 各采集任务的产出表最新日期（任务→产出联动，2026-09-06 新增） | DB |
| 3.15 | /api/v1/datamgr/schedule/{key}/run | POST | 手动触发任务；body 可选 {"trade_date": "YYYY-MM-DD"} 按历史日期回填（仅回填型任务：market_phase_sync/industry_rank_sync/dragon_score_sync） | 调度器 |
| 3.16 | /api/v1/sectors/{board_code}/flow-minute | GET | 板块当日分钟资金流曲线（主力/超大单/大单/中单/小单累计净额，09:30~15:00 全量分钟点含竞价首点；2026-10-06 新增，板块详情页用）。仅接受东财板块代码 BKxxxx；盘中 60s / 收盘后 600s 缓存，失败不缓存（不让一次风控被读成「该板块无数据」） | 东财 fflow（secid=90.BKxxxx，klt=1&lmt=0）→ push2delay |
| 3.17 | /api/v1/datamgr/market/trade-day-context | GET | 打板池日期上下文（今日是否交易日 + 默认应展示的交易日；非交易日回落到最近交易日，涨停板页默认日期解析用，2026-10-07 新增） | 交易日历 core.trading_calendar（零 HTTP） |
四、AI 对话与预置分析
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 4.1 | /api/v1/chat/ask | POST | AI 通用对话 | LLM |
| 4.2 | /api/v1/chat/ask/stream | POST | AI 流式对话（SSE） | LLM |
| 4.3 | /api/v1/chat/analyze-stock | POST | 个股深度分析 | LLM + 多数据源 |
| 4.4 | /api/v1/chat/quick-valuation | POST | 快速估值全景 | 腾讯 + 东财 + LLM |
| 4.5 | /api/v1/chat/batch-compare | POST | 批量横向对比 | 腾讯 + 东财 + LLM |
| 4.6 | /api/v1/chat/generate-title | POST | 对话标题生成 | LLM |
五、数据管理（管理端）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 5.1 | /api/v1/datamgr/stock-base/import | POST | 导入通达信全A股数据 | 文件上传 |
| 5.2 | /api/v1/datamgr/stock-base/backfill-stock-info | POST | 回填 stock_info | DB → DB |
| 5.3 | /api/v1/datamgr/stock-base/sync-tdx | POST | 同步 TDX 行情 | TDX TCP |
| 5.4 | /api/v1/datamgr/industry-rank/sync | POST | 拉取腾讯板块排行落库（hy2二级行业/hy一级行业/gn概念，block_type 参数） | 腾讯 getRank |
| 5.5 | /api/v1/datamgr/industry-rank/snapshot | GET | 查询板块排行快照（block_type 区分 hy2/hy/gn，默认最近一日） | DB tencent_industry_block_snapshot |
| 5.6 | /api/v1/datamgr/block/{block_code}/stocks/sync | POST | 同步指定板块成分股快照（含 pe_ttm/pb/市值等 20 字段） | 腾讯 getBoardRankList |
| 5.7 | /api/v1/datamgr/block/stocks/sync-all | POST | 批量同步板块成分股（遍历最近排行快照，max_blocks 安全阀） | 腾讯 getBoardRankList |
| 5.8 | /api/v1/datamgr/block/{block_code}/stocks | GET | 查询板块成分股快照（默认最近一日） | DB tencent_block_stock_snapshot |
| 5.9 | /api/v1/datamgr/block/{block_code}/kline/sync | POST | 同步板块日K线（腾讯仅回最近交易日 1 根，每日累积形成历史序列） | 腾讯 fqkline |
| 5.10 | /api/v1/datamgr/block/{block_code}/kline | GET | 查询板块日K线 | DB tencent_block_kline_daily |
| 5.11 | /api/v1/datamgr/block/kline/sync-from-stocks | POST | 批量同步板块K线：遍历成分股快照中的 block_code（每日收盘后跑一次累积） | 腾讯 fqkline |
| 5.12 | /api/v1/datamgr/tencent/quote-dates | GET | 腾讯全市场行情时序可用日期（倒序）+ 每日股票数 | DB tencent_stock_quote_daily |
| 5.13 | /api/v1/datamgr/tencent/quote-daily | GET | 某交易日腾讯全市场行情（trade_date/code/limit 过滤） | DB tencent_stock_quote_daily |
六、自选股 / 持仓 / 研究候选
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 6.1 | /api/v1/favorites | GET | 自选股列表（支持 status 参数筛选研究状态） | DB |
| 6.2 | /api/v1/favorites | POST | 添加自选（支持 status/notes/source 参数） | DB |
| 6.3 | /api/v1/favorites/{stock_code} | DELETE | 删除自选 | DB |
| 6.4 | /api/v1/favorites/check/{stock_code} | GET | 是否已在自选 | DB |
| 6.5 | /api/v1/portfolio/upload | POST | 上传持仓（图片/文本） | AI vision + DB |
| 6.6 | /api/v1/portfolio/holdings | GET | 持仓明细 | DB |
| 6.7 | /api/v1/portfolio/optimize | GET | 组合优化建议 | DB + LLM |
注：
/api/v1/candidates/*端点已弃用，功能合并至/api/v1/favorites。研究候选池通过status参数（research/watch/selected/rejected）实现四状态工作流。
七、MCP（Model Context Protocol）
双通道挂载：
/api/v1/mcp/*是管理端 REST（服务器配置与市场），/mcp是 FastMCP 的 Streamable HTTP 端点（JSON-RPC，不在/api/v1前缀下，也不进 OpenAPI）。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 7.1 | /mcp | POST | MCP Server（Streamable HTTP，JSON-RPC，9 个 xuangu_* 工具） | 多数据源 |
| 7.2 | /mcp/tools | GET | MCP 工具清单（REST 包装） | 多数据源 |
| 7.3 | /mcp/tools/call | POST | 调用单个 MCP 工具（REST 包装） | 多数据源 |
| 7.4 | /api/v1/mcp/servers | GET | 已配置的外部 MCP 服务器清单 | DB/SysConfig |
| 7.5 | /api/v1/mcp/servers | POST | 保存外部 MCP 服务器配置 | DB/SysConfig |
| 7.6 | /api/v1/mcp/marketplace | GET | MCP 市场目录（可安装项） | 内置清单 |
7.5 的请求体是信封，不是裸数组
{"servers": [...]} —— 直接 POST 裸数组会被 Pydantic 判成 422，
而前端曾因此"保存成功但配置从未落库"（GET /mcp/servers 一直返回空）。
八、TDX 直连数据层（自实现 TCP 协议 7709）
实时盘口主源（0x0547），备胎链路：DB 优先 → TDX 回源 → 降级提示； 连接池复用 + 记忆主机单点验证（冷启动 ~0.2s）+ 启动异步预热。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 8.1 | /api/v1/tdx/quotes/depth | GET | 五档盘口快照（实时，DB 缓存回退） | TDX 0x0547 |
| 8.2 | /api/v1/tdx/finance/snapshot | GET | 财务快照（DB 优先 → TDX 0x0010 回填） | TDX DB |
| 8.3 | /api/v1/tdx/fund-flow/history | GET | 历史资金流（Category 22） | TDX TCP |
| 8.4 | /api/v1/tdx/sync/run | GET | 手动触发同步任务（quote_depth/finance/fund_flow/market_stat/block_index/ipo） | TDX TCP → DB |
| 8.5 | /api/v1/tdx/sync/status | GET | 同步任务状态 | DB app_sync_log |
| 8.6 | /api/v1/tdx/stat/snapshot | GET | 全市场统计快照（PE/涨跌幅/趋势/52周高低等，DB 优先 → tdxstat 回源） | TDX cfg / DB |
| 8.7 | /api/v1/tdx/block/rank | GET | 板块涨跌排名（category=gn/hy/fg/zs，板块定义 → 指数行情 → 涨跌幅排序） | TDX TCP |
| 8.8 | /api/v1/tdx/block/index | GET | 板块指数定义检索（keyword 模糊，DB 优先 → tdxzs 回源） | TDX cfg / DB |
| 8.9 | /api/v1/tdx/ipo | GET | 新股申购日历（DB 优先 → xgsg 回源） | TDX cfg / DB |
| 8.10 | /api/v1/tdx/f10/category | GET | F10 目录（0x02CF，文本资料分类索引） | TDX TCP |
| 8.11 | /api/v1/tdx/f10/content | GET | F10 内容（0x02D0，GBK 文本资料分段读取） | TDX TCP |
九、fox 数据引擎（统一数据服务，Tushare pro.xxx 类比）
数据门面
app/services/fox_engine：/datamgr/fox/call为统一动态调用入口 （接口名+参数，白名单只读），/datamgr/fox/interfaces为 machine-readable 能力清单。 跨市场端点均为直连数据源（不落融合表），与/fox/call等价并提供直接 HTTP 入口。
融合层查询（fox_* DWD 表）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.1 | /api/v1/datamgr/fox/sync | POST | 触发 fox_ 融合层同步（全量/指定 codes） | 多源 → DB |
| 9.2 | /api/v1/datamgr/fox/status | GET | 融合层状态（各表行数/质量/最近任务） | DB |
| 9.3 | /api/v1/datamgr/fox/stock/{code} | GET | 个股全维度（master+profile+finance 近8期） | fox DB |
| 9.4 | /api/v1/datamgr/fox/stocks | GET | 批量融合摘要（逗号分隔，上限 500） | fox DB |
| 9.5 | /api/v1/datamgr/fox/stock/{code}/finance | GET | 财务指标序列（升序供绘图） | fox DB |
| 9.6 | /api/v1/datamgr/fox/stock/{code}/valuation | GET | 估值（最新融合行 + 近 N 期快照） | fox DB |
| 9.7 | /api/v1/datamgr/fox/stock/{code}/industry | GET | 行业归属（多口径） | fox DB |
| 9.8 | /api/v1/datamgr/fox/stock/{code}/holder | GET | 股东户数序列 | fox DB |
| 9.9 | /api/v1/datamgr/fox/stock/{code}/dividend | GET | 分红送转历史 | fox DB |
| 9.10 | /api/v1/datamgr/fox/stock/{code}/dragon-tiger | GET | 龙虎榜事件 | fox DB |
| 9.11 | /api/v1/datamgr/fox/stock/{code}/margin | GET | 融资融券日级序列 | fox DB |
| 9.12 | /api/v1/datamgr/fox/stock/{code}/block-trade | GET | 大宗交易历史 | fox DB |
| 9.13 | /api/v1/datamgr/fox/stock/{code}/announcements | GET | 公告历史 | fox DB |
| 9.14 | /api/v1/datamgr/fox/stock/{code}/news | GET | 新闻/研报列表 | fox DB |
| 9.15 | /api/v1/datamgr/fox/index/daily | GET | 批量指数日线（腾讯格式 codes） | fox DB |
| 9.15b | /api/v1/datamgr/fox/index/indicator/{code} | GET | 指数技术指标（MA/MACD/KDJ/BOLL/RSI，2026-09-06 新增） | fox DB → 腾讯 |
| 9.16 | /api/v1/datamgr/fox/index/daily/sync | POST | 触发指数日线同步 | 腾讯 HTTP |
| 9.17 | /api/v1/datamgr/fox/stock/{code}/kline-bar | GET | 多周期 K 线（week/month/quarter/year） | fox DB |
| 9.18 | /api/v1/datamgr/fox/stock/{code}/kline-bar/sync | POST | 触发单股多周期 K 线同步 | 腾讯 fqkline |
| 9.19 | /api/v1/datamgr/fox/market/dpyt | GET | 大盘云图个股快照（全市场~5200只） | fox DB |
| 9.20 | /api/v1/datamgr/fox/market/dpyt/tree | GET | 大盘云图行业树（三级结构） | fox DB |
| 9.21 | /api/v1/datamgr/fox/market/dpyt/sync | POST | 触发大盘云图同步 | JRJ dpyt API |
实时/信号路由（直连，不落库）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.25 | /api/v1/datamgr/fox/market/realtime-quote | GET | 实时行情快照（A股/ETF/港股/指数，上限 600） | 腾讯 qt.gtimg.cn |
| 9.26 | /api/v1/datamgr/fox/market/limit-up | GET | 涨停板池 | 东财 push2ex |
| 9.27 | /api/v1/datamgr/fox/market/industry-ranking | GET | 行业板块涨跌排名 | 腾讯 getRank |
| 9.28 | /api/v1/datamgr/fox/stock/{code}/lockup | GET | 限售解禁日历 | 东财 |
| 9.29 | /api/v1/datamgr/fox/market/northbound | GET | 北向资金实时概况 | 东财 |
外汇 / 期货（Tushare fx_* / fut_* 类比）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.30 | /api/v1/datamgr/fox/forex/quotes | GET | 关键汇率+贵金属实时（USD/CNY/黄金/白银） | 腾讯 |
| 9.31 | /api/v1/datamgr/fox/forex/list | GET | 全球外汇全量快照（51 货币对） | DB tencent_forex_info |
| 9.32 | /api/v1/datamgr/fox/futures/quotes | GET | 关键期货实时报价（7 大类） | 新浪 |
| 9.33 | /api/v1/datamgr/fox/futures/quote/{contract_code} | GET | 单品种期货报价（GC/CL 等） | 新浪 |
| 9.34 | /api/v1/datamgr/fox/futures/products | GET | 可用期货品种清单 | 内置 |
| 9.35 | /api/v1/datamgr/fox/futures/list | GET | 全球期货全量快照（50 品种，category 过滤） | DB tencent_future_info |
美股 / 港股（Tushare us_* / hk_* 类比）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.40 | /api/v1/datamgr/fox/us/quote/{symbol} | GET | 美股实时行情（含盘前/盘后） | Yahoo |
| 9.41 | /api/v1/datamgr/fox/us/kline | GET | 美股 K 线（period/interval） | Yahoo |
| 9.42 | /api/v1/datamgr/fox/us/fundamentals/{symbol} | GET | 美股基本面（财务/估值） | Yahoo |
| 9.43 | /api/v1/datamgr/fox/us/news/{symbol} | GET | 美股个股新闻 | Yahoo |
| 9.44 | /api/v1/datamgr/fox/us/search | GET | 美股代码搜索/补全 | Yahoo |
| 9.45 | /api/v1/datamgr/fox/us/intraday | GET | 美股日内分时 | Yahoo |
| 9.46 | /api/v1/datamgr/fox/us/stocks | GET | 美股板块全量（cdr/tec） | DB tencent_us_stock_info |
| 9.47 | /api/v1/datamgr/fox/hk/quote/{code} | GET | 港股实时行情 | Yahoo |
| 9.48 | /api/v1/datamgr/fox/hk/kline | GET | 港股 K 线 | Yahoo |
海外 / 国内宏观（Tushare 宏观分类类比）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.50 | /api/v1/datamgr/fox/macro/overview | GET | 全球宏观总览（指数/美债/汇率/加密/情绪） | 腾讯+Yahoo |
| 9.51 | /api/v1/datamgr/fox/macro/global-indices | GET | 海外主要指数实时（道指/纳指/恒生） | 腾讯 |
| 9.52 | /api/v1/datamgr/fox/macro/us-indicators | GET | VIX / 美债10Y / 美元指数 | Yahoo |
| 9.53 | /api/v1/datamgr/fox/macro/crypto | GET | 主流加密货币实时行情 | CoinGecko |
| 9.54 | /api/v1/datamgr/fox/macro/fear-greed | GET | 加密货币恐惧贪婪指数 | CoinGecko |
| 9.55 | /api/v1/datamgr/fox/macro/cn-overview | GET | 国内宏观指标聚合 | 新浪 datacenter |
| 9.56 | /api/v1/datamgr/fox/macro/cn/cpi | GET | 中国 CPI（月度） | 新浪 datacenter |
| 9.57 | /api/v1/datamgr/fox/macro/cn/pmi | GET | 中国 PMI（月度） | 新浪 datacenter |
| 9.58 | /api/v1/datamgr/fox/macro/cn/gdp | GET | 中国 GDP（季度） | 新浪 datacenter |
| 9.59 | /api/v1/datamgr/fox/macro/cn/m2 | GET | 中国 M2（月度） | 新浪 datacenter |
| 9.60 | /api/v1/datamgr/fox/macro/cn/social-financing | GET | 社会融资规模增量（月度） | 新浪 datacenter |
| 9.61 | /api/v1/datamgr/fox/macro/cn/lpr | GET | 中国 LPR（月度） | 新浪 datacenter |
| 9.62 | /api/v1/datamgr/fox/macro/cn/shibor | GET | SHIBOR（日度） | 新浪 |
基金 / ETF（Tushare fund_* 类比）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.70 | /api/v1/datamgr/fox/fund/rankings | GET | 基金业绩排行（fund_type/sort_by/top_n） | 东财天天基金 |
| 9.71 | /api/v1/datamgr/fox/fund/holdings/{fund_code} | GET | 基金持仓（前十大重仓股/行业配置） | 东财 |
| 9.72 | /api/v1/datamgr/fox/fund/etf-quote/{etf_code} | GET | ETF 实时行情（双源降级） | 东财/新浪 |
| 9.73 | /api/v1/datamgr/fox/fund/etf-kline/{etf_code} | GET | ETF/LOF 历史 K 线（day/week/month 前复权，days≤800；2026-09-06 新增，对齐 akshare fund_etf_hist_em） | 腾讯 fqkline → 新浪 getKLineData |
统一入口
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 9.80 | /api/v1/datamgr/fox/interfaces | GET | 引擎能力清单（machine-readable，只读白名单） | 注册表 |
| 9.81 | /api/v1/datamgr/fox/call | POST | 统一动态调用 {"interface": "...", "params": {...}} | 多源 |
| 9.82 | /api/v1/datamgr/fox/interfaces/search | GET | 自然语言检索接口（q + limit/dimension/readonly_only/kind）。双语料：kind=fox 引擎接口（可 /fox/call 调用）、kind=route 独立 HTTP 路由（直接 GET）；加权字段打分（名 100/10、doc 6、returns 5、维度 3、参数 2，全 token 命中 ×1.5）+ 2-gram 降级召回，精确名/路径置顶。未知接口名报错自动附最近候选 | 运行时（FOX_INTERFACES + app.openapi()） |
十、对标补齐的独立路由（akshare v1.18.96 差距分析落地，2026-09-20）
均为独立 Router（非
/datamgr管理端），并已同步登记进 fox 引擎能力清单 （/datamgr/fox/interfaces可查；_DELEGATED白名单说明缓存由下游 source_cache 负责）。
债券 / 股权风险 / 千股千评
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.1 | /api/v1/macro/bond-yield | GET | 中债国债收益率曲线（关键期限） | 东财 datacenter |
| 10.2 | /api/v1/macro/erp | GET | 股债利差 ERP（沪深300 盈利收益率 - 10Y 国债） | 腾讯 + 中债 |
| 10.2a | /api/v1/macro/policy-rates | GET | 货币政策与利率（LPR/准备金/存贷款基准/7天逆回购/Shibor/10Y + 动作时间线） | 东财 + 金十 + 央行公告 |
| 10.2b | /api/v1/macro/fiscal | GET | 财政与税收（税收收入 + 一般公共预算收入 + 支出累计） | 东财 datacenter + 财政部公报 |
| 10.2c | /api/v1/macro/tax-rates | GET | 现行税率速查（增值税/个税/企税/印花税参考表 + 变更历史） | 人工核实法定税率表 |
| 10.2d | /api/v1/macro/market-liquidity | GET | 资金面与拥挤度（前5%成交额占比/成交额与市值比/两融杠杆水位/FR·FDR 定盘利率） | 本地 K线聚合 + 东财 + 中国货币网 |
| 10.2e | /api/v1/macro/index-valuation | GET | 指数 PE 历史分位通道（上证/沪深300/创业板指，2017 至今） | 东财 RPT_VALUEMARKET |
| 10.2f | /api/v1/macro/macro-score | GET | 宏观可解释评分（机会 6 模块加权 × 风险折扣 → 建议仓位区间，阈值库内长历史自校准） | 本地落库序列（零 HTTP） |
| 10.2g | /api/v1/macro/macro-score/validation | GET | 评分 as_of 回放验证（曲线 + 仓位档 vs 上证 20 日前向收益分档） | 本地落库序列（零 HTTP） |
| 10.2h | /api/v1/macro/overview | GET | 全球宏观总览（指数/美债/汇率/加密/恐惧贪婪，各板块独立容错为 null） | 腾讯 + Yahoo + CoinGecko |
| 10.2i | /api/v1/macro/regime | GET | 宏观状态判读（增长/通胀/货币信用/市场利率四方向净分 + 投资时钟象限 + 驱动因素；缺失与陈旧项如实列出且不参与判定） | 本地 fox_macro_indicator（零 HTTP） |
| 10.2j | /api/v1/macro/regime/track | GET | 判读日账战绩（逐日判读 + 上证 T+5 前向收益曲线 + 按象限聚合；🔴 回放按「当时可见」截断，不放未来数据） | 本地 app_macro_regime_daily（零 HTTP） |
| 10.2k | /api/v1/macro/regime/industry-matrix | GET | 宏观维度 × 申万行业暴露矩阵（三分位分组组差 delta/se/weak，T+20 超额；已减当月全行业等权均值，只有相对含义） | 本地 fox_industry_index_daily + 宏观快照（零 HTTP） |
| 10.3 | /api/v1/risk/pledge-list | GET | 股权质押比例排行（全市场） | 东财 datacenter |
| 10.4 | /api/v1/risk/pledge/{code} | GET | 个股质押明细（质押笔数/比例/股东） | 东财 datacenter |
| 10.5 | /api/v1/risk/goodwill-list | GET | 商誉规模排行（全市场） | 东财 datacenter |
| 10.6 | /api/v1/risk/goodwill-overview | GET | 商誉总量/占比概览 | 东财 datacenter |
| 10.7 | /api/v1/risk/goodwill/{code} | GET | 个股商誉明细（商誉/净资产占比） | 东财 datacenter |
| 10.8 | /api/v1/risk/comment-list | GET | 千股千评排行（全市场，机构参与度/关注指数） | 东财 datacenter（已并入 fox_stock_wide） |
| 10.9 | /api/v1/risk/comment-summary | GET | 千股千评分档汇总 | 东财 datacenter |
| 10.10 | /api/v1/risk/comment/{code} | GET | 个股千股千评（含综合得分/主力成本） | 东财 datacenter |
可转债 / 指数 / 行业估值
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.11 | /api/v1/convertible-bond/dual-low | GET | 可转债双低排名（实时计算） | 东财 RPT_BOND_CB_LIST |
| 10.12 | /api/v1/convertible-bond/safety-rank | GET | 债底安全边际排行（YTM+评级+溢价率+年限四维加权） | 集思录（免登录） |
| 10.13 | /api/v1/convertible-bond/floor-distribution | GET | 低溢价池债性分布（YTM 分档 / 评级 / 强赎区家数） | 集思录 |
| 10.14 | /api/v1/convertible-bond/terms | GET | 可转债条款清单（回售/强赎/下修触发线） | 东财 datacenter |
| 10.15 | /api/v1/convertible-bond/{code} | GET | 单只转债条款详情 | 东财 datacenter |
| 10.16 | /api/v1/convertible-bond/{code}/ballot | GET | 转债票面利率与兑付安排 | 东财 datacenter |
| 10.17 | /api/v1/convertible-bond/{code}/fund-usage | GET | 转债募集资金用途 | 东财 datacenter |
| 10.18 | /api/v1/convertible-bond/{code}/dates | GET | 转债关键日期（转股/回售/到期） | 东财 datacenter |
| 10.19 | /api/v1/convertible-bond/{code}/bond-floor | GET | 单只转债债性画像（安全分四维拆解 / 距强赎空间 / 下修记录） | 集思录 |
| 10.20 | /api/v1/index/valuation/{symbol} | GET | 中证指数官方估值（PE/PB/股息率，如 000300） | 中证指数 csindex |
| 10.21 | /api/v1/index/weights/{symbol} | GET | 指数成分权重（中证/申万口径） | 中证指数 csindex |
| 10.22 | /api/v1/index/constituents/{symbol} | GET | 指数成分股清单 | 中证指数 csindex |
| 10.23 | /api/v1/industry/valuation | GET | 全行业估值分位（PE/PB 历史百分位） | fox 融合 + 腾讯 |
| 10.24 | /api/v1/industry/valuation/detail | GET | 单行业估值分位明细（近 N 年序列） | fox 融合 + 腾讯 |
公募 REITs / 港股财务 / 期货
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.25 | /api/v1/reit/list | GET | 全市场公募 REITs 列表（净值/IOPV/折溢价/份额/52周位置） | 腾讯（508xxx/180xxx 代码段扫描） |
| 10.26 | /api/v1/reit/kline | GET | REITs K 线（复权，day/week/month） | 腾讯 fqkline → 新浪 |
| 10.27 | /api/v1/reit/{code} | GET | REITs 详情（快照+阶段涨幅+同类对比） | 腾讯 |
| 10.28 | /api/v1/hk-finance/{code}/periods | GET | 港股报告期清单（96 期） | 东财港股 F10 |
| 10.29 | /api/v1/hk-finance/{code}/statement | GET | 港股三表（balance/income/cashflow，长表转宽表；金额为原报表币种） | 东财港股 F10 |
| 10.30 | /api/v1/hk-finance/{code}/indicator | GET | 港股主要指标（ROE/毛利率/负债率等，HKF10 预置列组） | 东财港股 F10 |
| 10.31 | /api/v1/hk-finance/{code}/overview | GET | 港股财务总览（报表科目 + 指标摘要） | 东财港股 F10 |
| 10.32 | /api/v1/futures/inventory/products | GET | 期货品种清单（74 个，东财仓单口径） | 东财 RPT_FUTU_POSITIONCODE |
| 10.33 | /api/v1/futures/inventory/rank | GET | 全品种注册仓单横截面（含增减；单位随品种不归一） | 东财 RPT_FUTU_STOCKDATA |
| 10.34 | /api/v1/futures/inventory/{code} | GET | 单品种仓单时序（区间高低/净变动） | 东财 RPT_FUTU_STOCKDATA |
| 10.35 | /api/v1/futures/position-rank | GET | 交易所持仓排名（exchange=shfe/cffex，前 20 会员三榜；DCE/CZCE/GFEX 未覆盖） | 上期所 JSON / 中金所 GBK CSV |
| 10.36 | /api/v1/futures/term-structure | GET | 期限结构（近月→远月整链 + 价差/年化持有收益/contango 判定） | 新浪 nf_ 批量（单请求整链） |
备用数据源（主链路之外的补充口径）
这三个源不是主链路备胎，而是主链路拿不到或需交叉校验的能力。 各自独立成败，响应里用
available显式区分「取不到」与「确实没有数据」—— 源故障渲染成空表格是最容易误导排查的做法。 页面入口：/alt-sources（侧栏「发现」面板）。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.37 | /api/v1/alt-sources/overview | GET | 三源状态总览（可用 / 需凭据 / 不可用 + 原因） | 聚合 |
| 10.38 | /api/v1/alt-sources/legulegu | GET | A 股整体估值（PE/PB 中位数与等权平均）+ 破净股 + 市场拥挤度 | 乐咕乐股（HTML 解析） |
| 10.39 | /api/v1/alt-sources/hk-ipo | GET | 港股新股 IPO（招股价/每手股数/超额认购倍数/首日与累计表现） | AAStocks + 东财首发资料 |
| 10.40 | /api/v1/alt-sources/private-fund | GET | 私募排行（净值/回撤/夏普） | 雪球（需 XUEQIU_COOKIE） |
关键口径（用错会得出错误结论，故写进速查）：
- 乐咕乐股是交叉校验源，不是替代。本仓已自算 ERP（
fox_erp_daily）与拥挤度 （fox_market_liquidity_daily），乐咕提供独立第三方口径用于对账——两者显著背离 往往说明本仓样本范围或剔除规则有问题。 - 港股 IPO 的两个源缺字段是真的缺：暗盘价与保荐人免费接口拿不到
（AAStocks 表格无此列、东财 JSON 返回
--），故接口与页面都不产出这两个字段。 - 雪球私募无凭据时
available: false+need_credential: true，属预期状态， 不是故障。配置见.env.example。
量化选股（因子打分）
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.41 | /api/v1/factor/factors | GET | 因子字典（11 个具名因子：口径/方向/真实度 real·partial·proxy） | fox_stock_wide |
| 10.42 | /api/v1/factor/presets | GET | 14 套预设策略（含 rationale 与 watchOut 风险提示） | 内置 |
| 10.43 | /api/v1/factor/screen | POST | 因子打分筛选（先过硬门控，被拦标的入 rejected 并给出原因） | fox_stock_wide |
行业分类（申万一级 / 二级）
口径：申万官方分类（
sw_index_meta155 类 = 一级 31 + 二级 124）。 代码列只存 801xxx 代码，行业名称单列存放（前端按sw_l1/sw_l2代码筛选、按名称展示）。 成交额占比的分母是「Σ31 个申万一级行业当日成交额」（denominator_complete标记是否满 31）， 与全市场成交额口径不同源，故只用于行业间横向比较。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.44 | /api/v1/industry/class/systems | GET | 可选分类体系（sw_l1 申万一级 / sw_l2 申万二级） | sw_index_meta |
| 10.45 | /api/v1/industry/class/list | GET | 分类清单（代码/名称/成分股数；代码列不写名称） | sw_index_meta + fox_industry |
| 10.46 | /api/v1/industry/class/ratio | GET | 行业成交额占比 + 近 1/2 年历史分位（占比口径，非绝对额） | fox_industry_index_daily |
| 10.47 | /api/v1/industry/class/kline | GET | 行业指数 K 线（含 amount_yi / ratio_pct 成交占比列，2021 起） | 申万官方 |
内置策略卡片 / 个股策略体检（2026-09-21）
与
/strategies（用户配置的规则/AI 策略）刻意分家：内置打分体系无参数、点开即用， 榜单与个股详情「策略体检」共用同一份进程缓存（services/strategy_audit.py）， 口径与各体系详情页一致（五维读app_dragon_score、VPA 同services.vpa、多因子同快照）。 体系故障降级neutral并附原因，不适用如实返回na（如五维只评涨停候选）。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.48 | /api/v1/builtin-strategies | GET | 4 张内置卡片（龙头五维/VPA/多因子/硬门控）+ 战绩徽章 | app_dragon_score / fox_stock_wide |
| 10.49 | /api/v1/builtin-strategies/{key}/board | GET | 某体系当前榜单（limit ≤200；整榜缓存 300s 后切片） | 同上 |
| 10.50 | /api/v1/stocks/{code}/strategy-audit | GET | 单股策略体检（三体系并集，与榜单同源同口径） | 同上 |
| 10.51 | /api/v1/builtin-strategies/{key}/performance | GET | 某体系历史战绩（逐日胜率/均收益 + 汇总，days 5~90） | app_builtin_board_pick / app_dragon_score |
10.44 口径（
services/builtin_track.py）：每日 18:15 收盘后把三榜 top 20 落痕app_builtin_board_pick（pending），过窗口后读本地fox_kline_daily回填前向收益 ——买入=入选日次一交易日开盘价、卖出=持有 5 个交易日收盘、胜=收益>0，零 HTTP。 gate 榜语义相反（排雷榜）：semantics="avoid"，看「被否标的均涨」，越跌越说明 门控拦得对，前端不硬套「胜率」。龙头五维不落新表，战绩代理dragon_review既有曲线 （断板日最低价口径，与其余三榜刻意不合并）。样本未满时overall.samples == 0属正常， 不伪造数字。榜单是收盘后落库口径（as_of为数据截止日），刻意不做盘中实时化。 该口径与形态战绩（10.45）共用唯一实现services/forward_return.py。
形态识别与形态战绩（2026-09-22）
识别器三层：
quant/chart_geometry.py（枢轴/边界线/缺口基元）←quant/chart_patterns.py（判据）←quant/structural_patterns.py（字段注册 + 统一入口 + 老鸭头/圆弧/杯柄）。 🔴 方向列（duck_buy/double_top/hs_bottom… ±100）只在突破首日给值； 度量列（duck_stage/triangle_kind/rectangle_height_pct…）是筛选条件， 判定成立期间持续给值。二者不可互当（见数据契约 §十三）。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.52 | /api/v1/quant/pattern-performance | GET | 各形态信号的前向收益战绩（days≤90、pattern 指定单个方向列；命中率按信号方向对齐，+100 看涨 / −100 看跌） | fox_stock_pattern_daily → fox_kline_daily |
| 10.53 | /api/v1/quant/pattern-performance/refresh | POST | 清形态战绩 + 形态目录缓存（手动刷新按钮） | 进程缓存 |
| 10.54 | /api/v1/quant/patterns/{code} | GET | 单股形态序列，含 structural（方向信号）/ duck（老鸭头度量）/ metrics（图形形态度量）三块；信号带 kind（event 当日新出现 / state 正在成立） | fox_stock_pattern_daily |
| 10.55 | /api/v1/quant/pattern-catalog | GET | 形态目录：分类（反转/持续整理/均线/K线组合）+ kind/direction/说明 + 最新信号日命中只数 + 近期战绩（/patterns 页与详情页卡片共用） | fox_stock_pattern_daily → fox_kline_daily |
10.45 口径（
quant/pattern_review.py）：不另起留痕表——fox_stock_pattern_daily本身就是留痕（PK(code,date)，方向列只写 ±100），不像fox_stock_wide是覆盖式快照 （那才是榜单必须落app_builtin_board_pick的原因）。命中率按方向对齐 （aligned = ret_5d × sign，>0 即走对），刻意不报浮亏——同一份max_drawdown_pct在 −100 的桶里含义翻转（成了最大浮盈）。只评测方向列：显式传duck_stage这类度量列 也被拒并返回说明，不静默当成信号回测。评测范围 = 15 个单根 K 线组合形态 + 16 个结构形态（2026-09-22 起，此前只评测结构形态）；单形态信号按日期倒序取MAX_SIGNALS_PER_KEY(3000) 条，被截断的形态在truncated_keys里如实标注 （十字星这类高发形态 90 天可达数万条）。10.48 目录（
quant/pattern_catalog.py）：元数据集中一处（PATTERN_CATALOG）， 中文名复用PATTERN_TABLE_FIELDS（与选股器同源，前端不再硬编码一份）。kind=state（圆弧底/圆弧顶/杯柄/鸭颈期）在成立期间持续给值，event只在当日出现； K 线图据此分色，避免状态型天天堆标记。duck_stage进目录但evaluable=false： 它是筛选条件不是信号，可筛可标注但不参与命中率统计。
回测成绩单（跨体系统一明细，2026-09-23）
把 9 套体系的留痕（龙头五维/内置三榜/形态/战法/量化策略/量化预设/智能选股规则策略） 统一成同一行契约 + 同一套汇总，服务四个入口：智能选股/量化选股/形态选股三页的 弹窗、战法与个股两张卡片。🔴 汇总与表格永远取自同一批行（后端按筛选后的行算）， 所以「命中率 60%」与用户在表里数出来的一致；
has_hit_rate=false的来源 （龙头五维买入价取断板日最低价 → 胜率恒 100%）前端不显示那个假数字，只给理由。 实现：services/scorecard.py（注册表SOURCES+ 300s 行缓存 + 分组等距抽样）。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.56 | /api/v1/scorecard/sources | GET | 来源目录：9 源元数据（口径/买入模型/是否有命中率）+ 分组 + 状态标签 + 全局 note | 进程内注册表 |
| 10.57 | /api/v1/scorecard/picks | GET | 某来源明细（source；筛选：date_from/to/status/group/hit/keyword/industry/评分·收益·回撤区间；sort+desc+page+size≤500） | 各源留痕表 |
| 10.58 | /api/v1/scorecard/breakdown | GET | 某来源按分组拆开的战绩（策略/预设卡片徽章用；同源内组间可比，跨源不可比） | 同上 |
| 10.59 | /api/v1/scorecard/overview | GET | 各来源摘要（卡片徽章，不含明细行） | 同上 |
| 10.60 | /api/v1/scorecard/stock/{code} | GET | 个股历史信号战绩（跨来源命中过该股的行 + 逐来源小计；days≤90、sources 限定） | 同上 |
10.50 口径：买入/卖出口径由各源自己声明（
buy_model），共用services/forward_return.py的只有内置三榜与量化预设（次日开盘买入/持有 5 个交易日收盘）；pending（窗口未满） 的行不提前结账，收益列为空，龙头五维会在extra.provisional里带临时值并标*。 明细被等距抽样时（truncated）面板顶部给出黄条 +coverage实际覆盖日期范围—— 汇总基于抽样后的行，这个事实必须看得见。quant_preset源对应每日 18:25 的preset_track任务（14 套因子预设各 top 20 →app_preset_pick_daily，不可回填）。
财报窗口（市场级业绩聚合，2026-10-06）
一屏回答「这个报告期谁在赚钱」：业绩预告聚合（预喜/预悲分档 + 明细）/ 业绩快报 / 行业盈利榜 / 个股盈利榜（净利额、净利同比两排序），前端
/earnings-window页。 实现services/earnings_window.py，纯本地落库零 HTTP，整页载荷缓存 600s； 数据由 18:50wholemarket_events_sync（预告/快报 RAW）与 16:00fox_daily_sync（财务指标）刷新，一天内稳定，故不做盘中实时化。🔴 三条口径（都有实测依据）：① 宇宙 =
fox_stock_wide——fox_finance_indicator含新三板/退市段（实测 2026-06-30 有 12,683 个代码、宽表宇宙内仅 5,581），不 JOIN 过滤会把新三板半年报混进行业合计；② 预告按指标优先级去重（归属净利润优先， 缺则净利润、扣非、任意；实测 2026-06-30 有 478 只带多条，直数会重复）；③ 行业 同比 = 合计口径（Σ本期 / Σ去年同期 − 1，只算两期都有数据的同一代码集；上年同期 合计 ≤ 0 写 NULL 不编数），个股同比分母 <100 万元标 NULL（小分母会算出 +186749% 的噪声）。数值单位一律亿元（前端不再换算）。
| § | 端点 | 方法 | 功能 | 数据源 |
|---|---|---|---|---|
| 10.61 | /api/v1/earnings-window/overview | GET | 财报窗口整页数据（period=YYYY-MM-DD 指定报告期，缺省 = 最新已披露；DB 不可用 503） | 本地落库（零 HTTP） |
十一、健康与诊断
健康端点在
/api/v1/health 下，裸 /health 恒 404探活/监控脚本必须打 http://localhost:6789/api/v1/health（/api/v1/health/ 是同义的 root 处理器）。
| § | 端点 | 方法 | 功能 |
|---|---|---|---|
| 11.1 | /api/v1/health | GET | 基础健康检查（进程存活 + DB 可用性） |
| 11.2 | /api/v1/health/liveness | GET | 存活探针（无依赖检查，给编排用） |
| 11.3 | /api/v1/health/readiness | GET | 就绪探针（缓存预热 / DB 连接） |
| 11.4 | /api/v1/health/datasources | GET | 各数据源健康计数与熔断状态（仅含已注册熔断器的源：行情主链路 + ai + database） |
| 11.5 | /api/v1/health/degradation-events | GET | 熔断器降级事件时间线（CircuitBreaker 状态跃迁流水，非"源A顶替源B"的替换关系）。?limit= 默认 50 / 上限 100；返回 {events: [...]}，时间逆序；进程内环形缓冲（容量 100），重启即清空 |
| 11.6 | /api/v1/health/inspect | GET | 深度巡检（逐源实调，慢，管理端用） |
| 11.7 | /api/v1/health/sources | GET | 数据源目录（全量清单 + 分组/风控面统计 + 交叉审计） |
| 11.8 | /api/v1/system/freshness | GET | 数据新鲜度体检（表 → 最新日期） |
| 11.9 | /api/v1/system/cross-source-check | GET | 跨源核对（官方口径 vs 融合值） |
11.4 与 11.7 的分工（别当成重复）
/health/datasources（11.4） | /health/sources（11.7） | |
|---|---|---|
| 回答什么 | 「此刻有没有在降级」 | 「本仓到底接了哪些源」 |
| 覆盖范围 | 仅已注册熔断器的源（5 个） | 全量 23 个（含无熔断器的资讯/宏观/交易所/备用） |
| 数据来源 | 熔断器运行时状态 | 声明式目录 source_catalog.py |
| 何时用 | 排查「为什么这会儿是降级」 | 排查「某个数据是谁给的」 |
健康端点全部裸返回，不套 JSON 信封
/api/v1/health 整体在 backend/app/core/envelope.py::_ENVELOPE_SKIP_PREFIXES
白名单里（设计如此：健康端点要能 curl 直读，且信封会把 sources[].status
这类结构破坏掉）。故 11.4~11.7 全部返回裸对象（无 ok/results 字段）。
前端拦截器对两种形态都透明（api/_shared.ts：ok === true && "results" in data
才拆包，否则原样透传），两侧都不必特殊处理。这不是遗漏，不要"修"它。
契约由 backend/tests/test_health_endpoint_contract.py 钉住。
数据源目录的交叉审计
/health/sources 的 fallback_audit 断言「降级链注册表里的每个源都在目录中出现」。
若 missing_in_catalog 非空，说明存在业务在用、但用户在可信度页看不到的真盲区，
页面会直接告警。两者是互补不是包含关系——注册表只登记参与主备竞争的 9 个源，
目录覆盖全部 23 个。
十二、数据源优先级与降级链
优先级 1a：腾讯财经 (HTTP) — 不封IP → K线/指数/估值快照/行业排名（2026-08-11 实测调整为主源）
优先级 1b：自实现 TDX 协议 (TCP 7709) — 不封IP → 实时盘口/资金流/财务快照（第一备胎；TDX 自实现，mootdx 命名已于 2026-10-06 移除）
优先级 2：东财 (HTTP) — 有风控 → 独有数据（龙虎榜/解禁/两融/大宗/股东户数/分红/研报/新闻/财务指标/涨停板）
— 资金流向/行业排名/估值**仅作末位兜底**，主源分别为 TDX/腾讯/腾讯
优先级 3：新浪/巨潮 (HTTP) — 低风险 → 财报三表/公告
优先级 4：申万宏源研究官方 (HTTP) — 低风险、有节流 → 行业分类清单/成分股/行业指数日线
完整的主源 → 备胎映射见代码
backend/app/services/data_sources/fallback_registry.py（35 个数据类型 × 多级降级链，是降级关系的权威注册表）。