钉钉群机器人通知 API
概述
钉钉群机器人通知功能允许系统在用户进行积分兑换时，自动发送美观的互动卡片消息到指定的钉钉群，让管理员能够第一时间了解兑换情况。
功能特性
- 🎯 实时推送 - 用户兑换商品后立即发送通知
- 🎨 美观卡片 - 结构化的互动卡片消息，信息清晰
- 👤 用户信息 - 显示兑换用户的详细信息
- 🛒 兑换详情 - 商品名称、数量、积分消耗等
- ⏰ 时间记录 - 精确的兑换时间记录
- 🔗 快捷操作 - 提供"立即审核"和"查看详情"按钮
- 🔒 安全配置 - 支持签名验证和关键词验证
API 端点
获取钉钉配置
获取当前的钉钉群机器人配置信息。
http
GET /api/admin/dingtalk-config请求头：
Authorization: Bearer <token>
Content-Type: application/json响应示例：
json
{
"webhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
"secret": "SECxxx",
"keyword": "",
"enabled": true,
"isEnabled": true
}更新钉钉配置
更新钉钉群机器人配置信息。
http
POST /api/admin/dingtalk-config请求头：
Authorization: Bearer <token>
Content-Type: application/json请求体：
json
{
"webhookUrl": "https://oapi.dingtalk.com/robot/send?access_token=xxx",
"secret": "SECxxx",
"keyword": "学习追踪",
"enabled": true
}字段说明：
webhookUrl(string, 必需): 钉钉机器人的 Webhook URLsecret(string, 可选): 签名密钥，用于消息安全验证keyword(string, 可选): 消息关键词过滤enabled(boolean, 必需): 是否启用钉钉通知
响应示例：
json
{
"success": true,
"message": "配置更新成功"
}测试钉钉连接
发送测试消息到钉钉群，验证配置是否正确。
http
POST /api/admin/dingtalk-config/test请求头：
Authorization: Bearer <token>
Content-Type: application/json请求体：
json
{}响应示例：
json
{
"success": true,
"message": "测试消息发送成功"
}通知消息格式
积分兑换通知
当用户进行积分兑换时，系统会自动发送以下格式的互动卡片消息：
🎁 新的积分兑换申请
---
### 👤 用户信息
👤 用户名：admin
📧 邮箱：admin@example.com
---
### 🛒 兑换详情
📦 商品名称：学习报告
🔢 兑换数量：1件
💎 消耗积分：50积分
✅ 兑换状态：✅ 已完成
⏰ 申请时间：2025/07/30 21:42:15
---
### 📋 操作提示
请及时处理兑换申请，确保用户体验！
---
*此消息由系统自动发送*测试消息
测试连接时发送的消息格式：
🔔 钉钉通知测试消息
---
### ✅ 配置验证成功
⏰ 测试时间：2025/07/30 21:42:30
🤖 机器人状态：正常运行
🔗 连接状态：已连接
---
### 📋 测试说明
如果您收到此消息，说明钉钉群机器人配置正确！
系统将能够正常发送积分兑换通知。
---
### 🎯 下一步
现在可以进行积分兑换测试，系统会自动发送通知到群聊。
---
*此消息由系统自动发送*错误处理
常见错误码
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 400 | 请求参数错误 | 检查请求参数格式 |
| 401 | 未授权访问 | 检查认证令牌 |
| 403 | 权限不足 | 确认用户具有管理员权限 |
| 500 | 服务器内部错误 | 检查服务器日志 |
钉钉API错误
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 0 | 成功 | - |
| 1 | 时间戳无效 | 检查系统时间是否准确 |
| 2 | 签名无效 | 检查签名密钥是否正确 |
| 3 | 关键词不匹配 | 检查消息是否包含关键词 |
| 4 | 请求过于频繁 | 等待一段时间后重试 |
| 5 | 机器人被禁用 | 在钉钉群中重新启用机器人 |
安全配置
签名验证
强烈建议启用签名验证以确保消息安全性：
- 在钉钉机器人设置中启用签名验证
- 获取签名密钥
- 在系统配置中填入签名密钥
关键词过滤
可以设置关键词过滤，只接收包含特定关键词的消息：
- 在钉钉机器人设置中配置关键词
- 在系统配置中填入相同的关键词
访问控制
- 只有管理员用户可以访问钉钉配置功能
- 配置信息存储在数据库中，使用加密传输
- 敏感信息（如签名密钥）在日志中会被脱敏处理
配置示例
环境变量配置
env
# 钉钉群机器人配置（可选）
DINGTALK_WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxx
DINGTALK_SECRET=SECxxx
DINGTALK_KEYWORD=学习追踪
DINGTALK_ENABLED=true数据库配置
钉钉配置信息存储在 system_config 表中：
sql
-- 钉钉配置表结构
SELECT * FROM system_config WHERE key LIKE 'dingtalk%';配置项包括：
dingtalk_webhook_url: Webhook URLdingtalk_secret: 签名密钥dingtalk_keyword: 关键词dingtalk_enabled: 启用状态
最佳实践
1. 安全配置
- 启用签名验证
- 设置强密码的签名密钥
- 定期更换签名密钥
2. 消息管理
- 设置合适的关键词过滤
- 避免发送过于频繁的消息
- 监控消息发送状态
3. 错误处理
- 实现重试机制
- 记录发送日志
- 设置告警机制
4. 性能优化
- 使用异步发送
- 实现消息队列
- 避免阻塞主业务流程
故障排除
常见问题
消息发送失败
- 检查 Webhook URL 是否正确
- 确认机器人是否被禁用
- 验证签名密钥是否正确
消息格式错误
- 检查消息内容是否包含特殊字符
- 确认消息长度是否超限
- 验证 Markdown 格式是否正确
权限问题
- 确认用户具有管理员权限
- 检查认证令牌是否有效
- 验证数据库连接是否正常
调试方法
查看日志
bashtail -f logs/app.log | grep dingtalk测试连接
bashcurl -X POST /api/admin/dingtalk-config/test \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{}'检查配置
bashcurl -X GET /api/admin/dingtalk-config \ -H "Authorization: Bearer <token>"
🔧 最新修复
钉钉通知API更新 (2025-01-XX)
修复内容：
- 修复了钉钉通知配置的存储和读取问题
- 优化了消息发送的异步处理机制
- 改进了错误处理和重试逻辑
- 增强了消息格式的兼容性
技术改进：
- 完善了钉钉配置的数据库存储机制
- 优化了消息发送的异步队列处理
- 改进了签名验证和关键词过滤逻辑
- 增强了消息发送的容错性
API影响：
- 钉钉配置API现在更加稳定可靠
- 消息发送成功率显著提升
- 错误处理更加完善
- 支持更多的消息格式和内容
新增功能：
- 支持批量消息发送
- 增加了消息发送状态追踪
- 提供了更详细的错误信息
- 支持消息发送历史记录