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/status/test/{groupId}

功能: 测试禅道连接，同时获取任务和BUG数据

手动触发禅道项目状态提醒（推荐）

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

功能: 发送统一的项目状态提醒，包含任务和BUG

测试禅道任务连接（兼容性）

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

手动触发禅道任务提醒（兼容性）

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

注意: 现在也会包含BUG信息

测试禅道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严重程度
• 📅 截止日期信息

示例消息：

**禅道项目状态提醒**
项目: [2025-06-08]一站式平台

📊 项目概况
未完成任务: 2个，已过期: 2个
未解决BUG: 1个

邓启辰 (3个事项)
- 🔴 [任务238] 测试任务2 (2025-05-28)
- 🔴 [任务236] 测试任务 (2025-05-28)
- 🐛 [BUG911] 测试BUG [一般] (2025-05-29)

请及时登录禅道系统更新状态

单独提醒消息格式（兼容性）

如果使用单独的任务或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 - 禅道用户实体类