# Webhook通知配置指南

## 📱 功能概述

系统支持通过Webhook将通知推送到钉钉或飞书群，适用于：
- **实时监测**：股票价格触发提醒
- **智策定时分析**：板块策略分析报告

可与邮件通知同时使用，也可单独使用。

---

## 🎯 支持的平台

### 1. 钉钉群机器人
- ✅ 支持Markdown格式
- ✅ 消息样式丰富
- ✅ 配置简单
- ✅ 免费使用

### 2. 飞书群机器人
- ✅ 支持交互式卡片
- ✅ 消息展示美观
- ✅ 支持文本和富文本
- ✅ 免费使用

---

## 📝 配置步骤

### 方法一：通过Web界面配置（推荐）

1. **进入配置页面**
   - 点击侧边栏"⚙️ 环境配置"
   - 选择"📢 通知配置"标签页

2. **配置Webhook**
   - 勾选"启用Webhook通知"
   - 选择Webhook类型（钉钉/飞书）
   - 填写Webhook URL
   - 点击"💾 保存配置"

3. **测试配置**
   - 在实时监测的"通知管理"中
   - 点击"测试Webhook"按钮
   - 检查群消息是否收到

### 方法二：手动编辑.env文件

```env
# Webhook通知配置
WEBHOOK_ENABLED=true
WEBHOOK_TYPE=dingtalk  # 或 feishu
WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxxxx
```

---

## 🔧 钉钉机器人配置

### 步骤1：创建群机器人

1. 打开钉钉PC端或移动端
2. 进入要接收通知的群聊
3. 点击右上角"⚙️"进入群设置
4. 选择"智能群助手" → "添加机器人"
5. 选择"自定义"机器人

### 步骤2：配置机器人

1. **机器人名称**：AI股票分析系统
2. **安全设置**（选择一种即可）：
   - ✅ **推荐**：自定义关键词（例如：股票、分析、智策）
   - 加签（需要额外配置）
   - IP地址段（需要固定IP）

### 步骤3：获取Webhook地址

完成配置后，会显示Webhook地址：
```
https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxx
```

复制整个地址到系统配置中。

### 钉钉消息格式示例

**实时监测通知**：
```markdown
### 股票监测提醒

**股票代码**: 600519

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

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

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

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

---

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

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

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

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

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

#### 💡 核心机会
重点关注人工智能、新能源汽车产业链...

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

---

## 🚀 飞书机器人配置

### 步骤1：创建群机器人

1. 打开飞书PC端或移动端
2. 进入要接收通知的群聊
3. 点击右上角"⚙️"进入群设置
4. 选择"群机器人" → "添加机器人"
5. 选择"自定义机器人"

### 步骤2：配置机器人

1. **机器人名称**：AI股票分析系统
2. **机器人描述**：股票监测和板块分析通知
3. **安全设置**（可选）：
   - 签名验证（需要额外配置）

### 步骤3：获取Webhook地址

完成配置后，会显示Webhook地址：
```
https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxx
```

复制整个地址到系统配置中。

### 飞书消息格式示例

**实时监测通知**：
```
📊 股票监测提醒 - 600519

股票代码      股票名称
600519       贵州茅台

提醒类型      触发时间
进场提醒      2024-01-15 10:30:00

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

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

**智策定时分析**：
```
【智策板块分析报告】
分析时间: 2024-01-15 09:00

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

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

#### 🔄 潜力接力板块
- 半导体: 关注突破信号

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

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

---

## ⚙️ 配置说明

### 环境变量

| 变量名 | 说明 | 示例值 |
|-------|------|--------|
| `WEBHOOK_ENABLED` | 是否启用Webhook | `true` 或 `false` |
| `WEBHOOK_TYPE` | Webhook类型 | `dingtalk` 或 `feishu` |
| `WEBHOOK_URL` | Webhook地址 | 完整的机器人Webhook URL |

### 配置检查

系统会自动检查配置状态：
- ✅ **配置完整**：显示绿色提示
- ⚠️ **配置不完整**：显示黄色警告
- ℹ️ **未启用**：显示蓝色信息

---

## 🧪 测试Webhook

### 在实时监测模块测试

1. 进入"📊 实时监测"页面
2. 滚动到"🔔 通知管理"区域
3. 点击"📱 发送测试Webhook"按钮
4. 检查钉钉/飞书群是否收到消息

### 测试消息内容

```
股票代码: 测试
股票名称: Webhook测试
提醒类型: 测试消息
提醒内容: 如果您收到此消息，说明Webhook配置正确！
触发时间: 刚刚
```

---

## 🔄 同时使用邮件和Webhook

系统支持同时启用邮件和Webhook通知：

```env
# 邮件通知
EMAIL_ENABLED=true
SMTP_SERVER=smtp.qq.com
EMAIL_FROM=your-email@qq.com
EMAIL_PASSWORD=authorization-code
EMAIL_TO=recipient@qq.com

