# 执行器飞书通知集成

## ✅ 改动概述

为所有交易执行器添加了飞书通知功能，确保每次交易执行结果（开仓、平仓、撤单、止盈止损设置）都会实时推送到飞书。

---

## 📦 改动的文件

### 1. `backend/app/crypto_agent/executor/base_executor.py`

**新增功能**：

#### 1.1 初始化飞书服务
```python
def __init__(self, platform_name: str):
    self.platform_name = platform_name
    # 初始化飞书通知服务
    try:
        from app.services.feishu_service import get_feishu_paper_trading_service
        self.feishu = get_feishu_paper_trading_service()
    except Exception as e:
        logger.warning(f"[{self.platform_name}] 飞书服务初始化失败: {e}")
        self.feishu = None
```

#### 1.2 通知方法

| 方法 | 用途 |
|------|------|
| `send_execution_notification()` | 统一通知入口，根据操作类型分发 |
| `_send_open_notification()` | 开仓成功/失败通知 |
| `_send_close_notification()` | 平仓成功/失败通知 |
| `_send_cancel_notification()` | 撤单成功/失败通知 |
| `_send_tp_sl_notification()` | 止盈止损设置通知 |
| `_send_position_management_notification()` | 持仓管理通知（自动止盈/移动止损） |
| `_send_generic_notification()` | 通用通知（兜底） |

#### 1.3 通知格式

**开仓成功**：
```
✅ [Bitget] 开仓成功 - BTC

**平台**: Bitget
**交易对**: BTC
**订单ID**: 123456789
**数量**: 1 张
**价格**: $85,000.00
**保证金**: $170.00
**杠杆**: 5x
**止损**: $83,000.00
**止盈**: $88,000.00
**订单类型**: limit
```

**开仓失败**：
```
❌ [Bitget] 开仓失败 - BTC

**平台**: Bitget
**交易对**: BTC
**错误**: 仓位计算结果 0 张，低于最小下单量
**原因**: 计算仓位 0 张 < 1 张
```

**平仓成功**：
```
✅ [Hyperliquid] 平仓成功 - ETH

**平台**: Hyperliquid
**交易对**: ETH
**盈利**: $125.50
**收益率**: 2.5%
**平仓原因**: 自动止盈
```

**止盈止损设置失败**：
```
⚠️ [Bitget] 止盈止损设置失败 - BTC

**平台**: Bitget
**交易对**: BTC
**错误**: API 限流，请稍后重试
```

---

### 2. `backend/app/crypto_agent/executor/bitget_executor.py`

**集成位置**：
- `execute_open()` - 开仓成功/失败后发送通知
- `execute_close()` - 平仓成功/失败后发送通知
- `execute_cancel()` - 撤单成功/失败后发送通知
- `set_stop_loss_take_profit()` - TP/SL 设置成功/失败后发送通知

**示例**：
```python
# 开仓成功
await self.send_execution_notification(
    operation='OPEN',
    symbol=symbol,
    result=result,
    details={
        'size': contracts,
        'price': entry_price,
        'margin': adjusted_margin,
        'leverage': leverage,
        'stop_loss': stop_loss,
        'take_profit': take_profit,
        'order_type': order_type
    }
)
```

---

### 3. `backend/app/crypto_agent/executor/paper_trading_executor.py`

**集成位置**：
- `execute_open()` - 开仓成功/失败后发送通知
- `execute_close()` - 平仓成功/失败后发送通知（包含盈亏信息）
- `execute_cancel()` - 撤单成功/失败后发送通知

**特点**：
- 平仓通知包含盈亏金额和收益率
- 开仓通知包含订单类型（市价/限价）

---

### 4. `backend/app/crypto_agent/executor/hyperliquid_executor.py`

**集成位置**：
- `execute_open()` - 开仓成功/失败后发送通知
- `execute_close()` - 平仓成功/失败后发送通知
- `execute_cancel()` - 撤单成功/失败后发送通知
- `set_stop_loss_take_profit()` - TP/SL 设置通知

**特点**：
- Hyperliquid 支持下单时设置 TP/SL，通知中会体现
- 平仓支持批量操作

---

## 🎯 通知触发场景

| 场景 | 操作类型 | 通知颜色 | 必须字段 |
|------|---------|---------|---------|
| 开仓成功 | `OPEN` | green | 平台、交易对、订单ID、数量、价格、保证金、杠杆 |
| 开仓失败 | `OPEN` | red | 平台、交易对、错误信息 |
| 平仓成功 | `CLOSE` | green | 平台、交易对、盈亏金额、收益率 |
| 平仓失败 | `CLOSE` | red | 平台、交易对、错误信息 |
| 撤单成功 | `CANCEL` | green | 平台、交易对、订单ID |
| 撤单失败 | `CANCEL` | red | 平台、交易对、订单ID、错误信息 |
| TP/SL 设置成功 | `TP_SL` | green | 平台、交易对、止损价、止盈价 |
| TP/SL 设置失败 | `TP_SL` | orange | 平台、交易对、错误信息 |
| 自动止盈 | `POSITION_MANAGEMENT` | green | 平台、交易对、操作、原因、盈亏 |
| 移动止损 | `POSITION_MANAGEMENT` | blue | 平台、交易对、操作、原因 |

