aiagents-stock/docs/Webhook功能完成说明.md

# Webhook功能完成说明

## ✅ 功能概述

成功为系统添加了**Webhook通知功能**，支持钉钉和飞书群机器人推送。

## 📋 完成内容

### 1. 核心功能实现

#### ✅ notification_service.py - Webhook发送核心
**新增功能**：
- `_send_webhook_notification()` - Webhook通知分发
- `_send_dingtalk_webhook()` - 钉钉消息发送
- `_send_feishu_webhook()` - 飞书消息发送  
- `send_test_webhook()` - 测试Webhook配置
- `get_webhook_config_status()` - 获取配置状态

**支持特性**：
- 📱 钉钉Markdown格式消息
- 📱 飞书交互式卡片消息
- ✅ 自动错误处理和重试
- ✅ 详细日志输出

#### ✅ sector_strategy_scheduler.py - 智策定时分析集成
**新增功能**：
- `_send_webhook_direct()` - 直接发送webhook
- `_send_dingtalk()` - 发送钉钉消息
- `_send_feishu()` - 发送飞书消息
- `_format_webhook_summary()` - 格式化精简摘要

**特点**：
- 同时支持邮件和Webhook
- 智能格式化报告（精简版）
- 分别统计发送成功数
- 完善的异常处理

### 2. 配置管理

#### ✅ config_manager.py - 配置项定义
**新增配置**：
```python
EMAIL_ENABLED     # 邮件通知开关
SMTP_SERVER       # SMTP服务器
SMTP_PORT         # SMTP端口
EMAIL_FROM        # 发件人邮箱
EMAIL_PASSWORD    # 邮箱授权码
EMAIL_TO          # 收件人邮箱
WEBHOOK_ENABLED   # Webhook开关
WEBHOOK_TYPE      # Webhook类型(dingtalk/feishu)
WEBHOOK_URL       # Webhook地址
```

**特性**：
- 支持布尔、文本、密码、选择框类型
- 自动读取和写入.env文件
- 完整的配置验证

#### ✅ app.py - 可视化配置界面
**新增UI**：
- 第4个标签页："📢 通知配置"
- 左右分栏布局（邮件 | Webhook）
- 实时配置状态提示
- 完整的帮助说明

**交互特性**：
- 启用开关自动禁用/启用输入框
- 配置完整性实时检查
- 保存后自动重新加载
- 显示当前.env文件内容

### 3. 通知集成

#### ✅ 实时监测模块
**集成点**：`monitor_service.py` → `notification_service.send_notifications()`

**通知时机**：
- ✅ 价格进入进场区间
- ✅ 价格达到止盈位
- ✅ 价格跌破止损位
- ✅ 量化交易执行

**发送逻辑**：
```python
# 同时尝试Webhook和邮件
if webhook_enabled:
    webhook_success = send_webhook()
if email_enabled:
    email_success = send_email()
# 至少一个成功即为成功
```

#### ✅ 智策定时分析
**集成点**：`sector_strategy_scheduler.py` → `_send_analysis_notification()`

**通知内容**：
- 📊 板块多空预测（信心度≥7）
- 🔄 潜力接力板块（TOP3）
- 🌡️ 板块热度排行（TOP3）
- 💡 核心投资机会

**消息格式**：
- Webhook：精简版（适合移动端）
- 邮件：完整版（详细分析）

### 4. 完整文档

#### ✅ 新建文档
- **Webhook通知配置指南.md** - 完整配置教程
  - 平台支持说明
  - 钉钉配置步骤
  - 飞书配置步骤
  - 消息格式示例
  - 故障排查指南
  - 使用场景推荐

#### ✅ 更新文档
- **环境配置功能说明.md** - 添加通知配置章节
- **config_manager.py** - 配置定义完善
- **app.py** - UI界面完整

---

## 🎯 使用方法

### 第一步：配置Webhook

#### 方法A：Web界面配置（推荐）
1. 进入"⚙️ 环境配置"
2. 选择"📢 通知配置"标签页
3. 勾选"启用Webhook通知"
4. 选择类型（钉钉/飞书）
5. 填写Webhook URL
6. 点击"💾 保存配置"

