task-reminder/ZENTAO_INTEGRATION.md

禅道集成功能说明

功能概述

本系统已集成禅道开源版20.8的API，可以自动查询项目中的未完成任务，并通过企业微信发送详细的任务提醒，支持@相关负责人。

配置说明

1. 禅道配置

在 application.yml 中配置禅道相关信息：

task:
  reminder:
    groups:
      - id: "zentao-team"
        name: "禅道开发团队"
        webhook:
          url: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=your-webhook-key"
        task-system: "zentao"  # 必须设置为 zentao
        # 禅道配置
        zentao:
          api-url: "https://zentao.iscmtech.com"  # 禅道地址
          username: "your-username"               # 禅道用户名
          password: "your-password"               # 禅道密码
          project-id: 26                          # 项目ID（同时用于获取任务和BUG）
        # 用户映射：禅道邮箱 -> 企业微信手机号
        user-mapping:
          "liguiling@iscmtech.com": "13800138000"
          "zhongweiyue@iscmtech.com": "13900139000"
          "meya@iscmtech.com": "13700137000"
        schedules:
          morning:
            time: "0 0 9 * * MON-FRI"
            message: "早上好！请及时更新禅道任务状态"
          evening:
            time: "0 30 17 * * MON-FRI"
            message: "下班前提醒：请更新今日任务完成情况"
        enabled: true

2. 用户映射配置

用户映射支持两种方式：

方式一：邮箱映射（推荐）

user-mapping:
  "user@iscmtech.com": "13800138000"  # 禅道用户邮箱 -> 手机号

方式二：用户名映射

user-mapping:
  "zhangsan": "13900139000"  # 禅道用户名 -> 手机号

3. 企业微信@人格式

• 手机号：13800138000（系统会自动添加@前缀）
• @所有人：all（系统会转换为@all）

API接口

测试禅道任务连接

GET /api/reminder/zentao/test/{groupId}

手动触发禅道任务提醒

POST /api/reminder/zentao/reminder/{groupId}

测试禅道BUG连接

GET /api/reminder/zentao/bugs/test/{groupId}

手动触发禅道BUG提醒

POST /api/reminder/zentao/bugs/reminder/{groupId}

手动触发指定群组提醒

POST /api/reminder/groups/{groupId}/morning
POST /api/reminder/groups/{groupId}/evening

消息格式

任务提醒消息格式

系统会发送包含以下信息的详细任务提醒：

• 📊 任务统计（总数、过期数、涉及人员）
• 👥 按人员分组的任务列表
• 🔴 过期任务标识
• ⚪ 其他状态任务标识
• 📋 任务优先级和截止日期
• 🔗 禅道系统访问链接

BUG提醒消息格式

系统会发送包含以下信息的详细BUG提醒：

• 📊 BUG统计（总数、过期数、涉及人员）
• 👥 按人员分组的BUG列表
• 🔴 过期BUG标识
• 🐛 未解决BUG标识
• 📋 BUG严重程度和截止日期
• 🔗 禅道系统访问链接

使用步骤

1. 配置禅道信息：在配置文件中填入正确的禅道地址、用户名、密码和项目ID
2. 配置用户映射：将团队成员的禅道邮箱映射到企业微信手机号
3. 测试连接：调用测试API确认禅道任务和BUG连接正常
4. 启用定时任务：系统会按配置的时间自动发送提醒

注意事项

1. 禅道版本：目前支持禅道开源版20.8
2. API认证：使用用户名密码方式认证
3. 项目权限：配置的禅道用户需要有项目访问权限
4. 网络连接：确保服务器能访问禅道系统
5. 手机号格式：必须是11位中国大陆手机号

故障排查

1. 禅道连接失败

• 检查禅道地址是否正确
• 检查用户名密码是否正确
• 检查网络连接是否正常

2. 无法获取任务

• 检查项目ID是否正确
• 检查用户是否有项目访问权限
• 查看日志中的详细错误信息

3. @人不生效

• 检查用户映射配置是否正确
• 确认手机号格式是否正确
• 确认企业微信群中是否有对应用户

开发说明

相关代码文件：

• ZentaoApiService.java - 禅道API调用服务
• ZentaoTaskReminderService.java - 禅道任务提醒服务
• UserMappingService.java - 用户映射服务
• ZentaoTask.java - 禅道任务实体类
• ZentaoUser.java - 禅道用户实体类