FinDataHub 项目实施分析报告

一、实施总览

14.7M

数据总行数

5,751

股票覆盖

数据源

0.85

质量评分

微服务

100%

P1-P4 完成

阶段	内容	状态	关键指标
P1	采集层：双源交叉验证 + AKShare 修复 + 北交所重拉	DONE	匹配率 96-100%
P2	预处理层：7 步 Pipeline + 4 级门控 + 策略画像	DONE	质量分 0.85
P3	使用层：SDK 11 方法 + API 14 端点	DONE	4 层递进接入
P4	AI 接入：Skills + MCP 7 工具	DONE	自然语言直达数据
P5	云端扩展：阿里云 MySQL 同步 + 版本管理 + 血缘追踪	DONE	14.8GB 全量同步

二、数据规模与质量

stock_daily

12,670,167 行 · 5,751 只股票 · 2021-01-04 ~ 2026-08-07

stock_weekly

1,681,905 行 · 质量分 0.85

stock_monthly

395,487 行 · 质量分 0.85

fina_indicator

244,601 行 · 最新 ROE=2.65%

stock_basic

5,549 行 · 全市场股票基础信息

辅助表（6 张）

_data_issues / _table_meta / _retry_queue 等

图 1：本地数据规模（行数）

图 2：各板块股票分布

图 3：阿里云 RDS 数据分布 (MB)

三、双源交叉验证

图 4：TuShare vs AKShare 匹配率历史趋势

日期	对比对数	匹配率	差异	差异字段分布
2026-08-07	5,535	96.1%	216	pct_chg(217) / pre_close(101)
2026-07-01	5,511	99.8%	13	pct_chg(12) / pre_close(1)
2025-01-02	5,331	99.9%	3	pct_chg(2) / vol(1)
2024-01-02	5,241	99.9%	3	pre_close(3)
2023-01-03	4,927	96.7%	161	pct_chg(155) / pre_close(6)

差异主要集中在涨跌幅（pct_chg）和昨收价（pre_close）两个字段，成交量/成交额差异极小（共 6 条）。最新日（2026-08-07）匹配率偏低至 96.1%，可能是某数据源更新时序延迟导致。

四、数据质量校验

检查项	结果	实现
OHLC 关系违规	0 行	`cleaner.py` — 自动修正 highhigh / close>high
价格为负	0 行	`gate.py` — Gate3 BLOCK 拦截
AKShare 成交额异常	637 万行修正	`cleaner._fix_akshare_broken_amount`
科创板 vol 单位	688/689 ÷100	`cleaner._fix_akshare_star_vol`
AKShare 涨跌幅重算	从 close/pre_close 推导	`cleaner._recompute_akshare_pct_chg`
AKShare pre_close 时效	253,513 行更新	`fix_akshare_preclose.py`
北交所数据补齐	333 只 / 186,460 行	`em_fetch.py` — 新浪源直连

五、完整模块清单

层级	模块	文件	行数	职责
L1 采集	tushare_fetcher	`Services/tushare_fetcher/`	~800	TuShare Pro API 封装 + 幂等写入
	akshare_fetcher	`Services/akshare_fetcher/`	~1200	AKShare 腾讯/东财/新浪多接口路由
	DatabaseManager	`tushare_fetcher/core/db.py` `akshare_fetcher/core/db.py`	50+60	继承 BaseDatabaseManager，覆写配置路径
	RetryManager	`findatahub_core/retry.py`	~80	指数退避 + 熔断 + 失败队列
L2 预处理	DataCleaner	`findatahub_core/cleaner.py`	~200	5 个子步骤（类型修正/去重/字段清洗/OHLC/AK修复）
	DataImputer	`findatahub_core/imputer.py`	~80	3 种策略（ffill/linear/median）
	OutlierDetector	`findatahub_core/outlier.py`	~70	IQR/MAD 检测 + 标记列
	StatsAnalyzer	`findatahub_core/stats.py`	~100	描述性统计 + 缺失率 + 分布特征
	CorrelationAnalyzer	`findatahub_core/correlation.py`	~120	Pearson/Spearman + 冗余检测
	PCAProcessor	`findatahub_core/pca.py`	~90	PCA 降维 + Normalizer（3 种）
	QualityGate	`findatahub_core/gate.py`	~90	4 级门控 + BLOCK/WARN/INFO
	CrossValidator	`findatahub_core/cross_validator.py`	~150	OHLCV 8 字段双源对比