#### 方法B：手动编辑.env
```env
WEBHOOK_ENABLED=true
WEBHOOK_TYPE=dingtalk
WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxxxx
```

### 第二步：创建机器人

#### 钉钉机器人
1. 钉钉群 → 设置 → 智能群助手
2. 添加机器人 → 自定义
3. 安全设置：自定义关键词（股票、分析、智策）
4. 复制Webhook地址

#### 飞书机器人
1. 飞书群 → 设置 → 群机器人
2. 添加机器人 → 自定义机器人
3. 设置名称：AI股票分析系统
4. 复制Webhook地址

### 第三步：测试通知

#### 在实时监测中测试
1. 进入"📊 实时监测"
2. 滚动到"🔔 通知管理"
3. 点击"📱 发送测试Webhook"
4. 检查群消息

#### 在智策中测试
1. 进入"🎯 智策板块"
2. 展开"⏰ 定时分析设置"
3. 点击"🔄 立即运行一次"
4. 分析完成后查看群消息

---

## 📊 消息格式

### 实时监测通知（钉钉Markdown）

```markdown
### 股票监测提醒

**股票代码**: 600519

**股票名称**: 贵州茅台

**提醒类型**: 进场提醒

**提醒内容**: 股票价格 1650.00 进入进场区间

**触发时间**: 2024-01-15 10:30:00

---

_此消息由AI股票分析系统自动发送_
```

### 智策分析通知（钉钉Markdown）

```markdown
### 智策板块分析报告
**分析时间**: 2024-01-15 09:00

#### 📊 板块多空
**看多**: 人工智能(8分)、新能源汽车(8分)、半导体(7分)
**看空**: 地产开发(7分)

#### 🔄 潜力接力板块
- 半导体: 关注突破信号
- 军工: 情绪升温，把握机会

#### 🌡️ 热度TOP3
1. 人工智能 - 95分
2. 新能源汽车 - 92分
3. 半导体 - 88分

#### 💡 核心机会
重点关注人工智能、新能源汽车产业链，半导体板块有轮动潜力...

---
*由智策AI系统自动生成*
```

---

## 🔧 技术实现

### 1. Webhook API调用

#### 钉钉API
```python
import requests

data = {
    "msgtype": "markdown",
    "markdown": {
        "title": "标题",
        "text": "Markdown格式内容"
    }
}

response = requests.post(webhook_url, json=data, timeout=10)
result = response.json()
success = result.get('errcode') == 0
```

#### 飞书API
```python
import requests

data = {
    "msg_type": "interactive",  # 或 "text"
    "card": {
        # 交互式卡片内容
    }
}

response = requests.post(webhook_url, json=data, timeout=10)
result = response.json()
success = result.get('code') == 0
```

### 2. 通知流程

```
触发条件
  ↓
检查配置
  ├─ Webhook启用？
  │   ├─ 是 → 发送Webhook
  │   └─ 否 → 跳过
  └─ 邮件启用？
      ├─ 是 → 发送邮件
      └─ 否 → 跳过
  ↓
记录日志
  ├─ 成功：✓ 发送成功
  ├─ 失败：✗ 发送失败 + 错误信息
  └─ 跳过：⚠️ 未配置
```

### 3. 配置管理

```
.env文件
  ↓
config_manager读取
  ↓
notification_service加载
  ↓
实时重新加载（dotenv）
  ↓
Streamlit UI显示
```

---

## 💡 使用场景

### 场景1：日内交易团队协作

**配置**：
- 创建钉钉/飞书团队群
- 配置Webhook推送
- 设置实时监测

**效果**：
- 股票触发 → 群内实时通知
- 团队讨论 → 快速决策
- 消息记录 → 便于复盘

### 场景2：每日策略推送

**配置**：
- 启用智策定时分析
- 配置Webhook + 邮件
- 设置每天9:00运行

**效果**：
- 9:00自动分析 → 策略报告
- Webhook推送 → 快速查看
- 邮件发送 → 详细存档

### 场景3：个人投资提醒

**配置**：
- 创建个人钉钉/飞书群
- 仅添加机器人
- 配置实时监测

**效果**：
- 价格波动 → 手机通知
- 随时随地 → 及时查看
- 不错过 → 投资机会

---

## ⚠️ 注意事项

