134 lines
3.8 KiB
Markdown
134 lines
3.8 KiB
Markdown
# 禅道集成功能说明
|
||
|
||
## 功能概述
|
||
|
||
本系统已集成禅道开源版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` - 禅道用户实体类
|