# 交易信号生成指南

## 📊 系统架构

系统分为两个独立的服务：

### 1. 数据采集服务 (ingestion) - 持续运行
- **功能**: WebSocket实时数据采集
- **数据源**: Binance期货WebSocket (K线、订单簿、交易流)
- **存储**: Redis Streams
- **状态**: 24/7持续运行

### 2. 信号生成服务 (scheduler) - 可选运行
- **功能**: 定时执行量化分析 + LLM决策
- **数据源**: 从Redis读取历史数据
- **输出**: 交易信号JSON文件
- **运行模式**: 定时自动 或 手动执行

---

## 🚀 运行方式

### 方式一：只运行数据采集（默认）

**适用场景**: 只需要采集数据，手动生成信号

```bash
# 启动数据采集服务
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f ingestion
```

**运行的服务**:
- ✅ `redis` - 数据存储
- ✅ `ingestion` - WebSocket数据采集
- ❌ `scheduler` - 未启动

**手动生成信号**:
```bash
# 随时可以手动执行
docker compose exec ingestion python /app/scripts/generate_trading_signal.py
```

---

### 方式二：数据采集 + 自动信号生成（推荐）

**适用场景**: 完全自动化，定时生成交易信号

```bash
# 启动数据采集 + 信号调度器
docker compose --profile scheduler up -d

# 查看状态
docker compose --profile scheduler ps

# 查看调度器日志
docker compose logs -f scheduler

# 查看采集服务日志
docker compose logs -f ingestion
```

**运行的服务**:
- ✅ `redis` - 数据存储
- ✅ `ingestion` - WebSocket数据采集
- ✅ `scheduler` - 定时信号生成 (每5分钟)

**配置信号生成间隔**:

编辑 `docker-compose.yml` 修改环境变量：
```yaml
scheduler:
  environment:
    - SIGNAL_INTERVAL_MINUTES=5  # 改为你想要的间隔（分钟）
```

支持的间隔：
- `1` - 每1分钟（高频，适合测试）
- `5` - 每5分钟（推荐，平衡频率和成本）
- `15` - 每15分钟（低频，节省LLM调用）
- `60` - 每1小时（很低频）

---

### 方式三：手动执行单次信号生成

**适用场景**: 测试、调试、手动判断

```bash
# 确保数据采集服务在运行
docker compose up -d

# 手动执行一次信号生成
docker compose exec ingestion python /app/scripts/generate_trading_signal.py
```

---

## 📁 信号输出

### 输出文件位置
```
./output/latest_signal.json
```

### 输出文件格式
```json
{
  "timestamp": "2025-11-30T13:23:24.816000",
  "aggregated_signal": {
    "final_signal": "BUY",
    "final_confidence": 0.75,
    "consensus": "QUANT_ONLY",
    "opportunities": {
      "intraday": {
        "exists": true,
        "direction": "LONG",
        "entry_price": 91128.0,
        "stop_loss": 91000.0,
        "take_profit": 91342.0
      },
      "swing": {...},
      "ambush": {...}
    }
  },
  "market_analysis": {...},
  "quantitative_signal": {...},
  "llm_signal": {...}
}
```

### 查看最新信号
```bash
# 直接查看
cat output/latest_signal.json

# 格式化查看
cat output/latest_signal.json | jq .
```

---

## 🔧 配置LLM API（可选）

如果需要LLM深度分析，配置API key：

### 方法1: 修改 docker-compose.yml

编辑 `docker-compose.yml` 的 `scheduler` 服务：

```yaml
scheduler:
  environment:
    # 使用 Deepseek (推荐，低成本)
    - OPENAI_API_KEY=sk-your-deepseek-key
    - OPENAI_BASE_URL=https://api.deepseek.com

    # 或使用 OpenAI GPT
    # - OPENAI_API_KEY=sk-your-openai-key

    # 或使用 Claude
    # - ANTHROPIC_API_KEY=sk-ant-your-key
```

### 方法2: 使用 .env 文件

创建 `.env.local` 文件：
```bash
OPENAI_API_KEY=sk-your-key
OPENAI_BASE_URL=https://api.deepseek.com
```

修改 docker-compose.yml:
```yaml
scheduler:
  env_file:
    - .env.local
```

---

## 📊 LLM Gate 控制

### 当前配置（极简模式）

LLM Gate 确保合理使用LLM API：

```yaml
LLM_GATE_ENABLED: true               # 启用门控
LLM_MIN_CANDLES: 100                 # 最少K线数量
LLM_MIN_COMPOSITE_SCORE: 15.0        # 综合得分门槛
LLM_MAX_CALLS_PER_DAY: 12            # 每天最多调用12次
LLM_MIN_INTERVAL_MINUTES: 15         # 调用间隔≥15分钟
```

### Gate 逻辑

信号生成时，LLM调用需要通过：

1. ✅ **频率检查** - 今日调用 < 12次，且距上次 ≥ 15分钟
2. ✅ **数据检查** - K线数量 ≥ 100根
3. ✅ **质量检查** - 综合得分 ≥ 15（过滤完全中性信号）

### 查看Gate统计