### 1. 安全配置

#### 钉钉关键词设置
- **推荐**：股票、分析、智策、监测
- 系统消息已包含关键词
- 避免使用过于通用的词

#### Webhook地址保护
- ❌ 不要公开分享
- ❌ 不要提交到版本控制
- ✅ 使用环境变量管理
- ✅ 定期更换地址

### 2. 消息频率

**平台限制**：
- 钉钉：20条/分钟
- 飞书：50条/分钟

**系统控制**：
- 实时监测：重复通知间隔60分钟
- 智策分析：每天1次
- 不会触发限流

### 3. 网络依赖

- 需要稳定网络连接
- 超时时间：10秒
- 失败不影响核心功能
- 错误会记录日志

### 4. 配置生效

- 修改配置后需重启应用
- 或使用"💾 保存配置"自动重载
- 建议先测试再正式使用

---

## 🐛 故障排查

### 问题1：未收到Webhook消息

**检查清单**：
1. ✅ `WEBHOOK_ENABLED=true`
2. ✅ Webhook URL完整正确
3. ✅ 网络连接正常
4. ✅ 机器人未被移出群
5. ✅ 钉钉关键词设置正确

**解决方案**：
```bash
# 1. 查看系统日志
📱 正在发送钉钉Webhook...
✅ 钉钉Webhook发送成功

# 2. 使用测试功能
点击"📱 发送测试Webhook"

# 3. 检查配置
进入"⚙️ 环境配置" → "📢 通知配置"
```

### 问题2：钉钉关键词不匹配

**错误信息**：`errcode: 310000`

**解决方案**：
- 添加关键词：股票、分析、智策
- 系统消息已包含这些词
- 检查是否误删关键词

### 问题3：飞书消息格式异常

**原因**：选择了错误的类型

**解决方案**：
- 确认选择 `feishu`
- 重新保存配置
- 测试验证

---

## 📈 功能对比

| 功能 | 邮件通知 | Webhook通知 | 界面通知 |
|------|---------|------------|----------|
| **实时性** | 延迟1-5秒 | 即时推送 | 需打开页面 |
| **详细度** | 完整详细 | 精简摘要 | 简单提示 |
| **查看方式** | 邮箱APP | 钉钉/飞书 | Web界面 |
| **历史记录** | 永久保存 | 群消息历史 | 临时显示 |
| **团队协作** | 转发分享 | 群内讨论 | 单人查看 |
| **移动端** | 邮箱APP | 原生APP | 浏览器 |
| **推荐场景** | 详细存档 | 快速查看 | 即时提示 |

---

## 🚀 未来规划

### v1.1.0 (计划中)
- [ ] 支持多个Webhook URL
- [ ] 企业微信机器人支持
- [ ] Server酱推送支持
- [ ] 消息模板自定义

### v1.2.0 (规划中)
- [ ] 消息去重和合并
- [ ] 智能推送时段设置
- [ ] 重要消息@提醒
- [ ] 消息统计和分析

---

## 📚 相关文档

- [Webhook通知配置指南.md](Webhook通知配置指南.md) - 详细配置教程
- [环境配置功能说明.md](环境配置功能说明.md) - 完整配置说明
- [实时监测优化说明.md](实时监测优化说明.md) - 实时监测功能
- [智策定时分析使用指南.md](智策定时分析使用指南.md) - 智策功能

---

## ✅ 验证清单

完成后请验证：

- [ ] Python环境正常
- [ ] requests库已安装
- [ ] Webhook配置已保存
- [ ] 机器人已创建
- [ ] 测试Webhook成功
- [ ] 收到测试消息
- [ ] 实时监测推送正常
- [ ] 智策分析推送正常
- [ ] 配置界面显示正常

---

## 🎉 总结

Webhook通知功能已全面完成，主要特点：

1. **双平台支持** - 钉钉和飞书群机器人
2. **灵活配置** - Web界面或.env文件
3. **全面集成** - 实时监测和智策分析
4. **可靠传输** - 错误处理和日志记录
5. **完整文档** - 配置指南和故障排查

现在您可以通过钉钉或飞书接收股票分析通知了！📱🔔

---

**Webhook通知功能** - v1.0.0

完成时间：2025-01-15