L3 使用	Python SDK	`findatahub/client.py`	~330	11 个方法（daily/weekly/monthly/fina/search/export 等）
	REST API	`findatahub/api.py`	~270	14 个端点（含健康监控）
	Skills 层	`findatahub/skill.md`	—	5 表 schema + 查询示例
	MCP 服务	`findatahub/mcp_server.py`	~210	7 个 MCP 工具（搜索/日线/财务/质量/统计等）
基础设施	Pipeline	`findatahub_core/pipeline.py`	~340	DAG 编排 + 并行执行 + 反馈回路
	BaseDatabaseManager	`findatahub_core/db.py`	~280	连接池 + 幂等 upsert + safe_identifier
	ProfileLoader	`findatahub_core/profile.py`	~50	YAML 策略画像加载（3 种）
	HealthMonitor	`findatahub_core/health.py`	~60	API 耗时/成功率 + REST 端点
P5 云端	CloudSyncWorker	`flows/cloud_sync.py`	~180	全量 + 增量同步 to RDS
	数据版本	`_data_versions`	—	版本号标记 + 回滚查询
	数据血缘	`_data_lineage`	—	Pipeline Step 自动记录行数/耗时

六、架构重构摘要

重构项	效果	状态
删除 alpha-common 废弃模块	减少 4 文件，消除混淆	DONE
两个 fetcher db.py 继承 BaseDatabaseManager	670 行 → 110 行（减少 83%）	DONE
bootstrap.py 移除反向依赖	核心层 0 import fetcher	DONE
FetchStepProtocol 协议	采集器通过接口注入 Pipeline	DONE
pyproject.toml 补声明	findatahub-client → findatahub-core	DONE
Docs 文档整理	10 文件 → 3 分类目录 + 3 README	DONE
Tests/ 提升到根级	5 端到端用例全部通过	DONE
设计文档合并	14 文档 → 10 （减少 29%）	DONE

七、最终目录结构

FinDataHub/
├── App/                          # macOS SwiftUI 桌面应用（29 文件）
├── Docs/                         # 文档中心
│   ├── README.md                 # 总索引
│   ├── pipeline/                 # 数据管道架构
│   │   ├── findatahub-data-pipeline.html    # 架构设计 + 规范（合并）
│   │   ├── rate_limit_pull_plan.md
│   │   └── EXECUTION_PLAN.md     # 已归档
│   ├── macos/                    # macOS App 设计
│   │   ├── DESIGN.md             # HIG 设计 + Liquid Glass（合并）
│   │   └── DEVLOG.md
│   └── tracking/                 # 项目管理
│       └── TODO.md               # 待办 + P1-P4 完成记录（合并）
├── Services/                     # 6 个微服务
│   ├── tushare_fetcher/          # TuShare 采集（db.py 50 行）
│   ├── akshare_fetcher/          # AKShare 采集（db.py 60 行）
│   ├── findatahub-core/          # 核心预处理（18 模块 + 6 flows）
│   ├── findatahub-client/        # SDK + API + MCP
│   ├── kuaixun-service/          # 快讯 API
│   └── kuaixun-frontend/         # 快讯 Vue.js 前端
├── Tests/                        # 跨层集成测试（5 用例）
├── Scripts/                      # 运维部署脚本
└── implementation-report/        # 本报告

八、架构合规状态

核心铁律：依赖单向流动（采集层 → 核心层 → 使用层）
✅ 12 个核心模块 0 反向依赖
✅ FetchStepProtocol 协议（依赖倒置）
✅ pyproject.toml 全部声明
✅ 两个 fetcher db.py 继承 BaseDatabaseManager
✅ bootstrap.py 使用 BaseDatabaseManager 直连

反向依赖

Service（删1）

策略画像

14.8GB

RDS 同步