# 交易推荐功能说明

## 功能概述

交易推荐模块用于生成交易对推荐，供手动参考下单。推荐基于技术指标分析，包含详细的参数指标和推荐原因，方便后续复盘。

## 数据库表结构

### trade_recommendations 表

包含以下字段：

- **基本信息**
  - `symbol`: 交易对（如 BTCUSDT）
  - `direction`: 推荐方向（BUY/SELL）
  - `recommendation_time`: 推荐时间
  - `current_price`: 当前价格
  - `change_percent`: 24小时涨跌幅

- **推荐原因**
  - `recommendation_reason`: 推荐原因（详细说明）
  - `signal_strength`: 信号强度（0-10）
  - `market_regime`: 市场状态（trending/ranging）
  - `trend_4h`: 4H周期趋势（up/down/neutral）

- **技术指标**
  - `rsi`: RSI指标
  - `macd_histogram`: MACD柱状图
  - `bollinger_upper/middle/lower`: 布林带上下中轨
  - `ema20/ema50`: EMA均线
  - `ema20_4h`: 4H周期EMA20
  - `atr`: 平均真实波幅

- **建议参数**
  - `suggested_stop_loss`: 建议止损价
  - `suggested_take_profit_1`: 建议第一目标止盈价（盈亏比1:1）
  - `suggested_take_profit_2`: 建议第二目标止盈价
  - `suggested_position_percent`: 建议仓位百分比
  - `suggested_leverage`: 建议杠杆倍数

- **市场数据**
  - `volume_24h`: 24小时成交量
  - `volatility`: 波动率

- **状态管理**
  - `status`: 状态（active/executed/expired/cancelled）
  - `executed_at`: 执行时间
  - `execution_result`: 执行结果
  - `execution_trade_id`: 关联的交易记录ID
  - `expires_at`: 推荐过期时间（默认24小时）

## 使用方法

### 1. 生成推荐

#### 通过API生成

```bash
POST /api/recommendations/generate
参数：
- min_signal_strength: 最小信号强度（默认5，范围0-10）
- max_recommendations: 最大推荐数量（默认20，范围1-50）
```

#### 通过代码生成

```python
from trading_system.trade_recommender import TradeRecommender
from trading_system.binance_client import BinanceClient
from trading_system.market_scanner import MarketScanner
from trading_system.risk_manager import RiskManager

# 初始化组件
client = BinanceClient(...)
scanner = MarketScanner(client)
risk_manager = RiskManager(client)
recommender = TradeRecommender(client, scanner, risk_manager)

# 生成推荐
recommendations = await recommender.generate_recommendations(
    min_signal_strength=5,
    max_recommendations=20
)
```

### 2. 查看推荐

#### 获取所有推荐

```bash
GET /api/recommendations
参数：
- status: 状态过滤（active/executed/expired/cancelled）
- direction: 方向过滤（BUY/SELL）
- limit: 返回数量（默认50，最大200）
- start_date: 开始日期（YYYY-MM-DD）
- end_date: 结束日期（YYYY-MM-DD）
```

#### 获取当前有效推荐

```bash
GET /api/recommendations/active
```

#### 获取推荐详情

```bash
GET /api/recommendations/{recommendation_id}
```

#### 根据交易对获取推荐

```bash
GET /api/recommendations/symbol/{symbol}
参数：
- limit: 返回数量（默认10，最大50）
```

### 3. 管理推荐

#### 标记推荐已执行

```bash
POST /api/recommendations/{recommendation_id}/execute
Body:
{
  "trade_id": 123  // 可选，关联的交易记录ID
}
```

#### 取消推荐

```bash
POST /api/recommendations/{recommendation_id}/cancel
Body:
{
  "notes": "取消原因"  // 可选
}
```

## 推荐生成逻辑

### 信号分析

推荐模块使用与交易策略相同的信号分析逻辑：

1. **多周期共振检查**
   - 4H周期定方向
   - 禁止逆4H趋势交易
   - 4H周期共振时信号强度+2

2. **技术指标分析**
   - 震荡市场：使用均值回归策略（RSI、布林带）
   - 趋势市场：使用趋势跟踪策略（MACD、均线）

3. **信号强度计算**
   - 基础信号：2-4分
   - 多指标确认：+2分
   - 4H周期共振：+2分
   - 要求信号强度 >= 5（可配置）

### 建议参数计算

1. **止损价**
   - 优先使用基于支撑/阻力的动态止损
   - 回退到ATR或固定百分比止损

2. **止盈价**
   - 第一目标：盈亏比1:1（了结50%仓位）
   - 第二目标：止损的2.5倍（剩余50%仓位）

3. **建议仓位**
   - 基础仓位：配置的MAX_POSITION_PERCENT
   - 根据信号强度调整（信号强度越高，建议仓位可适当增加，最多1.5倍）

## 推荐状态

- **active**: 有效推荐（未过期、未执行、未取消）
- **executed**: 已执行（已手动下单）
- **expired**: 已过期（超过24小时）
- **cancelled**: 已取消（手动取消）

## 复盘功能

推荐记录包含完整的技术指标和执行结果，方便复盘：

1. **查看历史推荐**
   - 按时间、状态、方向筛选
   - 查看推荐时的技术指标

2. **分析推荐质量**
   - 对比推荐原因与实际结果
   - 分析不同信号强度的成功率
   - 评估不同市场状态下的推荐效果

3. **优化策略**
   - 根据复盘结果调整信号强度要求
   - 优化推荐生成逻辑

## 注意事项

1. **推荐有效期**
   - 默认24小时后自动过期
   - 过期后状态变为 `expired`

2. **信号强度**
   - 建议使用信号强度 >= 5 的推荐
   - 信号强度越高，推荐质量越好

3. **手动验证**
   - 推荐仅供参考，请结合市场情况手动验证
   - 建议在关键支撑/阻力位附近入场

4. **风险控制**
   - 严格按照建议止损止盈执行
   - 不要超过建议仓位

## 示例

### 生成推荐

```bash
curl -X POST "http://localhost:8001/api/recommendations/generate?min_signal_strength=5&max_recommendations=10"
```

### 查看有效推荐

```bash
curl "http://localhost:8001/api/recommendations/active"
```

### 标记已执行

```bash
curl -X POST "http://localhost:8001/api/recommendations/1/execute" \
  -H "Content-Type: application/json" \
  -d '{"trade_id": 123}'
```

## 数据库迁移

如果数据库已存在，需要执行以下SQL创建推荐表：

```sql
-- 执行 backend/database/init.sql 中的 trade_recommendations 表创建语句
```

或者手动执行：

```sql
CREATE TABLE IF NOT EXISTS `trade_recommendations` (
  -- 见 init.sql 中的完整表结构
);
```