tradusai/DINGTALK_SETUP.md

# 钉钉消息通知配置指南

## 📱 功能说明

系统支持通过钉钉群机器人自动推送交易信号通知，包括：

- ✅ 实时交易信号推送（BUY/SELL）
- ✅ 量化分析 + AI深度分析结果
- ✅ 日内/中长线/埋伏点位机会详情
- ✅ 进场价/止损/止盈建议
- ✅ 风险评估和综合建议
- ✅ Markdown格式，可读性强

## 🔧 配置步骤

### 第一步：创建钉钉群机器人

1. **打开钉钉群**
   - 在电脑端或手机端打开需要接收通知的钉钉群

2. **添加自定义机器人**
   - 点击群设置 → 智能群助手 → 添加机器人
   - 选择"自定义"机器人
   - 点击"添加"

3. **配置机器人**
   - **机器人名称**: 例如 "交易信号助手"
   - **消息推送**:
     - ✅ 勾选 "加签"（推荐，更安全）
     - 或 勾选 "自定义关键词"（输入：信号、交易）
     - 或 勾选 "IP地址段"（如果固定IP）

4. **获取配置信息**
   - **Webhook地址**: 复制形如 `https://oapi.dingtalk.com/robot/send?access_token=xxxxx` 的URL
   - **加签密钥**: 如果选择了"加签"，复制 `SEC` 开头的密钥

5. **完成配置**
   - 点击"完成"
   - 机器人添加成功

---

### 第二步：配置系统环境变量

有两种配置方式：

#### 方式A: 修改 docker-compose.yml（推荐）

编辑 `docker-compose.yml` 文件，找到 `scheduler` 服务，取消注释并填入配置：

```yaml
scheduler:
  environment:
    # DingTalk Notification
    - DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=你的access_token
    - DINGTALK_SECRET=SEC你的加签密钥  # 如果使用了加签
```

**示例**:
```yaml
scheduler:
  environment:
    # DingTalk Notification
    - DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=1a2b3c4d5e6f7g8h9i0j
    - DINGTALK_SECRET=SEC1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0
```

#### 方式B: 使用 .env.local 文件

创建 `.env.local` 文件：

```bash
# DingTalk Configuration
DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=你的access_token
DINGTALK_SECRET=SEC你的加签密钥
```

然后在 `docker-compose.yml` 中添加：

```yaml
scheduler:
  env_file:
    - .env.local
```

⚠️ **重要**: 将 `.env.local` 添加到 `.gitignore`，避免泄露敏感信息

---

### 第三步：重启服务

```bash
# 停止服务
docker compose down

# 重新构建镜像（如果修改了requirements.txt）
docker compose build scheduler

# 启动服务
docker compose --profile scheduler up -d

# 查看日志，确认钉钉已启用
docker compose logs scheduler
```

**预期日志**:
```
📱 钉钉通知已启用 - Webhook: https://oapi.dingtalk.com/robot/send?access...
```

---

## 📊 消息示例

### BUY信号示例

```markdown
# 🟢 交易信号: BUY

**时间**: 2025-11-30 21:45:23
**置信度**: 75.0%
**共识**: QUANT_LLM_AGREE

---

## 📊 量化分析

- **信号**: BUY
- **综合得分**: 51.5
- **置信度**: 75.0%
- **趋势得分**: 99.0
- **动量得分**: 75.0
- **订单流得分**: -7.8

## 🤖 AI深度分析

- **信号**: BUY
- **置信度**: 60.0%
- **风险等级**: MEDIUM

### 📊 日内交易机会
- **方向**: LONG
- **入场**: $91,128.00
- **止损**: $91,000.00
- **止盈**: $91,342.00
- **说明**: 5分钟和15分钟周期呈现上涨趋势，MACD金叉扩大...

### 📌 埋伏点位
- **埋伏价位**: $90,612.00
- **说明**: 等待价格回调至4小时支撑位90612附近...

### 💡 AI分析
> 当前市场呈现多周期趋势分歧，日线下跌但短周期上涨，形成震荡格局...

**关键因素**:
- 多周期趋势分歧
- 成交量萎缩
- RSI中性区域

## 💰 价格位

- **当前价格**: $91,650.10
- **入场价**: $91,650.10
- **止损价**: $90,985.52
- **目标价1**: $92,646.96
- **目标价2**: $93,311.54
- **目标价3**: $94,308.40
- **风险回报比**: 1:1.50

## 📝 综合建议

> 量化和AI分析一致看多，建议在回调时逢低做多

---

*本信号由AI量化系统自动生成，仅供参考，不构成投资建议*
```

