stock-ai-agent/backend/app/crypto_agent/executor/FEISHU_NOTIFICATION_INTEGRATION.md

执行器飞书通知集成

✅ 改动概述

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

---

📦 改动的文件

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

新增功能：

1.1 初始化飞书服务

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 设置成功/失败后发送通知

示例：

# 开仓成功
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() 获取飞书服务实例，对应配置：

# .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. 开仓成功通知

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

2. 开仓失败通知

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

3. 平仓成功通知

# 触发条件：Hyperliquid 平仓持仓
# 预期：飞书收到绿色卡片，包含盈亏信息

4. 撤单通知

# 触发条件：取消挂单
# 预期：飞书收到绿色/红色卡片，包含订单ID

5. TP/SL 设置通知

# 触发条件：设置止盈止损
# 预期：飞书收到绿色/橙色卡片，包含 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. 通知频率控制

# 避免短时间内大量通知
# 可添加通知聚合或限流机制

2. 通知级别区分

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

3. 多语言支持

# 根据用户配置切换中英文通知

4. 通知内容定制

# 允许用户选择接收哪些类型的通知
# - 只接收失败通知
# - 只接收平仓通知
# - 接收所有通知

---

🚀 部署

1. 配置飞书 Webhook

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

2. 重启服务

sudo systemctl restart stock-agent
# 或
docker-compose restart

3. 验证通知

# 触发一次交易，检查飞书群是否收到通知

---

📋 总结

✅ 已完成：

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

✅ 核心优势：

• 实时监控交易状态
• 快速定位问题
• 统一通知格式
• 易于维护扩展

✅ 影响范围：

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