gao
05635b76b9
状态： - 9 个 sync task（stock_basic / kline_daily / kline_index / kline_5min / moneyflow / industry_sector / sector_features / share_snapshot / market_regime） - 数据源：baostock + mairui + 雪球(pysnowball) + 新浪（4 个） - 项目级约束：永远不用 akshare（已落实） - kline_5min 改用 DB 快照统一全量/增量逻辑 - 零后端 Chrome 扩展 xueqiu_sync（独立项目）
78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# market_data_sync
|
||
|
||
A 股市场数据**定时同步与管理**框架。
|
||
|
||
把 `akshare` / `baostock` / 新浪 / 雪球 / 麦蕊智数 等多个数据源接入到 MySQL 库，提供：
|
||
- 后台线程调度器（time-based + interval-based，交易日感知）
|
||
- 多数据源 + 自动降级 + 健康度监控
|
||
- `dataset_registry` 同步状态机（运行中 / 成功 / 失败 / 中断恢复）
|
||
- FastAPI 管理接口（手动触发、状态查询、失败重试）
|
||
- CLI 入口（手动跑任务、查看状态）
|
||
|
||
> 📖 详细架构说明见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 1. 准备环境（首次）
|
||
cp .env.example .env # 编辑 .env 填写真实 MySQL 凭据 + XUEQIU_TOKEN
|
||
chmod +x start.sh
|
||
./start.sh # 自动创建 .venv + 装依赖 + 启动 API（http://localhost:8100）
|
||
|
||
# 2. 常用命令
|
||
./start.sh worker # 仅启动调度器（无 web）
|
||
./start.sh list # 列出所有同步任务
|
||
./start.sh sync kline_daily # 手动触发一次（dataset_id 即可）
|
||
./start.sh status # 查看调度器/数据源/同步任务状态
|
||
./start.sh datasources # 查看数据源健康度
|
||
./start.sh reseed # 重新 seed 默认配置到 config 表
|
||
|
||
# 3. 一键全量同步（首次接入）
|
||
python bin/runall_once.py
|
||
|
||
# 4. 跑测试
|
||
.venv/bin/pytest tests/ -v
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
app/
|
||
├── core/ # 核心抽象（config / db / sync / scheduler / datasource base）
|
||
├── sources/ # 数据源实现（5 个）
|
||
├── tasks/ # 同步任务实现（8 个）
|
||
├── api/ # FastAPI 管理接口
|
||
└── entrypoints/ # 进程入口（cli + worker）
|
||
bin/ # 一次性脚本
|
||
docs/ # 架构文档
|
||
tests/ # 单元测试
|
||
```
|
||
|
||
## 内置同步任务
|
||
|
||
| dataset_id | 触发时间 | 说明 |
|
||
|---|---|---|
|
||
| `stock_basic` | 交易日 09:00 | 全市场股票基础信息 + 股本 |
|
||
| `kline_daily` | 交易日 15:40 | 增量日 K 线（OHLCV，多源交叉） |
|
||
| `kline_index` | 交易日 15:50 | 六大指数日线 |
|
||
| `kline_5min` | 交易日 16:00 | 增量 5 分钟 K 线 |
|
||
| `moneyflow` | 交易日 16:30 | 资金流（主力/大/中/小单净额） |
|
||
| `industry_sector` | 周一 09:30 | 股票-行业映射（Baostock） |
|
||
| `share_snapshot` | 交易日 09:30 | 股本快照（雪球） |
|
||
| `market_regime` | 交易日 16:00 | 市场情绪（衍生源） |
|
||
|
||
## 添加新数据源
|
||
|
||
1. 在 `app/sources/` 新建 `my_source.py`，继承 `DataSource`
|
||
2. 在 `app/core/datasource/registry.py` 的 `build_default_registry()` 注册
|
||
|
||
## 添加新同步任务
|
||
|
||
1. 在 `app/tasks/` 新建 `task_xxx.py`，继承 `SyncTask`，设置 `dataset_id`
|
||
2. 在 `app/tasks/__init__.py` 的 `TASKS` 字典注册
|
||
3. （可选）在 `app/core/sync/registry.py` 的 `SYNC_DEFINITIONS` 加条目
|
||
|
||
## License
|
||
|
||
私有
|