qiangdanxitong/钉钉个人通知配置指南.md

钉钉个人通知配置指南

📱 功能说明

系统现在支持两种钉钉通知方式：

1. 个人通知（工作消息） ⭐ 推荐

   • 直接发送给指定用户
   • 用户在钉钉"工作"Tab收到
   • 隐私性强，送达率高

2. 群通知（机器人消息）

   • 发送到群聊
   • 所有群成员可见
   • 适合公告、团队提醒

---

🔧 方式一：个人通知配置

第一步：创建企业内部应用

1. 访问钉钉开放平台

   • 网址：https://open-dev.dingtalk.com/
   • 使用管理员账号登录

2. 创建应用

   应用开发 → 企业内部开发 → 创建应用
   
   应用信息：
   ├─ 应用名称：设计Hub通知
   ├─ 应用描述：任务管理系统通知
   └─ 应用图标：（可选上传）
   

3. 获取应用凭证

   创建成功后，在应用详情页可以看到：

   • AgentId（应用ID）

     示例：1234567890
     

   • AppKey（应用Key）

     示例：dingabcdefghij1234567890
     

   • AppSecret（应用密钥）

     点击"显示"并复制
     示例：abcdefghijklmnopqrstuvwxyz123456
     

4. 配置应用权限

   在应用详情页 → 权限管理，添加以下权限：

   ✅ 通讯录只读权限（获取部门及员工信息）
   ✅ 企业内部机器人发送消息（发送工作通知）
   ✅ 消息通知（必需）
   

5. 发布应用

   版本管理与发布 → 发布
   
   可见范围：
   ☑️ 全部员工（推荐）
   或
   ☑️ 指定部门/员工
   

6. 获取企业ID (CorpId)

   钉钉管理后台 → 企业信息 → 企业ID (CorpId)
   

第二步：在系统中配置

登录系统 → 系统设置 → 钉钉集成

应用配置

AgentId:     1234567890
AppKey:      dingabcdefghij1234567890
AppSecret:   abcdefghijklmnopqrstuvwxyz123456
企业ID:       ding1234567890abcdef

启用功能

☑️ 消息通知  ← 必须勾选，启用个人通知
☑️ 钉钉登录  ← 可选，方便用户登录
☑️ 用户同步  ← 可选，自动同步部门

点击 "保存配置" → "测试连接"

---

🤖 方式二：群通知配置（可选）

第一步：创建群机器人

1. 创建或打开钉钉群聊

   • 建议创建专门的通知群
   • 例如："设计Hub系统通知"

2. 添加机器人

   群设置 → 群机器人 → 添加机器人 → 自定义（通过Webhook接入）
   

3. 配置机器人

   机器人名称：设计Hub通知机器人
   

4. 安全设置（三选一）

   方式A：加签验证（推荐）

   ☑️ 加签
   系统会生成密钥（SEC开头）
   复制此密钥，稍后填入系统
   

   方式B：自定义关键词（简单）

   ☑️ 自定义关键词
   关键词：任务、通知、提醒
   （消息必须包含其中一个关键词）
   

   方式C：IP地址

   ☑️ IP地址（段）
   服务器IP：45.192.99.48
   

5. 完成并获取Webhook

   复制Webhook地址：
   https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxx
   

第二步：在系统中配置

系统设置 → 钉钉集成 → 机器人配置

机器人Webhook地址：
https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxx

机器人密钥（如果使用加签）：
SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

点击 "发送测试消息" 查看群里是否收到

---

👥 第三步：用户绑定钉钉ID

方法A：通过钉钉登录（自动绑定）⭐ 推荐

1. 用户点击登录页的"钉钉登录"
2. 扫码或输入账号密码登录
3. 系统自动获取并保存钉钉ID
4. ✅ 绑定完成，可以接收个人通知

方法B：部门同步（批量绑定）

1. 系统设置 → 钉钉集成 → 部门同步
2. 点击"同步钉钉部门"
3. 用户下次登录时自动匹配部门和钉钉ID

方法C：手动设置（开发调试）

在数据库中手动设置用户的 ding_user_id 字段：

-- 查询钉钉用户ID（在钉钉管理后台查看）
-- 然后更新到系统用户表
UPDATE sys_user 
SET ding_user_id = '钉钉userId' 
WHERE username = '用户名';

---

📊 通知效果对比

特性	群机器人	工作通知（个人）
配置难度	⭐ 简单	⭐⭐ 中等
通知对象	群成员	指定个人
隐私性	低	高 ⭐⭐⭐⭐⭐
送达率	中等	高 ⭐⭐⭐⭐⭐
用户体验	⭐⭐⭐	⭐⭐⭐⭐⭐
适用场景	公告、汇总	任务、审核、私密消息

---

🎯 推荐通知策略

个人通知（工作消息）

✅ 任务分配给我
✅ 待我审核
✅ 任务被驳回
✅ 进度催办
✅ 获得积分
✅ 评审结果

群通知（机器人）

✅ 系统公告
✅ 每日任务汇总
✅ 排行榜更新
✅ 重要提醒

---

✅ 功能验证

测试个人通知

1. 确保用户已绑定钉钉ID
2. 创建一个任务并分配给该用户
3. 检查用户钉钉"工作"Tab是否收到通知

测试群通知

1. 点击"发送测试消息"按钮
2. 检查钉钉群是否收到消息

---

🔍 故障排查

个人通知未收到

检查清单：

1. ✅ 钉钉应用配置是否正确？

   • AgentId、AppKey、AppSecret 是否填写正确
   • 企业ID是否正确

2. ✅ 应用权限是否添加？

   • 通讯录只读权限
   • 企业内部机器人发送消息

3. ✅ 应用是否发布？

   • 应用必须发布且对用户可见

4. ✅ 用户是否绑定钉钉ID？

   -- 检查用户的钉钉ID
   SELECT id, username, real_name, ding_user_id 
   FROM sys_user 
   WHERE id = 用户ID;
   

   • 如果 ding_user_id 为空，需要通过钉钉登录绑定

5. ✅ 功能是否启用？

   • 系统设置 → 钉钉集成 → 消息通知（必须勾选）

群通知未收到

检查清单：

1. ✅ Webhook地址是否正确？
2. ✅ 密钥是否正确（如果使用加签）？
3. ✅ 消息内容是否包含关键词（如果使用关键词验证）？
4. ✅ IP是否正确（如果使用IP验证）？

查看后端日志

# 查看钉钉推送日志
ssh root@服务器IP
tail -f /opt/designhub/logs/application.log | grep -i "dingtalk\|notification"

---

📞 技术支持

如有问题，请查看系统日志或联系技术支持。

• 后端日志：/opt/designhub/logs/application.log
• 关键字：DingTalkService、NotificationService

---

🎉 配置完成！

现在您的系统支持：

• ✅ 个人通知（私密、高送达）
• ✅ 群通知（公开、团队可见）
• ✅ 自动推送（异步处理，不影响性能）

祝使用愉快！