README.md

---
title: Quant Unified Monitor
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.9.1
python_version: 3.11
app_file: app.py
pinned: false
---

# 量化交易统一系统 (Quant Unified)

本仓库整合了所有量化交易相关的组件，包括管理应用、策略仓库、后端服务和基础库。

## 目录结构 (中文化重构版)

- **应用 (应用/)**: 各种管理与展示应用
  - **qronos/**: 量化交易管理平台（Web 前端 + Python 后端）
    - 提供策略管理、回测分析、实盘监控的网页界面。
    - 启动方式: 
      - 后端: `cd 应用/qronos && source .venv/bin/activate && python -X utf8 main.py`
      - 前端: `cd 应用/qronos && npm run dev`

- **策略仓库 (策略仓库/)**: 各种交易策略实现
  - **二号网格策略/**: 网格交易策略实现，包含回测与实盘。
    - 运行回测: `cd 策略仓库/二号网格策略 && python -X utf8 backtest.py`
  - **一号择时策略/**: 包含选币和择时逻辑。
  - **三号对冲策略/**: 双向对冲策略。

- **服务 (服务/)**: 核心实盘与回测服务
  - **firm/**: 实盘交易核心服务，提供底层交易、行情和评估功能。

- **基础库 (基础库/)**: 项目通用的基础组件
  - **common_core/**: 包含风控、配置加载、工具函数等核心模块。

- **测试用例 (测试用例/)**: 单元测试与集成测试脚本。

- **系统日志 (系统日志/)**: 统一存储各组件运行产生的日志。

## 云端采集与数据同步 (New)

本系统支持在 Hugging Face Spaces 上进行 7x24 小时自动行情采集，并自动同步到 Hugging Face Dataset。

### 1. 云端配置 (Hugging Face)
在 Space 的 **Settings** -> **Variables and secrets** 中添加以下 Secrets：
- `SUPABASE_URL`: 你的 Supabase 项目 URL
- `SUPABASE_ANON_KEY`: 你的 Supabase Anon Key
- `HF_TOKEN`: **必须**。具有 `Write` 权限的 Hugging Face Token，用于将数据上传到 Dataset。

### 2. 数据流向
1. **采集**: `服务/数据采集/启动采集.py` 实时采集 Binance 数据并保存为 `.parquet` 碎片。
2. **整理**: `app.py` 每 12 小时触发一次 `整理行情数据.py`，将碎片合并为每日文件。
3. **同步**: 整理完成后，自动运行 `hf_sync.py` 将数据推送到数据集 `chenchuanshen/Quant_Market_Data`。

### 3. 本地获取数据
在本地项目根目录下运行：
```bash
python 下载云端数据.py
```
该脚本会自动对比云端与本地差异，只下载新增的行情数据。

## 开发指南

1. **环境准备**: 建议使用 Python 3.14+ 环境。
2. **导入机制**: 项目使用了 `sitecustomize.py` 钩子，允许直接从顶级目录导入，例如 `import common_core` 或 `from 策略仓库.二号网格策略 import ...`。
3. **编码规范**: 强制使用 UTF-8 编码。函数名、变量名推荐使用中文命名（符合“编程导师”教学规范）。
4. **单体仓库**: 本仓库采用 Monorepo 结构，请直接在根目录打开 IDE 进行开发。