```bash
docker compose exec scheduler python -c "
from signals.llm_gate import LLMGate
gate = LLMGate()
stats = gate.get_stats()
print(f'今日调用: {stats[\"today_calls\"]}/{stats[\"max_calls_per_day\"]}')
print(f'剩余配额: {stats[\"remaining_calls_today\"]}')
print(f'距离上次: {stats[\"minutes_since_last_call\"]:.1f} 分钟' if stats['minutes_since_last_call'] else '从未调用')
"
```

---

## 🔍 监控和日志

### 查看实时日志

```bash
# 数据采集日志
docker compose logs -f ingestion

# 信号生成日志
docker compose logs -f scheduler

# 所有服务日志
docker compose logs -f
```

### 日志关键信息

**数据采集 (ingestion)**:
```
Health Check | WebSocket: ✓ | Redis: ✓ | Buffer: 0.5% | Written: 12345
```

**信号生成 (scheduler)**:
```
📊 开始生成交易信号 - 2025-11-30 13:23:24
✅ 市场分析完成 - 价格: $91,650.10, 趋势: 上涨
📈 量化信号: BUY (得分: 51.5)
✅ LLM Gate: PASSED - 信号类型: BUY, 综合得分: 51.5
🤖 LLM信号: BUY (置信度: 60.00%)
🎯 最终信号: BUY (置信度: 75.00%)
💾 信号已保存到: /app/output/latest_signal.json
```

---

## ⚙️ 常用命令

### 启动/停止服务

```bash
# 只启动数据采集
docker compose up -d

# 启动数据采集 + 信号调度
docker compose --profile scheduler up -d

# 停止所有服务
docker compose down

# 重启某个服务
docker compose restart scheduler
docker compose restart ingestion
```

### 查看状态

```bash
# 查看运行状态
docker compose ps

# 查看资源使用
docker stats tradus-ingestion tradus-scheduler

# 查看网络
docker network inspect realtime-ingestion_tradus-network
```

### 进入容器

```bash
# 进入数据采集容器
docker compose exec ingestion bash

# 进入调度器容器
docker compose exec scheduler bash

# 进入Redis
docker compose exec redis redis-cli
```

---

## 🐛 故障排查

### 问题1: scheduler未启动

**症状**: `docker compose ps` 看不到 `tradus-scheduler`

**原因**: 默认情况下scheduler是profile服务，不会自动启动

**解决**:
```bash
docker compose --profile scheduler up -d
```

### 问题2: LLM总是被Gate拦截

**症状**: 日志显示 `🚫 LLM Gate: BLOCKED`

**可能原因**:
1. 综合得分太低 (< 15)
2. 调用频率太高 (< 15分钟)
3. 今日配额用完 (≥ 12次)

**解决**:
```bash
# 查看Gate状态
docker compose exec scheduler python -c "from signals.llm_gate import LLMGate; print(LLMGate().get_stats())"

# 降低综合得分门槛 (修改 .env)
LLM_MIN_COMPOSITE_SCORE=10.0

# 增加每日配额 (修改 .env)
LLM_MAX_CALLS_PER_DAY=20

# 重启服务
docker compose --profile scheduler restart scheduler
```

### 问题3: 生成信号失败

**症状**: 日志显示 `❌ 信号生成失败`

**可能原因**:
1. Redis数据不足
2. K线数据 < 100根

**解决**:
```bash
# 检查Redis数据
docker compose exec redis redis-cli
> XLEN binance:raw:kline:5m

# 等待数据累积（至少20分钟）
# 或手动从Binance API获取历史数据
```

---

## 📈 性能优化

### 调整信号生成间隔

根据交易策略调整：

- **高频策略**: 1-5分钟
- **中频策略**: 5-15分钟（推荐）
- **低频策略**: 15-60分钟

### 调整LLM调用频率

在 `.env` 中配置：

```bash
# 保守模式（节省成本）
LLM_MAX_CALLS_PER_DAY=5
LLM_MIN_INTERVAL_MINUTES=30
LLM_MIN_COMPOSITE_SCORE=20.0

# 激进模式（更多LLM分析）
LLM_MAX_CALLS_PER_DAY=20
LLM_MIN_INTERVAL_MINUTES=10
LLM_MIN_COMPOSITE_SCORE=10.0

# 平衡模式（推荐）
LLM_MAX_CALLS_PER_DAY=12
LLM_MIN_INTERVAL_MINUTES=15
LLM_MIN_COMPOSITE_SCORE=15.0
```

---

## 🎯 推荐使用方式

### 开发/测试阶段
```bash
# 只运行数据采集，手动测试信号生成
docker compose up -d
docker compose exec ingestion python /app/scripts/generate_trading_signal.py
```

### 生产/自动化阶段
```bash
# 运行数据采集 + 自动信号生成
docker compose --profile scheduler up -d

# 配置LLM API key（在docker-compose.yml中）
# 监控日志
docker compose logs -f scheduler
```

### 回测/分析阶段
```bash
# 只运行数据采集，积累历史数据
docker compose up -d

# 定期导出数据用于回测
# （后续可以开发专门的回测工具）
```