dev-toolkit-integrator

name	dev-toolkit-integrator
description	开发工具链集成操作指南：禅道+Jira+Wiki在迭代开发中的标准化操作流程、跨工具信息同步模板、状态流转规范。当用户说'创建禅道任务'、'写Wiki文档'、'Jira状态更新'、'需求怎么流转'、'Bug提单'、'迭代规划'、'发布版本'、'同步三个平台'时触发。核心特点：三工具联动模板、信息一次性录入多处复用、减少重复劳动、开发迭代全生命周期覆盖。

来源: 自建（基于国内开发团队禅道+Jira+Wiki/Confluence/语雀的真实工作流）

发布时间: 2026-05-28

理念: "同一个需求，不要在三个工具里写三遍。写一次，同步三处。"

🔧 Dev Toolkit Integrator — 禅道·Jira·Wiki 三工具集成操作指南

开发迭代中，禅道管任务、Jira 管需求、Wiki 管文档——这个 Skill 教你让它们说同一种语言。

---

🎯 核心设计：一次录入，三处复用

信息源头          同步目标
─────────────────────────────────
Jira Epic/Story → 禅道需求/任务
禅道 Bug          → Jira Issue + Wiki 故障分析
Wiki 技术方案     → 禅道任务描述 + Jira 描述
代码 Commit       → 禅道任务关联 + Jira 状态更新

统一信息单元（UIU: Unified Information Unit）：

每个需求/任务/缺陷，都包含以下字段：

uiu:
  id: "PROJ-001"                    # Jira Issue Key / 禅道编号
  title: "订单退款功能"              # 统一标题
  type: "需求/Bug/任务"              # 类型
  owner: "张三"                      # 负责人
  priority: "P0/P1/P2"              # 优先级
  status: "待开发/开发中/测试中/已上线" # 统一状态映射
  description: "..."                # 统一描述（Markdown）
  acceptance: "..."                 # 验收标准（Gherkin）
  related_docs:                     # 关联文档
    - "Wiki: 技术方案/订单退款"
    - "禅道: 任务 #1234"
    - "Jira: PROJ-001"

---

🏗️ 三工具分工与映射

维度	禅道 (ZenTao)	Jira	Wiki (Confluence/语雀/飞书)
核心定位	国产项目管理+测试管理	敏捷需求+迭代跟踪	知识沉淀+文档协作
需求管理	产品-需求模块	Epic → Story → Sub-task	需求文档 PRD
任务拆分	任务模块（开发/测试）	Sprint Board 任务卡	技术方案/拆分工时
缺陷跟踪	Bug 模块（最常用）	Bug Issue Type	故障复盘/根因分析
测试管理	用例+测试单+报表	Zephyr/Xray 插件	测试报告/验收文档
迭代管理	产品-迭代	Sprint + Board	迭代计划/ retro
报表统计	内置报表（燃尽图等）	Dashboard + JQL	周报/月报/总结

状态映射表（关键！）

统一状态	禅道	Jira	说明
待规划	草稿	Backlog	需求池，未排期
待开发	激活/进行中	To Do	已分配，未开始
开发中	进行中	In Progress	正在编码
待测试	已解决	Ready for Test	开发完成，提测
测试中	测试中	In Testing	QA 测试中
已验收	已关闭	Done	测试通过
已上线	已关闭（加标签）	Closed	生产验证通过
已驳回	已关闭（加原因）	Rejected	需求变更/不做了

---

🔄 场景一：需求从 Jira 到禅道到 Wiki（正向流转）

场景：产品同学在 Jira 提了 Story，需要拆任务、写方案、同步禅道。

Step 1: Jira 侧 — 需求澄清

# Jira Story 模板

## 标题
[模块] 一句话描述需求

## 描述
作为 [角色]，我希望 [功能]，以便 [价值]

## 验收标准（Gherkin）
Given [前提]
When [操作]
Then [结果]

## 优先级
P0 - 阻塞上线 / P1 - 迭代必须 / P2 - 有则更好

## 关联
- Wiki 需求文档: [链接]
- 设计稿: [链接]
-  Epic: [PROJ-xxx]

Step 2: Wiki 侧 — 写技术方案

# 技术方案：订单退款功能

## 需求来源
- Jira: PROJ-001
- 禅道需求: #1234
- 产品负责人: 李四

## 现状分析
[当前系统状态]

## 方案设计
[架构图/流程图]

## 接口变更
| 接口 | 变更类型 | 说明 |
|------|---------|------|
| POST /api/order/refund | 新增 | 创建退款 |

## 数据库变更
| 表 | 变更 | 脚本 |
|----|------|------|
| refund_record | 新增表 | V20260528__add_refund_record.sql |

## 任务拆分（同步禅道）
| 禅道任务 | 负责人 | 工时 | 依赖 |
|----------|--------|------|------|
| #5678 退款接口开发 | 张三 | 8h | 无 |
| #5679 退款单测 | 张三 | 4h | #5678 |
| #5680 集成测试 | 王五 | 4h | #5679 |

