# 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

私有