构建期货数据采集与三层打分系统

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

使用说明.md

@@ -0,0 +1,161 @@
+# 期货行情分析系统 — 使用说明
+
+基于 Docker + Python(tushare) + Go 的中国期货行情分析系统。当前阶段已实现数据采集与三层加权打分模型。
+
+## 环境准备
+
+- Docker >= 20.10
+- Docker Compose >= 2.0
+- (可选) sqlite3 CLI 用于本地查库
+
+## 快速开始
+
+### 1. 配置 tushare token
+
+将 token 写入 `tushare/.env`：
+
+```bash
+echo "TUSHARE_TOKEN=你的token" > tushare/.env
+```
+
+该文件已被 gitignore 排除，不会进入版本库。
+
+### 2. 启动并跑默认合约
+
+```bash
+docker-compose run --rm tushare
+```
+
+默认执行 `FG2609.ZCE`（玻璃期货 2609 合约），流程：
+1. 从 tushare 拉取合约日线数据
+2. 写入 SQLite `data/futures.db`
+3. 运行三层打分模型
+4. 保存打分结果并输出到 stdout
+
+### 3. 跑其他合约
+
+```bash
+# 螺纹钢 2510 合约（上期所）
+docker-compose run --rm tushare python -m src.main RB2510.SHF
+
+# 铁矿石 2601 合约（大商所）
+docker-compose run --rm tushare python -m src.main I2601.DCE
+```
+
+## 三层打分模型
+
+### 综合分数公式
+
+```
+综合分数 = (短期动力 × 0.4) + (中期趋势 × 0.35) + (长期结构 × 0.25)
+```
+
+### 1. 短期动力（7 日窗口，权重 0.4）
+
+逐日打分后取均值：
+
+| 持仓变化 | 价格方向 | 得分 |
+|---------|---------|------|
+| 增仓 | 上涨 | 100（多头主动进攻） |
+| 增仓 | 下跌 | 0（空头主动进攻） |
+| 减仓 | 上涨 | 70（空头撤退） |
+| 减仓 | 下跌 | 30（多头撤退） |
+| 持平（\|变化\|<1%） | 上涨 | 60 |
+| 持平（\|变化\|<1%） | 下跌 | 40 |
+
+### 2. 中期趋势（15 日窗口，权重 0.35）
+
+```
+价格信号 = (今收 - 15日前收) / 15日前收
+价格信号得分 = clamp(50 + 收益率×500, 0, 100)
+
+资金意愿:
+  增仓上涨天数 > 增仓下跌天数 → 80
+  两者相当 → 50
+  增仓下跌天数 > 增仓上涨天数 → 20
+
+模块得分 = 价格信号 × 0.6 + 资金意愿 × 0.4
+```
+
+### 3. 长期结构（30 日窗口，权重 0.25）
+
+```
+持仓变化幅度 = (30日日均持仓 - 30日前持仓) / 30日前持仓
+
+> 10%  → 90（显著增仓）
+5%~10% → 70（温和增仓）
+-5%~5% → 50（基本持平）
+-10%~-5% → 30（温和减仓）
+< -10% → 10（显著减仓）
+```
+
+### 信号解读
+
+| 综合分数 | 信号 |
+|---------|------|
+| 80-100 | 强烈看多 — 价格与资金共振 |
+| 50-80 | 偏多/震荡偏强 |
+| 40-50 | 偏空/震荡偏弱 |
+| 0-40 | 强烈看空 — 资金主动打压 |
+
+## 数据查询
+
+SQLite 数据库位于 `data/futures.db`，可直接用 sqlite3 查询：
+
+```bash
+# 查看最新打分
+sqlite3 data/futures.db "SELECT ts_code, trade_date, composite, signal FROM scores ORDER BY trade_date DESC LIMIT 5;"
+
+# 查看合约日线
+sqlite3 data/futures.db "SELECT trade_date, open, high, low, close, vol, oi FROM candles WHERE ts_code='FG2609.ZCE' ORDER BY trade_date DESC LIMIT 10;"
+
+# 查看表结构
+sqlite3 data/futures.db ".schema"
+```
+
+## 项目结构
+
+```
+trade/
+├── docker-compose.yml          # Docker Compose 编排
+├── 使用说明.md                  # 本文件
+├── data/                        # SQLite 数据库目录(gitignored)
+│   └── futures.db
+├── .gitignore                   # Git 忽略配置
+└── tushare/                     # Python 数据服务
+    ├── Dockerfile               # 镜像构建
+    ├── requirements.txt         # Python 依赖
+    ├── .env                     # TUSHARE_TOKEN(本地,不入库)
+    └── src/                     # Python 包
+        ├── models.py            # 数据模型
+        ├── fetcher.py           # tushare 数据拉取
+        ├── scorer.py            # 打分模型核心
+        ├── storage.py           # SQLite 持久化
+        └── main.py              # CLI 入口
+```
+
+## 技术栈
+
+- **Python 3.13** (alpine 基础镜像)
+- **tushare** — 中国金融数据接口
+- **pandas** — 数据处理
+- **SQLite** — 本地数据存储
+- **Docker / Docker Compose** — 容器化部署
+
+## 常见问题
+
+**Q: 为什么某些日期返回空数据？**
+
+A: tushare 数据更新有延迟，且不同接口对 token 积分等级有要求。若 `fut_daily` 返回空但 `trade_cal` 正常，通常是该日期实际行情数据尚未入库。
+
+**Q: 合约代码格式？**
+
+A: 郑商所用 `.ZCE` 后缀（如 `FG2609.ZCE`），上期所用 `.SHF`，大商所用 `.DCE`。注意不是 `.CZC`。
+
+**Q: 如何定时自动跑？**
+
+A: 当前为手动 CLI 触发。后续可在 `docker-compose.yml` 中增加 cron 服务或接入调度器。
+
+**Q: Go 后端怎么读数据？**
+
+A: Go 端可直接用 `database/sql` + `github.com/mattn/go-sqlite3` 读取 `data/futures.db` 中的 `candles` 和 `scores` 表。