## 风险与回滚
[风险点 + 回滚方案]

## 审批
- [ ] 技术负责人
- [ ] 测试负责人

Step 3: 禅道侧 — 拆任务+建迭代

禅道操作清单：

□ 产品 → 需求 → 关联 Jira Story（标题复制，描述贴 Wiki 链接）
□ 项目 → 迭代 → 建 Sprint（名称与 Jira Sprint 一致）
□ 项目 → 任务 → 按 Wiki 方案拆分任务
  ├── 类型：开发/测试/设计/文档
  ├── 关联需求：#1234
  ├── 预估工时：按 Wiki 方案填
  └── 负责人：指定到人
□ 项目 → 任务 → 设置任务依赖关系

信息同步检查表

## 需求同步检查表

| 检查项 | 禅道 | Jira | Wiki | 状态 |
|--------|------|------|------|------|
| 标题一致 | #1234 | PROJ-001 | 订单退款功能 | ☐ |
| 描述链接互相关联 | 含 Wiki 链接 | 含 Wiki 链接 | 含 Jira+禅道编号 | ☐ |
| 负责人一致 | 张三 | 张三 | 张三 | ☐ |
| 优先级一致 | P1 | High | P1 | ☐ |
| 状态映射正确 | 进行中 | In Progress | - | ☐ |

---

🔄 场景二：Bug 从发现到关闭（全链路）

场景：测试发现 Bug，提禅道，同步 Jira，修复后写 Wiki 根因分析。

Step 1: 禅道侧 — 提 Bug（信息最全）

# 禅道 Bug 模板

## 标题
[模块] 一句话描述 Bug

## 重现步骤
1. 登录系统，进入订单管理
2. 选择订单 #20240528001
3. 点击"退款"按钮
4. 输入金额 99999
5. 点击确认

## 实际结果
系统报错 500，无友好提示

## 期望结果
提示"退款金额不能超过订单实付金额"

## 环境
- 分支: feat/refund-v2
- 版本: v2.3.1-beta
- 浏览器: Chrome 120
- 数据库: MySQL 8.0

## 截图/日志
[附件]

## 关联
- 禅道任务: #5678
- Jira: PROJ-001
- 发现人: 测试-王五
- 负责人: 开发-张三

Step 2: Jira 侧 — 同步 Bug Issue

# Jira Bug Issue

## 标题
[Bug] 退款金额校验缺失导致 500 错误

## 描述
[复制禅道描述]

## 标签
bug, backend, refund, P1

## 关联
- Blocks: PROJ-001
- Related: 禅道 Bug #4567

Step 3: 修复后 — Wiki 写根因分析

# 故障复盘：退款金额越界导致 500

## 基本信息
| 项 | 值 |
|----|----|
| 禅道 Bug | #4567 |
| Jira | BUG-089 |
| 发现时间 | 2026-05-28 |
| 修复时间 | 2026-05-28 |
| 影响范围 | 退款功能 |
| 是否线上 | ☐ 是 ☑ 否（测试环境发现） |

## 根因分析
1. **直接原因**: Service 层缺少金额上限校验
2. **技术原因**: 入参校验只做了 @NotNull，没做 @Max
3. **流程原因**: Code Review 时未识别此边界条件

## 修复方案
- Commit: `fix: 添加退款金额上限校验`
- 文件: OrderService.java
- 方案: 校验 amount <= actualPayAmount

## 预防措施
- [ ] 补充同类接口的金额校验检查
- [ ] Code Review 检查清单增加"金额边界"
- [ ] 集成测试用例补充越界场景

## 经验教训
[教训]

Step 4: 禅道+Jira 状态同步

禅道: Bug #4567 → 已解决 → 已关闭（验证通过）
Jira: BUG-089 → In Progress → Resolved → Closed

---

🔄 场景三：迭代规划（三工具联动）

场景：新 Sprint 开始，需要在三个平台同步建迭代、排任务。

三工具同步操作

# Sprint 2026S13 迭代规划

## 基本信息（三平台一致）
- 名称: 2026S13（5.27-6.9）
- 目标: 完成退款功能 + 账户安全升级
- 人数: 5人（3开发 + 1测试 + 1产品）
- 工时: 10天 × 5人 × 6h = 300h

## Jira 侧
□ 创建 Sprint 2026S13
□ 从 Backlog 拉 Story 到 Sprint
□ 设置 Sprint 目标
□ 启动 Sprint

## 禅道侧
□ 产品 → 迭代 → 建迭代 2026S13
□ 关联需求到迭代
□ 项目 → 任务 → 按人分配
□ 设置任务起止时间

## Wiki 侧
□ 创建"2026S13 迭代计划"页面
□ 包含：目标/人员/Story列表/风险/里程碑
□  retro 模板预创建

---

🔄 场景四：版本发布（三工具收尾）

发布前检查清单

# 版本发布检查清单 v2.4.0

## 禅道侧
□ 所有 Bug 已关闭
□ 所有任务已关闭
□ 测试单通过率 100%
□ 迭代状态：已完成

