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是否有效
   • 檢查請求參數格式
   • 查看釘釘開發者后臺的錯誤日志