技术文档鲸鱼选股 技术文档
A股价值投资分析平台 —— 集成多源实时行情数据、AI 智能分析与市场情绪监控。 这里记录它的架构分层、数据源降级链、数据契约与 API 形态。
- FastAPI · Python 3.14
- React 19 · Vite
- MySQL 8
- 腾讯 / TDX 多源降级
- fox 融合层
文档导航
按主题分八个板块，点击卡片进入对应分类入口文档：
产品与能力
页面地图与投研工作流、量化打分体系、AI 能力链路、用户体系与通知
架构设计
系统分层、融合引擎、数据模型、数据流转、缓存策略与任务/进程模型
数据源集成
各数据源接入方式、优先级与降级链（腾讯 HTTP 与自建 TDX TCP 为主源）
可靠性与性能
错误处理体系、熔断器与性能优化
数据管理操作
数据下载、同步、清理等管理操作调用示例（需管理员权限）
API 参考
REST API 接口文档（Base URL: http://localhost:6789/api/v1）
速查手册
端点路由全量索引、数据契约（分层/单位/血缘）、数据源覆盖对照
配置与开发指南
环境变量配置、文档维护规范与常见问题
按角色快速开始
| 你是谁 | 先读这三篇 |
|---|---|
| 新接手的开发者 | 产品总览与页面地图 → 数据管理架构 → 配置指南 |
| 只关心数据对不对 | 数据流转（任务时序） → 数据模型总览 → 数据契约 |
| 调接口 / 找端点 | 端点路由速查 → API 参考 · 行情 → 数据源覆盖对照 |
| 调信号 / 改打分 | 量化选股与打分体系 → 数据流转 → API 参考 · 行情 |
| 排查线上问题 | 任务中心与进程模型 → 常见问题 → 错误处理体系 |
| 接大模型 / 写稿 | AI 能力架构 → 配置指南 → 数据源集成 |
技术栈概览
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端 | React + Vite + TailwindCSS | macOS 风格玻璃拟态 UI |
| 移动端 | Flutter（原生 + WebView 混合） | 与 src/ 同直连 /api/v1 |
| 后端 | FastAPI + SQLAlchemy | 异步 Python 服务，路由自动发现注册 |
| 数据库 | MySQL 8+ | 行情快照 + 基础信息持久化（缺失时降级 mock 模式） |
| 数据源 | 腾讯 / TDX / 东财 / 新浪 / 巨潮 / 申万 | 多级降级链（腾讯 HTTP 与自建 TDX TCP 为主源） |
| 数据引擎 | fox_ 融合层 | ODS → DWD 多源交叉验证，应用只读融合结果 |
| AI | LLM API | 晨报 / 复盘 / 智能选股 |
核心设计理念
- 多源降级：任何单一数据源故障不影响整体可用性
- 零额外依赖：直连数据源 API，不依赖 AkShare 等重量级封装库
- 防封策略：编号主机轮转、请求限流、403 不重试、熔断器保护
- 数据标准化：所有数值字段通过
safe_float()安全转换，杜绝异常值穿透 - 单一事实源：同一主题只在一处文档维护，代码与文档同一次提交更新（见文档维护规范）