## Jira 侧
□ Sprint 已关闭
□ 所有 Story Done
□ Release 已创建
□ 版本号：v2.4.0

## Wiki 侧
□ 发布说明已编写
□ 变更日志已更新
□ 操作手册已更新
□ 回滚方案已确认

## 代码侧
□ main 分支已打 tag v2.4.0
□ CHANGELOG.md 已更新
□ 数据库迁移脚本已确认

Wiki 发布说明模板

# v2.4.0 发布说明

## 发布概要
- 版本号: v2.4.0
- 发布时间: 2026-06-10
- 禅道迭代: 2026S13
- Jira Release: v2.4.0

## 新增功能
| 功能 | 禅道需求 | Jira | 负责人 |
|------|---------|------|--------|
| 订单退款 | #1234 | PROJ-001 | 张三 |

## 修复缺陷
| Bug | 禅道 | Jira | 严重级别 |
|-----|------|------|---------|
| 退款越界 500 | #4567 | BUG-089 | P1 |

## 技术变更
- 数据库: 新增 refund_record 表
- 接口: 新增 POST /api/order/refund
- 配置: 无变更

## 回滚方案
如有异常，回滚至 v2.3.2，执行回滚脚本 rollback_v2.4.0.sql

## 验证方式
1. 登录测试环境
2. 执行退款流程
3. 检查监控告警

---

📝 常用操作速查

禅道速查

操作	路径	快捷键/技巧
提 Bug	测试 → Bug → 提Bug	批量创建用"批量添加"
建任务	项目 → 任务 → 建任务	用"批量添加"拆任务
更新状态	任务详情 → 开始/完成/关闭	看板视图拖拽
关联需求	任务 → 相关需求 → 关联	自动带需求描述
生成报表	项目 → 统计 → 燃尽图	导出 Excel

Jira 速查

操作	路径	JQL 示例
查我的任务	搜索 → 高级	assignee = currentUser() AND status != Closed
Sprint 规划	Backlog → 拖拽	-
状态流转	看板拖拽 / 详情页按钮	-
批量操作	搜索结果 → 批量操作	最多 100 条
生成报表	项目 → 报告	燃尽图、速度图、累积流

Wiki 速查

操作	路径	模板
写技术方案	空间 → 创建 → 页面	见本 Skill 技术方案模板
写迭代计划	空间 → 创建 → 页面	见迭代规划模板
故障复盘	空间 → 创建 → 页面	见 Bug 复盘模板
发布说明	空间 → 创建 → 页面	见发布说明模板
同步更新	编辑 → 更新关联链接	确保三工具链接互相关联

---

💡 自动化建议（进阶）

用 Git Commit 触发状态更新

# Commit message 规范
feat(PROJ-001): 添加退款金额校验

- 校验 amount <= actualPayAmount
- 关联禅道任务 #5678
- Closes BUG-089

配合 CI 脚本：

• 解析 Commit 中的 Jira Key → 自动更新 Jira 状态为 "In Progress"
• 解析 Commit 中的禅道任务号 → 自动更新禅道任务为 "进行中"
• 解析 "Closes" → 自动更新关联 Bug 为 "已解决"

用 PR 模板强制信息完整

# PR 模板

## 关联
- Jira: [ ]
- 禅道任务: [ ]
- 禅道 Bug: [ ]
- Wiki 技术方案: [ ]

## 变更
[描述]

## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过

---

🚀 快速入口

"创建禅道任务" → 禅道任务模板 + 关联需求/Bug
"写Wiki文档" → 技术方案/迭代计划/复盘/发布说明模板
"Jira状态更新" → 状态映射 + 批量操作
"需求怎么流转" → Jira→Wiki→禅道正向流转
"Bug提单" → 禅道Bug模板 + Jira同步 + Wiki根因分析
"迭代规划" → 三工具同步建Sprint
"发布版本" → 发布检查清单 + Wiki发布说明
"同步三个平台" → 信息同步检查表

---

🆚 与现有 Skill 的关系

Skill	关系	协作场景
backend-change-flow	前置	开发变更前，用本 Skill 在禅道/Jira 创建任务，再用 backend-change-flow 开发
solo-parallel-dev	互补	并行开发多个 feature 时，用本 Skill 管理各 feature 在三工具中的任务
create-pr	后置	代码完成后，PR 中关联禅道/Jira/Wiki，形成完整链路
quality-gate	后置	提交前检查是否关联了三工具的对应 Issue
openspec-sdd	前置	需求澄清后，用本 Skill 把 Gherkin 验收标准同步到 Jira + 禅道 + Wiki

最佳实践链：

openspec-sdd（需求澄清）
  → dev-toolkit-integrator（同步到禅道/Jira/Wiki）
  → backend-change-flow（编码开发）
  → quality-gate（提交检查）
  → create-pr（生成 PR，关联三工具）
  → dev-toolkit-integrator（更新状态/写复盘/发版本）

---

"工具是手段，不是目的。三工具集成的终极目标，是让信息只写一次，让状态一眼可见，让复盘有据可查。"