1. 概述

本文档详细描述了在若依框架基础上集成钉钉消息推送功能的开发步骤。该功能允许系统向指定钉钉用户发送文本和富文本消息通知。

2. 环境准备

2.1 钉钉开发者账号配置

1. 登录钉钉开发者平台：https://open.dingtalk.com/
2. 创建/选择企业内部应用
3. 获取以下关键信息：
   • AppKey: dingvngxxxxx
   • AppSecret: 0uyedo8zroBN4CCGy8ESxxxxxxx
   • AgentId: 3xxx

2.2 应用权限配置

1. 在钉钉开发者后台为应用添加以下权限：
   • 通讯录管理权限（获取用户ID）
   • 工作通知权限（发送消息）
2. 发布应用到测试/生产环境
3. 设置应用可见范围，确保测试用户在可见范围内

3. API接口测试

3.1 获取access_token

请求：

GET https://oapi.dingtalk.com/gettoken?appkey=dingxxxxxxxxx&appsecret=0uyedo8xxxxxxxxxx

响应：

{"errcode": 0,"access_token": "获取到的access_token","errmsg": "ok","expires_in": 7200
}

3.2 发送文本消息

请求：

POST https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=上一步获取的access_token
Content-Type: application/json{"agent_id": "3828659278","userid_list": "钉钉用户ID","msg": {"msgtype": "text","text": {"content": "这是一条测试消息"}}
}

响应：

{"errcode": 0,"task_id": 329537971320,"errmsg": "ok","request_id": "15rqb5jfvarmn"
}

3.3 发送富文本消息

请求：

POST https://oapi.dingtalk.com/topapi/message/corpconversation/asyncsend_v2?access_token=上一步获取的access_token
Content-Type: application/json{"agent_id": "3828659278","userid_list": "钉钉用户ID","msg": {"msgtype": "markdown","markdown": {"title": "测试富文本消息","text": "### 测试标题\n- 项目1\n- 项目2\n\n**加粗文本**"}}
}

4. 后端实现步骤

4.1 创建钉钉模块

1. 创建 ruoyi-dingtalk 模块，配置 pom.xml 依赖：
   • 添加钉钉开放平台SDK依赖
   • 添加若依通用依赖

4.2 配置文件设置

1. 在 application.yml 中添加钉钉配置：

   dingtalk:appkey: dingvxxxxappsecret: 0uyedo8zroBNxxxxxxxagentid: 38xxxxxxx
   

4.3 创建实体类和DTO

1. 创建消息发送请求DTO：
   • DingTalkMessageDTO: 包含消息类型、内容、接收人等信息
   • TextMessageDTO: 文本消息
   • MarkdownMessageDTO: 富文本消息

4.4 实现核心服务类

1. 创建 DingTalkTokenService：

   • 实现获取和缓存 access_token 的功能
   • 使用 Redis 存储 token，设置过期时间

2. 创建 DingTalkMessageService：

   • 实现发送各类消息的方法
   • 处理API响应和异常情况

4.5 封装HTTP请求工具

1. 创建 DingTalkHttpClient：
   • 封装对钉钉API的HTTP请求
   • 处理响应解析和错误处理

4.6 实现Controller层

1. 创建 DingTalkTestController：
   • 提供测试发送消息的接口
   • 支持文本和富文本消息发送

5. 前端实现步骤

5.1 创建API接口文件

1. 在 src/api 下创建 dingtalk.js：
   • 实现调用后端发送消息的接口

5.2 创建测试页面

1. 创建 views/tool/dingtalkTest/index.vue 页面：
   • 包含富文本编辑器
   • 添加接收人选择功能
   • 添加消息类型选择（文本/富文本）
   • 添加发送按钮

5.3 配置路由

1. 在路由配置中添加钉钉测试页面：
   • 配置路径、组件、权限等

6. 用户ID获取与验证

6.1 实现用户查询接口

1. 创建 DingTalkUserService：
   • 调用钉钉API获取企业用户列表
   • 提供用户ID查询方法

6.2 前端用户选择组件

1. 实现钉钉用户选择组件：
   • 可搜索、选择企业内用户
   • 支持多选功能

7. 关键注意事项

1. 用户ID验证：

   • 务必通过钉钉API获取正确的用户ID
   • 不可手动输入用户ID，避免格式错误

2. Token管理：

   • 妥善处理access_token的缓存与过期刷新
   • 避免频繁请求token，考虑并发请求情况

3. 错误处理：

   • 完善的错误日志记录
   • 合理的异常处理和用户提示

4. 性能考虑：

   • 批量发送机制
   • 异步处理大量消息发送请求

8. 测试与验证

1. 单元测试：

   • 测试token获取
   • 测试消息发送

2. 集成测试：

   • 测试完整发送流程
   • 验证实际钉钉接收效果

9. 后续扩展方向

1. 实现更多消息类型：

   • 卡片消息
   • 图片消息
   • OA消息

2. 实现消息模板功能：

   • 预设常用消息模板
   • 支持变量替换

3. 实现消息发送状态追踪：

   • 记录发送历史
   • 查询消息发送状态

4. 接入工作流系统：

   • 与流程引擎集成
   • 实现任务状态变更通知

10. 附录

常见问题排查

1. 消息发送成功但未收到通知：

   • 检查用户ID是否正确
   • 检查应用权限是否已授权
   • 检查应用是否已发布
   • 验证用户是否在应用可见范围内

2. API返回错误：

   • 检查access_token是否有效
   • 检查请求参数格式
   • 查看钉钉开发者后台的错误日志