# 禅道集成功能说明

## 功能概述

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

## 配置说明

### 1. 禅道配置

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

```yaml
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
        # 用户映射：禅道邮箱 -> 企业微信手机号
        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. 用户映射配置

用户映射支持两种方式：

#### 方式一：邮箱映射（推荐）
```yaml
user-mapping:
  "user@iscmtech.com": "13800138000"  # 禅道用户邮箱 -> 手机号
```

#### 方式二：用户名映射
```yaml
user-mapping:
  "zhangsan": "13900139000"  # 禅道用户名 -> 手机号
```

### 3. 企业微信@人格式

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

## API接口

### 测试禅道连接
```
GET /api/reminder/zentao/test/{groupId}
```

### 手动触发禅道任务提醒
```
POST /api/reminder/zentao/reminder/{groupId}
```

### 手动触发指定群组提醒
```
POST /api/reminder/groups/{groupId}/morning
POST /api/reminder/groups/{groupId}/evening
```

## 消息格式

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

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

## 使用步骤

1. **配置禅道信息**：在配置文件中填入正确的禅道地址、用户名、密码和项目ID
2. **配置用户映射**：将团队成员的禅道邮箱映射到企业微信手机号
3. **测试连接**：调用测试API确认禅道连接正常
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` - 禅道用户实体类