产品总览与页面地图
概述
鲸鱼选股（XuanGu）是一个面向 A 股个人投资者的智能分析工作台：本地/私有部署，
数据多源降级采集 + 每日全市场落库，分析与决策环节由「确定性规则在前、大模型在后」的
分层完成。前端是 React 19 SPA（src/），后端是 FastAPI（backend/app/），
两侧只经 http://localhost:6789/api/v1 一条 HTTP 边界通信。
本文给出功能全景与页面地图：所有路由、每个页面做什么、依赖哪个后端模块。 适合新接手的开发者建立整体心智，也适合作为产品评审的对照清单。
功能分组
侧边栏（src/components/layout/Sidebar.tsx）分「首页」固定组 + 选股 / 行情 / 资讯
三个核心组 + 一个「发现」面板。管理员项（任务中心、数据管理）经 admin 与
菜单可见性配置双重过滤。
| 分组 | 项目 |
|---|---|
| 首页 | 首页（AI 搜索 · 市场速览） |
| 选股 | 一句话选股、智能选股、量化选股、今日信号 |
| 行情 | 市场概览、板块中心、行情中心、涨停板 |
| 资讯 | 今日头条 |
| 发现 | 社区·大V复盘、游资心法、持仓AI巡检、热搜聚合、可转债、财报窗口、备用数据源、投资检查清单、监控中心、任务中心（admin）、我的收藏、横向对比、条件选股、形态选股、回测系统、交易日志、我的持仓、数据可信度、AI用量（admin）、数据管理（admin）、数据库管理（admin） |
页面地图
路由定义在 src/App.tsx：主应用 74 条（:173-252，含 5 条重定向壳 + 1 条兜底）
- 鉴权页全屏 3 条（
:332-334，不套侧边栏外壳），合计 77 条路由 / 71 个真实页面。 重定向壳：/skills→/nl-pick、/strategy-center→/backtest， 以及/login、/register、/verify-email→/（登录态已由鉴权块接管）。 除首页与鉴权页外全部React.lazy()懒加载；/ai-usage、/datamgr、/dbadmin与/tasks外层包AdminRoute（非管理员Navigate to="/"）。 "后端模块"列为该页取数所依赖的backend/app/api/*.py。
首页与对话
| 路由 | 页面 | 职责 | 后端模块 |
|---|---|---|---|
/ | pages/Home.tsx | AI 搜索 + 市场速览（热门股、板块热力图） | market |
/ai-chat | pages/AIChat.tsx | 多轮 AI 对话 / SOP 分析（SSE 流式） | chat |
/morning-note | pages/MorningNote.tsx | 次日晨报（AI 生成 / 降级稿） | morning |
/daily-review | pages/DailyReview.tsx | 当日收盘复盘 | review |
/news/:source/:newsKey | pages/NewsDetail.tsx | 新闻详情（财联社电报 / 同花顺快讯 / 全球资讯） | catalyst |
/hot-trending | pages/HotTrending.tsx | 多平台热搜聚合（股票/财经/科技/社交四榜 + 全部） | hot_trending |
/catalyst | pages/CatalystCalendar.tsx | 今日头条 / 财联社电报与催化剂事件 | catalyst |
个股与指数
| 路由 | 页面 | 职责 | 后端模块 |
|---|---|---|---|
/analysis/:code | pages/Analysis.tsx | 个股详情（行情/K 线/财务/行业对比） | stocks |
/analysis/:code/finance | pages/FinancialDetail.tsx | 财务明细 | stocks |
/analysis/:code/module/:module | pages/StockModuleDetail.tsx | 个股专题模块（风险/高管持股/机构调研/同花顺 F10） | risk / signal / ths_f10 |
/analysis/:code/announcement/:annKey | pages/AnnouncementDetail.tsx | 公告详情 | signal |
/index-detail/:code | pages/IndexDetail.tsx | 指数详情（fox 指数日线 + 指标） | index_data / market |
/index-constituents/:code | pages/IndexConstituents.tsx | 指数成分股 | index_data |
/etf-center | pages/EtfCenter.tsx | ETF 中心 | etf |
/etf/:code | pages/EtfDetail.tsx | ETF 行情与持仓 | etf |
/dimension/:dimKey | pages/DimensionAnalysis.tsx | 五维分析（国家意志/时代潮流/行业拐点/竞争格局/认清阶段），走 /chat/ask/stream 实时研判 | chat |
选股与工作流
| 路由 | 页面 | 职责 | 后端模块 |
|---|---|---|---|
/nl-pick | pages/NlPick.tsx | 自然语言一句话选股 | screener（/screener/nl-find） |
/screener | pages/Screener.tsx | 条件 DSL 选股 + 方案管理 | screener |
/factor-pick | pages/FactorPick.tsx | 多因子打分选股 + 预设策略 + 战绩 | factor / scorecard |
/patterns | pages/PatternSelect.tsx | 形态选股（左形态目录 / 右结果） | quant（patterns / pattern-performance）+ screener |
/rule-pick、/rule-pick/:strategyId | pages/SmartPick.tsx / SmartPickDetail.tsx | 规则选股（策略池批量跑，流式） | strategies / builtin_strategies |
/rule-pick/debate | pages/Debate.tsx | 规则选股辩论（多空对抗式研判） | strategies |
/tactics | pages/TacticSignals.tsx | 今日信号（6 战法全市场扫描） | tactics |
/trend-discovery | pages/TrendDiscovery.tsx | 趋势选股（板块连续强势榜 /sectors/streak） | sectors |
/chokepoint | pages/ChokepointSelect.tsx | 卡脖子选股（供应链瓶颈框架） | chokepoint |
/limit-up-reason | pages/LimitUpReason.tsx | 涨停归因 | market |
/backtest | pages/Backtest.tsx | 回测实验室（Tab 外壳，面板在 components/backtest/） | backtest_lab |
/compare | pages/compare/ComparePage.tsx | 多股横向对比 | compare |
/favorites | pages/Favorites.tsx | 我的收藏与研究候选池（四状态工作流：研究/关注/已选/已弃，/candidates 重定向至此） | favorites |
/thesis | pages/ThesisTracker.tsx | 我的持仓与投资论点 | portfolio |
/position-center | pages/PositionCenter.tsx | 持仓中心 | portfolio |
/trade-journal | pages/TradeJournal.tsx | 交易日志 | portfolio |
/portfolio-inspection | pages/PortfolioInspection.tsx | 持仓 AI 巡检 | portfolio_inspection |
/mastery | pages/Mastery.tsx | 游资心法 | mastery |
/pattern-similarity | pages/PatternSimilarity.tsx | 形态相似度 | pattern_similarity / quant |
/checklist/* | pages/Checklist/ | 投资检查清单（模板 + 作答记录） | checklist |
行情与板块
| 路由 | 页面 | 职责 | 后端模块 |
|---|---|---|---|
/realtime | pages/RealtimeMarket.tsx | 实时大盘看板（情绪/分布/资金流） | market / realtime |
/dashboard | pages/Dashboard.tsx | 大盘总览 | market |
/market-center | pages/MarketCenter.tsx | 全 A 行情中心（宽表榜单） | datamgr（fox 宽表）/ stocks |
/market-treemap | pages/MarketTreemap.tsx | 市场矩阵（Treemap） | market |
/auction | pages/Auction.tsx | 集合竞价 | market |
/crowding-detail | pages/CrowdingDetail.tsx | 拥挤度详情 | market |
/annual-heatmap-detail | pages/AnnualHeatmapDetail.tsx | 年度热力图 | market |
/zhangtingban | pages/Zhangtingban.tsx | 涨停板（板块 + 打板情绪） | market |
/limit-ladder | pages/LimitLadder.tsx | 涨停连板天梯 | market |
/sector-center | pages/sector/SectorCenter.tsx | 板块中心（热点/列表/分类体系） | sectors / industry |
/sector-center/sw/:system/:code | pages/sector/IndustryDetail.tsx | 申万体系行业详情 | industry |
/sector-center/concept/:code | pages/sector/ConceptDetail.tsx | 概念板块详情 | sectors |
/sector-center/:code | pages/sector/SectorDetail.tsx | 通用板块详情 | sectors |
/bonds | pages/ConvertibleBond.tsx | 可转债（债底安全边际/双低/条款/详情） | convertible_bond |
/earnings-window | pages/EarningsWindow.tsx | 财报窗口（业绩预告/快报聚合、行业与个股盈利榜） | earnings_window |
/alt-sources | pages/AltSources.tsx | 备用数据源（乐咕乐股估值对账/港股新股IPO/私募排行） | alt_sources |
/data-trust | pages/DataTrustCenter.tsx | 数据可信度中心（可信度评分 / 数据源目录 / 源状态 / 新鲜度 / 降级时间线 / 主动探测）。评分权重公开（源状态 60% + 新鲜度 40%），覆盖不足时不出分 | health / system |
/global-macro | pages/GlobalMacro.tsx | 全球宏观指标与发布日历 | macro |
/global-market | pages/GlobalMarket.tsx | 海外市场（指数/期货/外汇/美股） | futures / 外部行情 |
/monitor-center | pages/MonitorCenter.tsx | 监控规则与事件（含持仓异动通知） | monitor |
/policy-rates | pages/PolicyRates.tsx | 政策利率（LPR / Shibor / 国债收益率长序列） | macro |
/news-radar | pages/NewsRadar.tsx | 消息面雷达（规则判读 + 规则级战绩自学习） | news_signal |
/community | pages/Community.tsx | 社区·大V复盘 | bigv |
/commodity | pages/CommodityCenter.tsx | 商品中心（现货-期货基差） | commodity |
管理与设置
| 路由 | 页面 | 职责 | 后端模块 |
|---|---|---|---|
/ai-usage | pages/AiUsage.tsx | AI 用量统计（模型调用量 / Token 消耗 / 配额）管理员 | ai_usage |
/datamgr | pages/DataManager/ | 数据管理（统计/同步日志/下载/新鲜度/数据源探测）管理员 | datamgr |
/dbadmin | pages/DbAdmin/ | 数据库管理（表浏览 / 建表删表 / 批量与对象编辑 / SQL 工作台与导入导出，独立窗口打开）管理员 | db_admin |
/tasks | pages/TaskCenter/ | 任务中心（总览/任务列表/运行历史/日志流/运维动作）管理员 | tasks |
/settings/* | pages/Settings/ | 设置（账户/AI 模型/MCP/SMTP/菜单可见性/关于/数据配置） | auth / settings / mcp / health |
/notifications | pages/Notifications.tsx | 通知中心 | notifications（当前前端用本地态，见用户体系） |
/login /register /verify-email | pages/auth/ | 鉴权页（已登录访问则跳回 /） | auth |
* | pages/NotFound.tsx | 未知地址兜底 | — |
两条历史重定向
/skills → /nl-pick、/strategy-center → /backtest（策略中心能力已并入回测系统，
保留路由只为兼容书签与外链）。
三条典型投研工作流
| 工作流 | 时点 | 关键页面 | 数据依赖 |
|---|---|---|---|
| 盘前定调 | 06:30 晨报 → 09:15 | /morning-note → / → /nl-pick | fox_market_snapshot（休市 TTL 3600s）+ 昨日收盘数据 |
| 盘中跟踪 | 09:30-15:00 | /realtime /zhangtingban /dimension/* /monitor-center | TDX TCP 实时 + SSE 推送，缓存 TTL 10~30s |
| 收盘复盘 | 15:30-19:30 | /daily-review /factor-pick /backtest /tasks | fox 三域融合 → quant_calc → 留痕任务，全链路在任务中心可观测 |
产品设计原则
这五条是全站一致的硬约定，新增功能时必须延续：
| 原则 | 落地方式 |
|---|---|
| 规则在前 · LLM 在后 | 确定性门控（scoring/gates.py）先否决，再谈打分与研判；LLM 不参与"能不能买"的第一道判断 |
| DB 优先读取 | 页面秒开靠本地落库：三级读路径（SQLite 快路径 → Parquet 镜像 → MySQL），外部 API 只在缺失时回源 |
| 诚实标注降级 | 非本次模型实时调用的产出必须标来源：local_rule（琥珀「本地规则口径」）/ agent_batch·deep_ai（中性蓝「助手离线」）/ 缺省（「AI 生成」） |
| 口径单一 · 数字可回溯 | 同一份事实只留一个来源（战绩口径统一在 services/forward_return.py）；汇总与表格取自同一批行，前端一个收益数字都不自己算 |
| 来源标签到段 | 载荷级 _source 只记主源，多源拼装必须打段级标签（_bins_source 等），详见常见问题 |
图表叠加层的展示纪律
K 线叠加标注（压力支撑、缠论中枢、形态关键位、笔·线段）一律仅悬浮提示显示， 不在主图常驻文字——常驻标注会把图面压成文字墙并遮挡 K 线。
前端基础设施
| 关注点 | 实现 |
|---|---|
| 应用外壳 | src/main.tsx（React Query Provider + 全局 ErrorBoundary + 主题初始化）→ src/App.tsx（AuthGate → 侧边栏/内容区 → 路由） |
| 服务端状态 | TanStack Query；lib/queryClient.ts 按 DATA_TIERS（realtime/hotChanges/daily/slow/static）分档 staleTime/gcTime，默认 5min/30min、retry≤2（NOT_FOUND/ABORTED/CIRCUIT_OPEN 不重试）、窗口聚焦不重刷 |
| 交易时段轮询 | hooks/useTradingQuery.ts——盘中用 tradingInterval（SSE 已连且命中失效白名单则降为 max(60s, tradingInterval) 兜底），休时用 idleInterval，页面隐藏即停。任务中心不可用它（任务在盘后/夜间跑） |
| 客户端状态 | jotai（src/store/：atoms / authAtoms / notificationAtoms / quotaAtoms），组件级 UI 状态仍用 useState。状态分层规范见 reference/frontend-state-layering.md |
| 请求层 | lib/api.ts axios 实例（baseURL=/api/v1，超时 20s）；请求拦截器加 Authorization: Bearer；响应拦截器做信封解包并回补被抬到顶层的 items/total；401 → 清 token + 弹「登录已过期」跳 /login |
| 主题 | .dark 类唯一写入者 lib/themeMode.ts（FOUC 由 index.html 内联脚本抢跑），主色 CSS 变量由 lib/theme.tsx 的 ThemeProvider 提供 |
| 样式 | Tailwind CSS 4 utility-first，禁止内联 style；components/ui/ 沿用 shadcn 风格 kebab-case 文件名 |
| 路径别名 | @/ → src/（tsconfig.json + vite.config.ts） |
| 目录规模 | src/pages/ 顶层 58 个 .tsx（含 4 个测试文件）+ 10 个子目录，递归共 141 个非测试 .tsx；src/components/ 36 个子目录（layout/ui/charts/market/sector/earnings/backtest/scorecard/tasks…） |
移动端
mobile/ 是独立的 Flutter（Dart 3.12+）应用，与 Web 前端同一直连 /api/v1，
不共用任何代码：lib/features/ 承载智选/行情/个股/持仓等业务模块（原生 + WebView 混合），
lib/core/ 提供 dio+SSE 网络、go_router、主题与 JS Bridge。
改动后必须跑 flutter analyze + flutter test（含五 tab 启动冒烟测试），
混合架构与 Bridge 协议见 mobile/README.md。