# Webhook通知
WEBHOOK_ENABLED=true
WEBHOOK_TYPE=dingtalk
WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxxxx
```

**优势**：
- 📧 邮件：详细完整，适合深度阅读
- 📱 Webhook：即时推送，适合快速查看
- 🔔 双重保障：确保不错过重要通知

---

## ⚠️ 注意事项

### 1. 钉钉安全设置

如果选择"自定义关键词"，确保消息中包含关键词：
- **推荐关键词**：股票、分析、智策、监测、提醒
- 系统消息已包含这些关键词，无需额外配置

### 2. 消息频率限制

- **钉钉**：每个机器人每分钟最多20条消息
- **飞书**：每个机器人每分钟最多50条消息
- 系统会自动控制发送频率，避免超限

### 3. Webhook地址安全

- ❌ 不要在公开场合分享Webhook URL
- ❌ 不要提交到版本控制系统
- ✅ 使用环境变量或配置文件管理
- ✅ 定期更换Webhook地址

### 4. 消息格式

- **钉钉**：支持Markdown格式
- **飞书**：支持文本和交互式卡片
- 系统会自动根据平台类型格式化消息

---

## 🛠️ 故障排查

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

**检查项**：
1. ✅ Webhook是否已启用（`WEBHOOK_ENABLED=true`）
2. ✅ Webhook URL是否正确
3. ✅ 网络连接是否正常
4. ✅ 机器人是否被移出群聊
5. ✅ 钉钉关键词安全设置是否正确

**解决方案**：
- 使用"测试Webhook"功能验证配置
- 检查系统日志查看错误信息
- 重新创建机器人并更新URL

### 问题2：Webhook发送失败

**常见错误**：

| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| `errcode: 310000` | 关键词不匹配 | 添加"股票"或"分析"到关键词 |
| `Connection timeout` | 网络超时 | 检查网络连接 |
| `Invalid URL` | URL格式错误 | 检查URL完整性 |

**日志查看**：
系统会在终端输出详细日志：
```
📱 正在发送钉钉Webhook...
  - URL: https://oapi.dingtalk.com...
✅ 钉钉Webhook发送成功
```

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

**现象**：消息显示不正确或乱码

**解决方案**：
- 确认选择了正确的Webhook类型（钉钉/飞书）
- 检查系统编码设置为UTF-8
- 尝试重新保存配置

---

## 📊 使用场景

### 场景1：日内交易监控

**配置**：
- 启用实时监测 ✅
- 启用Webhook通知 ✅
- 设置进场区间、止盈止损 ✅

**效果**：
- 股票价格变动 → 钉钉/飞书实时提醒
- 手机随时查看 → 及时做出决策
- 双重保障 → 不错过交易机会

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

**配置**：
- 启用智策定时分析 ✅
- 设置每天9:00运行 ✅
- 启用Webhook通知 ✅

**效果**：
- 每天9:00自动分析 → 板块策略报告
- 推送到钉钉/飞书群 → 团队成员查看
- 邮件同步发送 → 详细报告留存

### 场景3：团队协作

**配置**：
- 将机器人添加到团队群 ✅
- 配置Webhook URL ✅
- 多人共享通知 ✅

**效果**：
- 团队成员实时接收 → 投资信息同步
- 群内讨论决策 → 提高协作效率
- 历史消息可查 → 便于复盘总结

---

## 🎓 最佳实践

### 1. 消息分级

**重要通知** → Webhook + 邮件：
- 进场/止盈/止损提醒
- 智策定时分析报告

**一般通知** → 仅Webhook：
- 价格波动提醒
- 系统状态更新

### 2. 多群分发

创建多个机器人，分别推送：
- **交易群**：实时监测提醒
- **研究群**：智策分析报告
- **个人**：所有通知

### 3. 消息过滤

利用钉钉/飞书的消息筛选功能：
- 设置关键词提醒
- 静音非关键时段
- 重要消息置顶

---

## 📚 相关文档

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

---

## ❓ 常见问题

**Q: 可以同时配置多个Webhook吗？**  
A: 当前版本只支持一个Webhook URL。如需多群推送，建议使用钉钉/飞书的消息转发功能。

**Q: Webhook和邮件应该选哪个？**  
A: 建议同时使用。Webhook适合实时查看，邮件适合详细阅读和存档。

**Q: 消息发送失败会影响系统吗？**  
A: 不会。Webhook发送失败不影响核心功能，系统会记录日志并继续运行。

**Q: 如何更换Webhook URL？**  
A: 在环境配置中修改`WEBHOOK_URL`，保存后重启应用即可。

**Q: 钉钉和飞书哪个更好？**  
A: 各有优势。钉钉Markdown渲染好，飞书卡片更美观。选择团队常用的即可。

---

**Webhook通知配置指南** - 让通知更及时 📱🔔

版本：v1.0  
更新时间：2025-01-15