---

## 📊 飞书 Webhook 配置

所有执行器使用 `get_feishu_paper_trading_service()` 获取飞书服务实例，对应配置：

```python
# .env
FEISHU_PAPER_TRADING_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
FEISHU_ENABLED=true
```

**说明**：
- 所有平台的执行通知统一发送到 `paper_trading` webhook
- 这是因为执行通知属于交易操作，与 `crypto` webhook（信号通知）区分
- 如需为不同平台配置不同 webhook，可在执行器初始化时传入不同的 `service_type`

---

## ✅ 测试验证

### 测试场景

#### 1. 开仓成功通知
```python
# 触发条件：Bitget 开仓 1 张 BTC 合约
# 预期：飞书收到绿色卡片，包含订单详情
```

#### 2. 开仓失败通知
```python
# 触发条件：仓位计算 < 1 张
# 预期：飞书收到红色卡片，包含失败原因
```

#### 3. 平仓成功通知
```python
# 触发条件：Hyperliquid 平仓持仓
# 预期：飞书收到绿色卡片，包含盈亏信息
```

#### 4. 撤单通知
```python
# 触发条件：取消挂单
# 预期：飞书收到绿色/红色卡片，包含订单ID
```

#### 5. TP/SL 设置通知
```python
# 触发条件：设置止盈止损
# 预期：飞书收到绿色/橙色卡片，包含 TP/SL 价格
```

---

## 🔍 日志示例

### 开仓成功
```
🎯 [Bitget] 处理交易信号: buy BTCUSDT
   订单类型: 价格差 0.05% < 0.2%，使用市价单
   仓位计算: $170.00 USD → 0.010000 BTC → 1 张
   ✅ 开仓成功: BTC 1张 @ $market
   📤 飞书通知发送成功
```

### 开仓失败
```
🎯 [Hyperliquid] 处理交易信号: buy ETHUSDT
   订单类型: 价格差 0.05% < 0.1%，使用市价单
   ❌ 开仓失败: 仓位计算失败: 0
   📤 飞书通知发送成功
```

### 平仓成功
```
📊 [Bitget] 检查持仓管理
   BTCUSDT 盈利 3.2% >= 3%
   ✅ 自动止盈成功: BTCUSDT
   📤 飞书通知发送成功
```

---

## 🎯 优势

### 1. 实时监控
- ✅ 每次交易操作都会即时推送到飞书
- ✅ 无需登录平台即可了解交易状态
- ✅ 支持移动端接收通知

### 2. 问题快速定位
- ✅ 失败通知包含详细错误信息
- ✅ 便于快速排查交易失败原因
- ✅ 支持审计和回溯

### 3. 统一管理
- ✅ 所有平台使用统一的通知格式
- ✅ 基类封装，易于维护和扩展
- ✅ 新增平台自动继承通知功能

### 4. 灵活配置
- ✅ 支持不同平台使用不同 webhook
- ✅ 通知内容可自定义
- ✅ 支持启用/禁用通知

---

## 📝 后续优化建议

### 1. 通知频率控制
```python
# 避免短时间内大量通知
# 可添加通知聚合或限流机制
```

### 2. 通知级别区分
```python
# 不同级别的通知使用不同 webhook
# - INFO: 开仓/平仓成功
# - WARNING: TP/SL 设置失败
# - ERROR: 交易失败
# - CRITICAL: 爆仓风险
```

### 3. 多语言支持
```python
# 根据用户配置切换中英文通知
```

### 4. 通知内容定制
```python
# 允许用户选择接收哪些类型的通知
# - 只接收失败通知
# - 只接收平仓通知
# - 接收所有通知
```

---

## 🚀 部署

### 1. 配置飞书 Webhook
```bash
# .env
FEISHU_PAPER_TRADING_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
FEISHU_ENABLED=true
```

### 2. 重启服务
```bash
sudo systemctl restart stock-agent
# 或
docker-compose restart
```

### 3. 验证通知
```bash
# 触发一次交易，检查飞书群是否收到通知
```

---

## 📋 总结

✅ **已完成**：
- BaseExecutor 集成飞书通知基类
- Bitget 执行器完整通知集成
- Hyperliquid 执行器完整通知集成
- PaperTrading 执行器完整通知集成
- 支持开仓/平仓/撤单/TP/SL 通知
- 成功/失败不同颜色区分
- 详细的通知内容（包含所有关键字段）

✅ **核心优势**：
- 实时监控交易状态
- 快速定位问题
- 统一通知格式
- 易于维护扩展

✅ **影响范围**：
- 3 个执行器文件（Bitget, Hyperliquid, PaperTrading）
- 1 个基类文件（BaseExecutor）
- 无需修改 crypto_agent.py
- 向后兼容，不影响现有功能