### SELL信号示例

```markdown
# 🔴 交易信号: SELL

**时间**: 2025-11-30 22:30:15
**置信度**: 68.0%
**共识**: QUANT_ONLY

---

[类似格式，信号为SELL]
```

---

## 🎯 通知规则

### 何时发送通知

- ✅ **BUY信号**: 立即发送通知
- ✅ **SELL信号**: 立即发送通知
- ❌ **HOLD信号**: 不发送通知（避免噪音）

### 消息去重

- 每次只发送最新的信号
- 不会重复发送相同的信号

---

## 🔐 安全建议

### 1. 使用加签（强烈推荐）

加签可以验证请求来源，防止webhook被滥用：

```yaml
- DINGTALK_SECRET=SEC你的加签密钥
```

### 2. 限制IP地址（可选）

如果服务器IP固定，可以在钉钉机器人设置中配置IP白名单。

### 3. 保护webhook地址

- ❌ 不要将webhook地址提交到Git仓库
- ❌ 不要在公开场合分享webhook地址
- ✅ 使用 `.env.local` 文件存储
- ✅ 添加 `.env.local` 到 `.gitignore`

---

## 🐛 故障排查

### 问题1: 未收到通知

**检查步骤**:

1. **确认钉钉配置是否正确**
   ```bash
   docker compose logs scheduler | grep "钉钉"
   ```

   期望输出: `📱 钉钉通知已启用`

2. **确认是否有BUY/SELL信号**
   ```bash
   docker compose logs scheduler | grep "发送钉钉通知"
   ```

3. **检查钉钉机器人配置**
   - webhook地址是否正确
   - 加签密钥是否匹配
   - 关键词是否配置正确

4. **手动测试webhook**
   ```bash
   docker compose exec scheduler python -c "
   from notifiers.dingtalk import DingTalkNotifier
   import os
   notifier = DingTalkNotifier(
       webhook_url=os.getenv('DINGTALK_WEBHOOK'),
       secret=os.getenv('DINGTALK_SECRET')
   )
   notifier.send_markdown('测试', '# 测试消息\n\n这是一条测试消息')
   "
   ```

### 问题2: 发送失败

**可能原因**:

1. **Webhook地址错误**
   - 检查是否完整复制了webhook URL
   - 确认access_token没有遗漏

2. **加签密钥错误**
   - 检查密钥是否以 `SEC` 开头
   - 确认密钥完整

3. **网络问题**
   - 检查容器是否能访问外网
   - 尝试 `docker compose exec scheduler ping oapi.dingtalk.com`

4. **关键词不匹配**
   - 如果使用"自定义关键词"，确保消息包含关键词
   - 推荐使用"加签"方式

### 问题3: 消息格式错误

**症状**: 收到消息但格式混乱

**解决**:
- 确保使用最新版本的代码
- 检查日志中是否有错误信息
- 联系开发者反馈问题

---

## 📞 支持的通知场景

### 当前已支持

- ✅ 交易信号通知（BUY/SELL）
- ✅ 包含量化 + AI分析
- ✅ 包含价格位和风险建议

### 未来计划支持

- ⏳ 系统错误通知
- ⏳ 每日汇总报告
- ⏳ 重要市场事件提醒
- ⏳ 仓位管理提醒

---

## 🔄 取消通知

如果需要暂时关闭钉钉通知：

### 方法1: 注释环境变量

编辑 `docker-compose.yml`:

```yaml
scheduler:
  environment:
    # - DINGTALK_WEBHOOK=...  # 注释掉
    # - DINGTALK_SECRET=...   # 注释掉
```

### 方法2: 删除机器人

在钉钉群中删除机器人即可。

### 重新启动服务

```bash
docker compose --profile scheduler restart scheduler
```

---

## 📝 最佳实践

1. **专用群组**: 建议为交易信号创建专门的钉钉群，避免干扰其他讨论
2. **多环境隔离**: 测试环境和生产环境使用不同的webhook
3. **定期检查**: 定期查看通知是否正常，避免错过重要信号
4. **备份配置**: 保存webhook和密钥的备份，避免丢失
5. **安全第一**: 始终使用加签，不要分享webhook地址

---

## 🎉 配置完成

完成上述配置后，系统会在生成BUY/SELL信号时自动发送钉钉通知！

**下一步**:
- 等待下一次信号生成（根据SIGNAL_INTERVAL_MINUTES配置）
- 或手动触发一次: `docker compose exec scheduler python /app/scripts/generate_trading_signal.py`
- 在钉钉群中查看通知消息

祝交易顺利！🚀