180 lines
5.0 KiB
Markdown
180 lines
5.0 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（同时用于获取任务和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. 用户映射配置
|
||
|
||
用户映射支持两种方式：
|
||
|
||
#### 方式一：邮箱映射（推荐）
|
||
```yaml
|
||
user-mapping:
|
||
"user@iscmtech.com": "13800138000" # 禅道用户邮箱 -> 手机号
|
||
```
|
||
|
||
#### 方式二：用户名映射
|
||
```yaml
|
||
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` - 禅道用户实体类
|