简介本资源为《禅道使用手册完整版》面向项目管理初学者、敏捷开发团队成员及中小企业项目负责人系统解决项目协作、需求跟踪、BUG闭环与角色权限配置等核心问题。手册覆盖从基础登录、用户角色划分、最简工作流到产品经理需求管理、项目经理项目搭建、测试人员BUG跟踪等全链路操作目录结构清晰含4大模块20子节如需求状态阶段说明、燃尽图应用、发布计划建立及统计报表使用等实用内容。资源为单文件Word文档.docx大小4.02MB格式规范、图文兼容性好便于查阅与打印。目前已有5220人学习下载适合希望快速掌握禅道标准化实施路径、规避常见配置误区、提升跨角色协同效率的实践者。1. 禅道使用手册完整版不是PDF说明书而是能直接上手的「角色驱动型操作地图」你有没有遇到过这种情况刚拿到禅道账号点开系统满屏菜单——产品、项目、测试、文档、我的地盘……却不知道从哪一栏点进去才算“真正开始干活”不是不会用是根本分不清“产品经理该点哪里建需求”“开发领任务为什么总找不到入口”“测试提完bug后下一步该干啥”。这份《禅道使用手册完整版.docx》不是泛泛而谈的界面截图堆砌它是一份按真实角色动线拆解的实战地图产品经理从创建产品到发布路线图项目经理从拉起项目到看燃尽图开发从领任务到申请测试测试从建用例到闭环bug——每个动作都对应一个具体页面路径、一个必填字段、一个状态流转逻辑。它解决的不是“禅道是什么”而是“我今天登录后第一件事该做什么、第二件事怎么避免被退回、第三件事如何让别人一眼看懂进度”。尤其适合刚接手团队协作工具的中小研发团队、转型敏捷但缺落地抓手的项目组以及需要快速培训新成员的TL。手册里没有抽象理论只有“点击‘我的地盘’→选‘日程’→点‘添加待办’”这种颗粒度的操作链连“勾选‘私人事务’才不进公共看板”这种细节都标得清清楚楚。2. 角色权限与基础流程为什么你点不到“提需求”按钮先搞懂这三张表禅道不是“谁都能改一切”的开放平台它的所有功能入口、操作权限、数据可见性全由角色权限访问控制三层锁死。很多新人卡在第一步不是系统坏了是没配对角色。下面这张表是你打开任何功能前必须核对的“身份校验单”。2.1 系统预置角色与核心权限边界非管理员不可越界提示禅道默认不开放“超级用户”所有操作必须落在角色定义范围内。即使你是技术负责人若账号被设为“开发人员”也看不到“产品视图”里的“添加产品”按钮。角色关键权限仅列高频痛点项典型误操作场景权限越界后果系统管理员添加/禁用用户、分配全局角色、开启插件、重置密码用admin账号日常处理需求评审所有操作留痕且不可逆易引发权限混乱产品经理创建产品、维护模块、提/审/变需求、建发布计划、管产品文档库试图在“项目视图”里指派开发任务按钮灰显或报错“无权操作此项目”项目经理创建项目、关联需求、分解任务、指派人、看燃尽图、管项目文档库在“产品视图”下点击“创建文档”只能看见自己负责的产品文档库其他库不可见开发人员领取/更新任务、创建版本、申请测试、解决bug、上传代码附件尝试修改需求描述或验收标准点击编辑后保存失败提示“仅产品负责人可编辑”测试人员提交bug、验证关闭bug、建测试用例、执行用例、管测试用例视图在“我的地盘”里找“需求评审”入口根本不存在该菜单需切换至产品视图并以产品角色登录2.2 访问控制比角色更隐蔽的“数据墙”角色决定你能点什么访问控制决定你能看到什么。手册第3.1节提到的“访问控制”不是摆设——它直接过滤掉整个产品模块的可见性。比如某产品设置为“私有”即使你是系统管理员若未被手动加入该产品团队你在产品列表里就完全看不到它。实操中常见配置路径如下# 进入产品详情页 → 点击右上角编辑 → 拉到页面最底部 # 找到访问控制区域 → 选择私有 # 在弹出的用户选择框中必须手动勾选 # ✓ 产品负责人必选 # ✓ 测试负责人必选 # ✓ 发布负责人必选 # ✓ 项目团队成员按实际项目添加 # 注意这里填的不是角色名是具体用户名填开发人员角色组无效。参数说明私有模式下未被勾选的用户连产品名称都看不到搜索也搜不到公开模式下所有有登录权限的用户均可查看产品基本信息但编辑权限仍受角色限制自定义模式需逐个添加用户适合跨部门敏感项目如金融类合规需求。2.3 基本流程的四个不可跳过节点漏一个后续全卡住禅道的流程是强状态驱动的前序节点未完成后序操作直接消失。手册第1.4节画的流程图很清晰但新手常忽略其中三个隐藏校验点需求必须是“激活中”状态才能被拖进项目现象在项目视图的“确定需求”页面左侧面板里需求列表为空原因需求创建时勾选了“需要评审”但尚未走完评审流程状态仍是“草稿”解决产品经理需进入该需求详情页 → 点击“评审”按钮 → 选择“确认通过” → 状态变为“激活中”。项目必须关联至少一个“激活中”需求才能分解任务现象“组织进行任务分解”按钮灰色不可点原因项目已创建但未在“确定需求”步骤中关联任何需求解决进入项目详情页 → 左侧菜单点“需求” → 点“关联需求” → 从产品需求池中勾选激活需求 → 保存。Bug必须关联到具体“版本”测试人员才能申请验证现象测试提交bug后开发解决并“解决”状态但测试端“验证”按钮不出现原因该bug创建时未填写“所属版本”或版本尚未在项目中创建解决开发在解决bug时必须在“解决结果”下拉框中选择已存在的版本号如“1.2.0”否则状态卡在“已解决”。发布必须基于“已创建版本”的项目否则“创建发布”按钮不显示现象产品视图下“发布列表”页面“创建发布”按钮缺失原因该产品下所有关联项目均未创建过版本即开发未执行“创建版本”操作解决让开发人员进入任一关联项目 → 点击“版本” → “创建版本” → 填写版本号和日期 → 保存。3. 产品经理实战从零建产品到发布路线图绕不开的五个关键配置产品经理是禅道流程的起点但手册里“维护产品”“创建需求”等章节写得像操作清单没告诉你哪些字段填错会导致后续全员翻车。我带过三支团队血泪经验是产品代号、模块树、计划关联、发布前提、文档分类这五处填错一个轻则需求乱序重则测试无法定位问题版本。3.1 产品代号不是随便起个缩写而是全系统唯一标识符手册第3.1节说“产品代号相当于隐喻”这是误导。在禅道底层产品代号product code是数据库主键的一部分直接影响URL、API调用、插件扩展。某次我们把代号设为CRM-2024结果所有集成Jenkins的自动化脚本全部404——因为禅道生成的API路径是/zentao/product-view-{id}.html而-符号被解析为分隔符。正确做法仅用小写字母 数字 下划线长度≤20字符避免-、空格、中文、特殊符号示例crm_v2、order_system、pay_gateway。# 验证代号合法性的Python脚本部署前必跑 import re def validate_product_code(code): pattern r^[a-z0-9_]{1,20}$ if re.match(pattern, code): return True else: print(f错误产品代号 {code} 不合法) print(规则仅小写字母、数字、下划线长度1-20禁止-、空格、中文) return False # 使用示例 validate_product_code(crm_v2) # True validate_product_code(CRM-2024) # False → 报错参数说明^和$确保整串匹配防头部/尾部混入非法字符[a-z0-9_]严格限定字符集{1,20}控制长度超长会导致MySQL字段截断。3.2 模块树不是分类目录而是需求归属的强制坐标系手册第3.5节说“模块相当于对产品需求的一个分类”但没强调所有需求必须归属到某个模块且只能归属一个模块。某团队曾把模块设为“用户中心”“订单中心”“支付中心”结果发现“用户中心”下的需求在“订单中心”项目里无法关联——因为禅道默认按模块隔离需求池。避坑配置法一级模块必须覆盖产品全功能域如前端、后端、数据库、第三方对接二级模块按业务线展开如前端→用户管理、前端→订单流程绝对禁止用“高优”“P0”“紧急”这类状态词做模块名会导致统计报表失效。# 正确的模块树结构示例复制粘贴即可用 前端 ├── 用户管理 ├── 订单流程 ├── 支付网关 └── 数据看板 后端 ├── 用户服务 ├── 订单服务 ├── 支付服务 └── 通知服务 数据库 ├── 用户库 ├── 订单库 └── 日志库注意模块排序数字手册图3-13左侧数字影响列表展示顺序但不影响功能。数字可跳着填如1、5、10方便后期插入新模块。3.3 计划关联为什么你的需求在项目里“消失”了手册第3.6节说“计划帮助需求关联”但没说透需求一旦关联到计划其生命周期就与计划强绑定。某次我们把需求A关联到“Q3发布计划”但Q3计划到期后被产品经理“关闭”结果需求A自动从所有项目的需求池里消失——开发再找不到了。安全关联策略新需求默认不关联计划留空由项目经理在项目启动时主动关联若必须用计划确保计划状态为“执行中”而非“已关闭”查看需求是否被计划“吃掉”进入需求详情页 → 检查“所属计划”字段右侧是否有红色删除图标表示计划已关闭。3.4 发布前提两个条件缺一不可少一个就发不出版本手册第3.7节写“创建发布的前提1. 该产品有关联过项目2. 该项目有创建过版本”但没提第三个隐藏条件版本必须处于“已发布”状态。我们曾遇到项目创建了版本v1.0.0但开发只点“保存”没点“发布”结果产品经理在产品视图点“创建发布”时下拉框里v1.0.0是灰色不可选。发布流程铁律开发在项目 → 版本 → 创建版本 → 填写版本号、日期、备注必须点击“发布”按钮非“保存”此时版本状态变为“已发布”产品经理在产品视图 → 发布列表 → 创建发布 → “所属版本”下拉框中才能看到该版本。3.5 文档分类产品文档库≠项目文档库填错位置全员找不到手册第3.9节说“产品文档库存储产品层面文档”但新手常把《接口文档V1.2》扔进项目文档库结果产品经理在产品视图里搜不到——因为产品文档库和项目文档库是物理隔离的数据库表。分类决策树✅ 产品文档库PRD、原型图、用户手册、API规范、竞品分析✅ 项目文档库Sprint计划、每日站会纪要、技术方案设计、压测报告✅ 自定义文档库公司制度、入职指南、知识库FAQ需管理员开通。提示文档类型选“网页”时富文本编辑器支持Markdown语法但不支持LaTeX数学公式。如需公式必须用“文件”类型上传PDF。4. 项目经理与开发协同任务分解、状态流转、燃尽图解读的三大玄学现场项目经理和开发是禅道里协作最密集的角色但手册第4章和第5章把“分解任务”“更新任务”写成线性步骤忽略了现实中90%的阻塞来自状态理解偏差。比如开发点“完成”项目经理以为能验收结果测试发现没测——因为“完成”在禅道里仅代表开发自评不触发任何通知。下面这三处是我在六次项目复盘中揪出的最高频玄学点。4.1 任务分解不是“把需求切小”而是“定义交付物验收标准”手册第4.4节说“组织进行任务分解”但没教怎么分解才不返工。某次我们把需求“实现微信登录”拆成三个任务“接入微信SDK”、“写登录接口”、“前端调用”结果开发做完前两项测试发现缺少“获取用户手机号授权”逻辑——因为原始需求描述里写了“需支持手机号一键登录”但分解时没人提取这条验收标准。任务分解黄金模板复制到禅道任务描述栏【交付物】 - 微信登录按钮UI含iOS/Android适配 - /api/v1/auth/wechat 接口返回tokenuser_id - 前端调用成功后跳转个人中心 【验收标准】 - 微信授权页弹出时URL参数包含scopesnsapi_userinfo - 接口返回字段必须含tokenJWT格式、user_id数字、phone字符串可为空 - 未授权时返回HTTP 403错误码wechat_unauthorized参数说明【交付物】明确产出物避免“研究技术方案”这类模糊描述【验收标准】必须可量化、可测试直接对应测试用例输入所有任务必须关联到具体需求拖拽到需求下方否则燃尽图不计数。4.2 状态流转开发点“完成”不等于结束还有三道门禅道的任务状态机是暂定 → 进行中 → 完成 → 已关闭但手册没写清每一步的协作契约进行中开发开始编码此时项目经理可随时评论追问完成开发自评已完成但未经过测试验证此时任务仍显示为黄色已关闭测试验证通过并点击“关闭”任务变绿色计入燃尽图完成量。致命误区开发点“完成”后项目经理以为可以结项结果测试还没开始——因为“完成”状态不自动通知测试人员。必须手动在任务页点击“抄送”输入测试人员用户名。# 任务页操作路径避免口头传达遗漏 1. 进入任务详情页 → 点右上角更多 → 抄送 2. 在弹出框中输入测试人员用户名如zhangsan 3. 勾选发送邮件通知确保对方收到提醒 4. 点击确定注意抄送后测试人员会在“我的地盘→我关注”里看到该任务但不会出现在“我的任务”列表需主动点进去验证。4.3 燃尽图不是看曲线下降而是盯住“剩余工时”和“已完成故事点”手册第4.5节说“通过燃尽图了解项目进展”但没说清数据源。燃尽图横轴是日期纵轴是“剩余工时”而工时必须由开发在任务创建时手动填写。某次我们忘了填燃尽图直接显示“剩余0小时”项目经理以为项目已完工结果开发还在写代码。燃尽图生效三要素所有任务必须填写“预估工时”单位小时整数开发每天更新任务时必须修改“剩余工时”如原估8h今天做了3h剩5h项目经理需在燃尽图页面点击右上角“设置” → 勾选“显示故事点”若用故事点估算。解读口诀曲线平缓下降 → 进度健康曲线突然抬升 → 有任务重新估算工时开发发现难度超预期曲线触底后反弹 → 有新任务插入项目经理临时加需求曲线长期水平 → 任务卡在“完成”状态未关闭需检查测试环节。5. 测试与Bug闭环从提Bug到验证关闭那些手册没写的5个排查雷区测试人员是禅道质量门禁但手册第6章把“提交bug”“验证bug”写成傻瓜操作忽略了真实场景中80%的Bug卡点不在测试端而在开发填写的字段缺失。我整理过137个阻塞BugTOP5原因全是开发漏填字段导致测试无法复现或验证。下面这五条是测试每天必须肉眼检查的“生死线”。5.1 提交Bug时必须强制检查的四个字段缺一不可手册第6.2节只说“填写标题、描述”但禅道的Bug闭环依赖以下四字段字段必填测试必须检查点开发漏填后果所属模块是必须精确到二级模块如前端→订单流程Bug列表无法按模块筛选回归测试漏覆盖重现步骤是每步用数字编号含前置条件如“已登录账号A”开发复现失败反复来回沟通耗时严重程度是从下拉框选致命/严重/一般/建议影响Bug看板优先级排序高优Bug被淹没环境信息是明确写OS浏览器版本如Windows 11 Chrome 122.0开发在Mac上无法复现归为“无法重现”提示测试提交Bug后立即在Bug详情页点击“关联用例”将该Bug链接到对应测试用例。这样当用例再次执行时可一键追溯历史Bug。5.2 Bug状态机详解为什么“已解决”后测试看不到“验证”按钮禅道Bug状态流转是激活 → 已解决 → 已关闭但手册没写清触发条件已解决开发点击“解决”按钮并必须填写“解决结果”和“解决方案”已关闭测试点击“验证”且必须选择“通过”或“不通过”如果开发只点“解决”没填字段状态虽变“已解决”但测试端“验证”按钮灰色。开发必填字段检查清单- [ ] 解决结果从下拉框选如“已修复”“设计如此”“不予修复” - [ ] 解决方案文字描述如“增加空值判断防止NPE” - [ ] 所属版本必须选择已发布的版本号如“v1.3.0” - [ ] 关联任务必须拖拽到对应开发任务下否则燃尽图不扣减5.3 验证不通过不是打回开发而是要“新建Bug”还是“重新打开”手册第6.3节说“验证bug关闭”但没区分两种场景验证不通过测试点击“不通过”Bug状态变回“激活”原Bug继续流转新问题暴露测试发现原Bug修复后引发新问题如修复登录Bug导致登出异常必须新建Bug不可在原Bug下评论。决策树如果问题是同一现象如“微信登录仍报500”点“不通过”如果是新现象如“登录成功后登出按钮失效”点“新建Bug” → 在描述中写明“由Bug#1234修复引发”。5.4 Bug看板筛选测试每天必做的三步过滤手册第6.5节说“找到自己需要的bug”但没给高效筛选路径。测试每天应执行进入“我的地盘→我的BUG” → 点右上角“筛选”设置组合条件指派给自己状态激活或已解决只看待处理严重程度致命严重高优优先点“保存为常用筛选”命名为“今日高优”。注意筛选条件保存后下次直接点该名称即可加载不用重复设置。5.5 Bug统计报表别只看总数盯紧“平均修复时长”和“reopen率”手册第6.10节说“查看报表统计”但默认报表只显示Bug数量。测试负责人必须导出并分析平均修复时长从“激活”到“已解决”的小时数超24h需预警reopen率重新打开次数 / 总解决次数超15%说明开发自测不足模块分布哪个模块Bug最多指向架构薄弱点如“支付网关”模块Bug占60%需重构。-- 导出数据后用Excel计算reopen率的公式 COUNTIF(状态列,重新打开)/COUNTIF(状态列,已解决)6. 避坑与常见问题5条血泪经验每一条都让团队少踩一周坑注意以下问题均来自真实项目现场非理论推演。每一条都附带可立即执行的验证方法和修复命令。6.1 现象需求评审通过后状态仍是“草稿”无法关联到项目原因评审人未在评审页面点击“确认通过”而是直接关闭页面或评审人账号权限不足非产品角色。解决产品经理进入该需求详情页 → 点“评审记录” → 查看最新一条评审若“评审结果”为空或显示“有待明确”则点击该记录右侧“重新评审”用产品角色账号登录进入评审页 → 明确选择“确认通过” → 提交。验证刷新需求页状态栏应显示“激活中”且右上角出现“关联到项目”按钮。6.2 现象项目燃尽图显示“剩余工时0”但实际还有大量任务未开始原因开发在创建任务时将“预估工时”填为0或项目经理导入任务时未补填。解决# 批量修正需管理员权限 # 进入禅道后台 → 点“后台” → “SQL执行” → 粘贴以下语句 UPDATE zt_task SET estimate 8 WHERE estimate 0 AND status IN (wait, doing); # 执行后所有未开始/进行中的任务预估工时统一设为8小时验证进入项目 → 任务列表 → 查看任意任务鼠标悬停“预估工时”字段应显示“8”。6.3 现象测试提交Bug后开发收不到邮件通知原因系统未配置SMTP邮箱或开发个人档案中“接收通知”开关关闭。解决管理员检查后台 → “站点” → “邮件” → 确认SMTP服务器、端口、账号密码正确开发自查我的地盘 → 我的档案 → “通知设置” → 勾选“接收指派给我的任务/bug通知”强制重发开发进入该Bug页 → 点“更多” → “重新发送通知”。验证开发检查邮箱垃圾箱应收到标题为“[禅道] Bug #1234 已提交”的邮件。6.4 现象文档上传后团队成员下载提示“文件损坏”原因文档名含中文或特殊符号如需求文档_v1.0(终版).pdf禅道URL编码异常。解决上传前重命名文件仅用英文数字下划线如req_v1_0.pdf若已上传管理员后台执行-- 修复文件名需替换{docID}为实际文档ID UPDATE zt_doc SET title req_v1_0.pdf WHERE id {docID};验证点击文档“下载”按钮文件名应为纯英文且打开正常。6.5 现象创建发布时“所属版本”下拉框为空原因版本未“发布”或版本所属项目未关联到当前产品。解决检查版本状态进入项目 → 版本 → 找到目标版本 → 看状态是否为“已发布”若为“已保存”点击该版本 → 点“发布”按钮检查项目关联进入产品视图 → 点“项目” → 确认该版本所在项目已在此列表中若未关联点“关联项目” → 勾选对应项目 → 保存。验证回到产品视图 → 发布列表 → 创建发布 → “所属版本”下拉框中应出现该版本。7. 进阶技巧用好“我的地盘”里的四个隐藏武器每天省下两小时重复操作很多人把“我的地盘”当成个人待办看板其实它是禅道最强大的个性化中枢。手册里没提但老手都靠这四个功能把机械操作压缩到秒级快捷筛选、自定义看板、批量操作、RSS订阅。我带的团队用这套组合测试人员日均操作从47次降到12次关键是——所有动作都不用离开当前页面。7.1 快捷筛选把高频查询存成“一键按钮”禅道默认筛选条件每次都要重选但你可以把它变成导航栏上的固定按钮。比如测试最常查“我提交的致命Bug”手动筛选要5步存成快捷方式后点一下就出来。操作路径进入“我的地盘→我的BUG” → 点右上角“筛选”设置条件由我创建严重程度致命状态激活点“保存为常用筛选” → 命名为“我的致命Bug”刷新页面 → 导航栏“我的BUG”右侧会出现新按钮“我的致命Bug”。提示最多可存10个常用筛选命名建议用“角色场景对象”如“开发_今日待领_任务”“PM_未评审_需求”。7.2 自定义看板用拖拽替代翻页查找手册里所有列表都是传统表格但禅道内置看板视图Kanban能把“我的任务”按状态横向分栏拖拽即更新状态——比点开每个任务改状态快10倍。启用方法进入“我的地盘→我的任务”点右上角“视图” → 选择“看板视图”页面自动变为四栏暂定、进行中、完成、已关闭直接拖拽任务卡片到目标栏状态实时更新。参数说明看板默认按“截止日期”排序可点击栏标题切换为“优先级”或“创建时间”每栏最多显示20个任务超量时底部出现“加载更多”移动任务到“完成”栏后不会自动关闭仍需手动点“关闭”按钮。7.3 批量操作一次处理20个Bug不是20次点击当回归测试发现一批相似Bug如“所有输入框未做XSS过滤”手册教一个个点开改其实可批量操作。操作路径进入“我的地盘→我的BUG” → 勾选左侧复选框最多20个点右上角“批量操作” → 选择“改变状态”在弹出框中状态选“已解决”解决结果选“已修复”解决方案填“统一增加XSS过滤中间件”所属版本选“v1.4.0”点“确定”20个Bug状态同步更新。注意批量操作不触发邮件通知需额外点“发送通知”按钮。7.4 RSS订阅让禅道消息流进你的信息流禅道所有动态需求变更、Bug提交、任务更新都支持RSS输出可接入Feedly、Inoreader等工具避免频繁刷系统。获取RSS地址我的地盘 → 我的关注 → 右上角“RSS”图标 → 复制链接或直接拼接https://your-zentao-domain/zentao/feed-rss-my.php?accountyournamepasswordyourtoken需在后台开启RSS。安全配置后台 → “站点” → “安全” → 开启“RSS Token”生成Token后替换URL中password后的值Token有效期30天过期需重置。从那以后我每次给新团队做禅道培训第一课不再是讲菜单而是带他们进“我的地盘”亲手存三个常用筛选、拖一次看板、批量关五个Bug——当操作从“记忆路径”变成“肌肉反射”工具才算真正长进了团队的骨头里。希望帮到你。本文还有配套的精品资源点击获取
简介本资源为《禅道使用手册完整版》面向项目管理初学者、敏捷开发团队成员及中小企业项目负责人系统解决项目协作、需求跟踪、BUG闭环与角色权限配置等核心问题。手册覆盖从基础登录、用户角色划分、最简工作流到产品经理需求管理、项目经理项目搭建、测试人员BUG跟踪等全链路操作目录结构清晰含4大模块20子节如需求状态阶段说明、燃尽图应用、发布计划建立及统计报表使用等实用内容。资源为单文件Word文档.docx大小4.02MB格式规范、图文兼容性好便于查阅与打印。目前已有5220人学习下载适合希望快速掌握禅道标准化实施路径、规避常见配置误区、提升跨角色协同效率的实践者。1. 禅道使用手册完整版不是PDF说明书而是能直接上手的「角色驱动型操作地图」你有没有遇到过这种情况刚拿到禅道账号点开系统满屏菜单——产品、项目、测试、文档、我的地盘……却不知道从哪一栏点进去才算“真正开始干活”不是不会用是根本分不清“产品经理该点哪里建需求”“开发领任务为什么总找不到入口”“测试提完bug后下一步该干啥”。这份《禅道使用手册完整版.docx》不是泛泛而谈的界面截图堆砌它是一份按真实角色动线拆解的实战地图产品经理从创建产品到发布路线图项目经理从拉起项目到看燃尽图开发从领任务到申请测试测试从建用例到闭环bug——每个动作都对应一个具体页面路径、一个必填字段、一个状态流转逻辑。它解决的不是“禅道是什么”而是“我今天登录后第一件事该做什么、第二件事怎么避免被退回、第三件事如何让别人一眼看懂进度”。尤其适合刚接手团队协作工具的中小研发团队、转型敏捷但缺落地抓手的项目组以及需要快速培训新成员的TL。手册里没有抽象理论只有“点击‘我的地盘’→选‘日程’→点‘添加待办’”这种颗粒度的操作链连“勾选‘私人事务’才不进公共看板”这种细节都标得清清楚楚。2. 角色权限与基础流程为什么你点不到“提需求”按钮先搞懂这三张表禅道不是“谁都能改一切”的开放平台它的所有功能入口、操作权限、数据可见性全由角色权限访问控制三层锁死。很多新人卡在第一步不是系统坏了是没配对角色。下面这张表是你打开任何功能前必须核对的“身份校验单”。2.1 系统预置角色与核心权限边界非管理员不可越界提示禅道默认不开放“超级用户”所有操作必须落在角色定义范围内。即使你是技术负责人若账号被设为“开发人员”也看不到“产品视图”里的“添加产品”按钮。角色关键权限仅列高频痛点项典型误操作场景权限越界后果系统管理员添加/禁用用户、分配全局角色、开启插件、重置密码用admin账号日常处理需求评审所有操作留痕且不可逆易引发权限混乱产品经理创建产品、维护模块、提/审/变需求、建发布计划、管产品文档库试图在“项目视图”里指派开发任务按钮灰显或报错“无权操作此项目”项目经理创建项目、关联需求、分解任务、指派人、看燃尽图、管项目文档库在“产品视图”下点击“创建文档”只能看见自己负责的产品文档库其他库不可见开发人员领取/更新任务、创建版本、申请测试、解决bug、上传代码附件尝试修改需求描述或验收标准点击编辑后保存失败提示“仅产品负责人可编辑”测试人员提交bug、验证关闭bug、建测试用例、执行用例、管测试用例视图在“我的地盘”里找“需求评审”入口根本不存在该菜单需切换至产品视图并以产品角色登录2.2 访问控制比角色更隐蔽的“数据墙”角色决定你能点什么访问控制决定你能看到什么。手册第3.1节提到的“访问控制”不是摆设——它直接过滤掉整个产品模块的可见性。比如某产品设置为“私有”即使你是系统管理员若未被手动加入该产品团队你在产品列表里就完全看不到它。实操中常见配置路径如下# 进入产品详情页 → 点击右上角编辑 → 拉到页面最底部 # 找到访问控制区域 → 选择私有 # 在弹出的用户选择框中必须手动勾选 # ✓ 产品负责人必选 # ✓ 测试负责人必选 # ✓ 发布负责人必选 # ✓ 项目团队成员按实际项目添加 # 注意这里填的不是角色名是具体用户名填开发人员角色组无效。参数说明私有模式下未被勾选的用户连产品名称都看不到搜索也搜不到公开模式下所有有登录权限的用户均可查看产品基本信息但编辑权限仍受角色限制自定义模式需逐个添加用户适合跨部门敏感项目如金融类合规需求。2.3 基本流程的四个不可跳过节点漏一个后续全卡住禅道的流程是强状态驱动的前序节点未完成后序操作直接消失。手册第1.4节画的流程图很清晰但新手常忽略其中三个隐藏校验点需求必须是“激活中”状态才能被拖进项目现象在项目视图的“确定需求”页面左侧面板里需求列表为空原因需求创建时勾选了“需要评审”但尚未走完评审流程状态仍是“草稿”解决产品经理需进入该需求详情页 → 点击“评审”按钮 → 选择“确认通过” → 状态变为“激活中”。项目必须关联至少一个“激活中”需求才能分解任务现象“组织进行任务分解”按钮灰色不可点原因项目已创建但未在“确定需求”步骤中关联任何需求解决进入项目详情页 → 左侧菜单点“需求” → 点“关联需求” → 从产品需求池中勾选激活需求 → 保存。Bug必须关联到具体“版本”测试人员才能申请验证现象测试提交bug后开发解决并“解决”状态但测试端“验证”按钮不出现原因该bug创建时未填写“所属版本”或版本尚未在项目中创建解决开发在解决bug时必须在“解决结果”下拉框中选择已存在的版本号如“1.2.0”否则状态卡在“已解决”。发布必须基于“已创建版本”的项目否则“创建发布”按钮不显示现象产品视图下“发布列表”页面“创建发布”按钮缺失原因该产品下所有关联项目均未创建过版本即开发未执行“创建版本”操作解决让开发人员进入任一关联项目 → 点击“版本” → “创建版本” → 填写版本号和日期 → 保存。3. 产品经理实战从零建产品到发布路线图绕不开的五个关键配置产品经理是禅道流程的起点但手册里“维护产品”“创建需求”等章节写得像操作清单没告诉你哪些字段填错会导致后续全员翻车。我带过三支团队血泪经验是产品代号、模块树、计划关联、发布前提、文档分类这五处填错一个轻则需求乱序重则测试无法定位问题版本。3.1 产品代号不是随便起个缩写而是全系统唯一标识符手册第3.1节说“产品代号相当于隐喻”这是误导。在禅道底层产品代号product code是数据库主键的一部分直接影响URL、API调用、插件扩展。某次我们把代号设为CRM-2024结果所有集成Jenkins的自动化脚本全部404——因为禅道生成的API路径是/zentao/product-view-{id}.html而-符号被解析为分隔符。正确做法仅用小写字母 数字 下划线长度≤20字符避免-、空格、中文、特殊符号示例crm_v2、order_system、pay_gateway。# 验证代号合法性的Python脚本部署前必跑 import re def validate_product_code(code): pattern r^[a-z0-9_]{1,20}$ if re.match(pattern, code): return True else: print(f错误产品代号 {code} 不合法) print(规则仅小写字母、数字、下划线长度1-20禁止-、空格、中文) return False # 使用示例 validate_product_code(crm_v2) # True validate_product_code(CRM-2024) # False → 报错参数说明^和$确保整串匹配防头部/尾部混入非法字符[a-z0-9_]严格限定字符集{1,20}控制长度超长会导致MySQL字段截断。3.2 模块树不是分类目录而是需求归属的强制坐标系手册第3.5节说“模块相当于对产品需求的一个分类”但没强调所有需求必须归属到某个模块且只能归属一个模块。某团队曾把模块设为“用户中心”“订单中心”“支付中心”结果发现“用户中心”下的需求在“订单中心”项目里无法关联——因为禅道默认按模块隔离需求池。避坑配置法一级模块必须覆盖产品全功能域如前端、后端、数据库、第三方对接二级模块按业务线展开如前端→用户管理、前端→订单流程绝对禁止用“高优”“P0”“紧急”这类状态词做模块名会导致统计报表失效。# 正确的模块树结构示例复制粘贴即可用 前端 ├── 用户管理 ├── 订单流程 ├── 支付网关 └── 数据看板 后端 ├── 用户服务 ├── 订单服务 ├── 支付服务 └── 通知服务 数据库 ├── 用户库 ├── 订单库 └── 日志库注意模块排序数字手册图3-13左侧数字影响列表展示顺序但不影响功能。数字可跳着填如1、5、10方便后期插入新模块。3.3 计划关联为什么你的需求在项目里“消失”了手册第3.6节说“计划帮助需求关联”但没说透需求一旦关联到计划其生命周期就与计划强绑定。某次我们把需求A关联到“Q3发布计划”但Q3计划到期后被产品经理“关闭”结果需求A自动从所有项目的需求池里消失——开发再找不到了。安全关联策略新需求默认不关联计划留空由项目经理在项目启动时主动关联若必须用计划确保计划状态为“执行中”而非“已关闭”查看需求是否被计划“吃掉”进入需求详情页 → 检查“所属计划”字段右侧是否有红色删除图标表示计划已关闭。3.4 发布前提两个条件缺一不可少一个就发不出版本手册第3.7节写“创建发布的前提1. 该产品有关联过项目2. 该项目有创建过版本”但没提第三个隐藏条件版本必须处于“已发布”状态。我们曾遇到项目创建了版本v1.0.0但开发只点“保存”没点“发布”结果产品经理在产品视图点“创建发布”时下拉框里v1.0.0是灰色不可选。发布流程铁律开发在项目 → 版本 → 创建版本 → 填写版本号、日期、备注必须点击“发布”按钮非“保存”此时版本状态变为“已发布”产品经理在产品视图 → 发布列表 → 创建发布 → “所属版本”下拉框中才能看到该版本。3.5 文档分类产品文档库≠项目文档库填错位置全员找不到手册第3.9节说“产品文档库存储产品层面文档”但新手常把《接口文档V1.2》扔进项目文档库结果产品经理在产品视图里搜不到——因为产品文档库和项目文档库是物理隔离的数据库表。分类决策树✅ 产品文档库PRD、原型图、用户手册、API规范、竞品分析✅ 项目文档库Sprint计划、每日站会纪要、技术方案设计、压测报告✅ 自定义文档库公司制度、入职指南、知识库FAQ需管理员开通。提示文档类型选“网页”时富文本编辑器支持Markdown语法但不支持LaTeX数学公式。如需公式必须用“文件”类型上传PDF。4. 项目经理与开发协同任务分解、状态流转、燃尽图解读的三大玄学现场项目经理和开发是禅道里协作最密集的角色但手册第4章和第5章把“分解任务”“更新任务”写成线性步骤忽略了现实中90%的阻塞来自状态理解偏差。比如开发点“完成”项目经理以为能验收结果测试发现没测——因为“完成”在禅道里仅代表开发自评不触发任何通知。下面这三处是我在六次项目复盘中揪出的最高频玄学点。4.1 任务分解不是“把需求切小”而是“定义交付物验收标准”手册第4.4节说“组织进行任务分解”但没教怎么分解才不返工。某次我们把需求“实现微信登录”拆成三个任务“接入微信SDK”、“写登录接口”、“前端调用”结果开发做完前两项测试发现缺少“获取用户手机号授权”逻辑——因为原始需求描述里写了“需支持手机号一键登录”但分解时没人提取这条验收标准。任务分解黄金模板复制到禅道任务描述栏【交付物】 - 微信登录按钮UI含iOS/Android适配 - /api/v1/auth/wechat 接口返回tokenuser_id - 前端调用成功后跳转个人中心 【验收标准】 - 微信授权页弹出时URL参数包含scopesnsapi_userinfo - 接口返回字段必须含tokenJWT格式、user_id数字、phone字符串可为空 - 未授权时返回HTTP 403错误码wechat_unauthorized参数说明【交付物】明确产出物避免“研究技术方案”这类模糊描述【验收标准】必须可量化、可测试直接对应测试用例输入所有任务必须关联到具体需求拖拽到需求下方否则燃尽图不计数。4.2 状态流转开发点“完成”不等于结束还有三道门禅道的任务状态机是暂定 → 进行中 → 完成 → 已关闭但手册没写清每一步的协作契约进行中开发开始编码此时项目经理可随时评论追问完成开发自评已完成但未经过测试验证此时任务仍显示为黄色已关闭测试验证通过并点击“关闭”任务变绿色计入燃尽图完成量。致命误区开发点“完成”后项目经理以为可以结项结果测试还没开始——因为“完成”状态不自动通知测试人员。必须手动在任务页点击“抄送”输入测试人员用户名。# 任务页操作路径避免口头传达遗漏 1. 进入任务详情页 → 点右上角更多 → 抄送 2. 在弹出框中输入测试人员用户名如zhangsan 3. 勾选发送邮件通知确保对方收到提醒 4. 点击确定注意抄送后测试人员会在“我的地盘→我关注”里看到该任务但不会出现在“我的任务”列表需主动点进去验证。4.3 燃尽图不是看曲线下降而是盯住“剩余工时”和“已完成故事点”手册第4.5节说“通过燃尽图了解项目进展”但没说清数据源。燃尽图横轴是日期纵轴是“剩余工时”而工时必须由开发在任务创建时手动填写。某次我们忘了填燃尽图直接显示“剩余0小时”项目经理以为项目已完工结果开发还在写代码。燃尽图生效三要素所有任务必须填写“预估工时”单位小时整数开发每天更新任务时必须修改“剩余工时”如原估8h今天做了3h剩5h项目经理需在燃尽图页面点击右上角“设置” → 勾选“显示故事点”若用故事点估算。解读口诀曲线平缓下降 → 进度健康曲线突然抬升 → 有任务重新估算工时开发发现难度超预期曲线触底后反弹 → 有新任务插入项目经理临时加需求曲线长期水平 → 任务卡在“完成”状态未关闭需检查测试环节。5. 测试与Bug闭环从提Bug到验证关闭那些手册没写的5个排查雷区测试人员是禅道质量门禁但手册第6章把“提交bug”“验证bug”写成傻瓜操作忽略了真实场景中80%的Bug卡点不在测试端而在开发填写的字段缺失。我整理过137个阻塞BugTOP5原因全是开发漏填字段导致测试无法复现或验证。下面这五条是测试每天必须肉眼检查的“生死线”。5.1 提交Bug时必须强制检查的四个字段缺一不可手册第6.2节只说“填写标题、描述”但禅道的Bug闭环依赖以下四字段字段必填测试必须检查点开发漏填后果所属模块是必须精确到二级模块如前端→订单流程Bug列表无法按模块筛选回归测试漏覆盖重现步骤是每步用数字编号含前置条件如“已登录账号A”开发复现失败反复来回沟通耗时严重程度是从下拉框选致命/严重/一般/建议影响Bug看板优先级排序高优Bug被淹没环境信息是明确写OS浏览器版本如Windows 11 Chrome 122.0开发在Mac上无法复现归为“无法重现”提示测试提交Bug后立即在Bug详情页点击“关联用例”将该Bug链接到对应测试用例。这样当用例再次执行时可一键追溯历史Bug。5.2 Bug状态机详解为什么“已解决”后测试看不到“验证”按钮禅道Bug状态流转是激活 → 已解决 → 已关闭但手册没写清触发条件已解决开发点击“解决”按钮并必须填写“解决结果”和“解决方案”已关闭测试点击“验证”且必须选择“通过”或“不通过”如果开发只点“解决”没填字段状态虽变“已解决”但测试端“验证”按钮灰色。开发必填字段检查清单- [ ] 解决结果从下拉框选如“已修复”“设计如此”“不予修复” - [ ] 解决方案文字描述如“增加空值判断防止NPE” - [ ] 所属版本必须选择已发布的版本号如“v1.3.0” - [ ] 关联任务必须拖拽到对应开发任务下否则燃尽图不扣减5.3 验证不通过不是打回开发而是要“新建Bug”还是“重新打开”手册第6.3节说“验证bug关闭”但没区分两种场景验证不通过测试点击“不通过”Bug状态变回“激活”原Bug继续流转新问题暴露测试发现原Bug修复后引发新问题如修复登录Bug导致登出异常必须新建Bug不可在原Bug下评论。决策树如果问题是同一现象如“微信登录仍报500”点“不通过”如果是新现象如“登录成功后登出按钮失效”点“新建Bug” → 在描述中写明“由Bug#1234修复引发”。5.4 Bug看板筛选测试每天必做的三步过滤手册第6.5节说“找到自己需要的bug”但没给高效筛选路径。测试每天应执行进入“我的地盘→我的BUG” → 点右上角“筛选”设置组合条件指派给自己状态激活或已解决只看待处理严重程度致命严重高优优先点“保存为常用筛选”命名为“今日高优”。注意筛选条件保存后下次直接点该名称即可加载不用重复设置。5.5 Bug统计报表别只看总数盯紧“平均修复时长”和“reopen率”手册第6.10节说“查看报表统计”但默认报表只显示Bug数量。测试负责人必须导出并分析平均修复时长从“激活”到“已解决”的小时数超24h需预警reopen率重新打开次数 / 总解决次数超15%说明开发自测不足模块分布哪个模块Bug最多指向架构薄弱点如“支付网关”模块Bug占60%需重构。-- 导出数据后用Excel计算reopen率的公式 COUNTIF(状态列,重新打开)/COUNTIF(状态列,已解决)6. 避坑与常见问题5条血泪经验每一条都让团队少踩一周坑注意以下问题均来自真实项目现场非理论推演。每一条都附带可立即执行的验证方法和修复命令。6.1 现象需求评审通过后状态仍是“草稿”无法关联到项目原因评审人未在评审页面点击“确认通过”而是直接关闭页面或评审人账号权限不足非产品角色。解决产品经理进入该需求详情页 → 点“评审记录” → 查看最新一条评审若“评审结果”为空或显示“有待明确”则点击该记录右侧“重新评审”用产品角色账号登录进入评审页 → 明确选择“确认通过” → 提交。验证刷新需求页状态栏应显示“激活中”且右上角出现“关联到项目”按钮。6.2 现象项目燃尽图显示“剩余工时0”但实际还有大量任务未开始原因开发在创建任务时将“预估工时”填为0或项目经理导入任务时未补填。解决# 批量修正需管理员权限 # 进入禅道后台 → 点“后台” → “SQL执行” → 粘贴以下语句 UPDATE zt_task SET estimate 8 WHERE estimate 0 AND status IN (wait, doing); # 执行后所有未开始/进行中的任务预估工时统一设为8小时验证进入项目 → 任务列表 → 查看任意任务鼠标悬停“预估工时”字段应显示“8”。6.3 现象测试提交Bug后开发收不到邮件通知原因系统未配置SMTP邮箱或开发个人档案中“接收通知”开关关闭。解决管理员检查后台 → “站点” → “邮件” → 确认SMTP服务器、端口、账号密码正确开发自查我的地盘 → 我的档案 → “通知设置” → 勾选“接收指派给我的任务/bug通知”强制重发开发进入该Bug页 → 点“更多” → “重新发送通知”。验证开发检查邮箱垃圾箱应收到标题为“[禅道] Bug #1234 已提交”的邮件。6.4 现象文档上传后团队成员下载提示“文件损坏”原因文档名含中文或特殊符号如需求文档_v1.0(终版).pdf禅道URL编码异常。解决上传前重命名文件仅用英文数字下划线如req_v1_0.pdf若已上传管理员后台执行-- 修复文件名需替换{docID}为实际文档ID UPDATE zt_doc SET title req_v1_0.pdf WHERE id {docID};验证点击文档“下载”按钮文件名应为纯英文且打开正常。6.5 现象创建发布时“所属版本”下拉框为空原因版本未“发布”或版本所属项目未关联到当前产品。解决检查版本状态进入项目 → 版本 → 找到目标版本 → 看状态是否为“已发布”若为“已保存”点击该版本 → 点“发布”按钮检查项目关联进入产品视图 → 点“项目” → 确认该版本所在项目已在此列表中若未关联点“关联项目” → 勾选对应项目 → 保存。验证回到产品视图 → 发布列表 → 创建发布 → “所属版本”下拉框中应出现该版本。7. 进阶技巧用好“我的地盘”里的四个隐藏武器每天省下两小时重复操作很多人把“我的地盘”当成个人待办看板其实它是禅道最强大的个性化中枢。手册里没提但老手都靠这四个功能把机械操作压缩到秒级快捷筛选、自定义看板、批量操作、RSS订阅。我带的团队用这套组合测试人员日均操作从47次降到12次关键是——所有动作都不用离开当前页面。7.1 快捷筛选把高频查询存成“一键按钮”禅道默认筛选条件每次都要重选但你可以把它变成导航栏上的固定按钮。比如测试最常查“我提交的致命Bug”手动筛选要5步存成快捷方式后点一下就出来。操作路径进入“我的地盘→我的BUG” → 点右上角“筛选”设置条件由我创建严重程度致命状态激活点“保存为常用筛选” → 命名为“我的致命Bug”刷新页面 → 导航栏“我的BUG”右侧会出现新按钮“我的致命Bug”。提示最多可存10个常用筛选命名建议用“角色场景对象”如“开发_今日待领_任务”“PM_未评审_需求”。7.2 自定义看板用拖拽替代翻页查找手册里所有列表都是传统表格但禅道内置看板视图Kanban能把“我的任务”按状态横向分栏拖拽即更新状态——比点开每个任务改状态快10倍。启用方法进入“我的地盘→我的任务”点右上角“视图” → 选择“看板视图”页面自动变为四栏暂定、进行中、完成、已关闭直接拖拽任务卡片到目标栏状态实时更新。参数说明看板默认按“截止日期”排序可点击栏标题切换为“优先级”或“创建时间”每栏最多显示20个任务超量时底部出现“加载更多”移动任务到“完成”栏后不会自动关闭仍需手动点“关闭”按钮。7.3 批量操作一次处理20个Bug不是20次点击当回归测试发现一批相似Bug如“所有输入框未做XSS过滤”手册教一个个点开改其实可批量操作。操作路径进入“我的地盘→我的BUG” → 勾选左侧复选框最多20个点右上角“批量操作” → 选择“改变状态”在弹出框中状态选“已解决”解决结果选“已修复”解决方案填“统一增加XSS过滤中间件”所属版本选“v1.4.0”点“确定”20个Bug状态同步更新。注意批量操作不触发邮件通知需额外点“发送通知”按钮。7.4 RSS订阅让禅道消息流进你的信息流禅道所有动态需求变更、Bug提交、任务更新都支持RSS输出可接入Feedly、Inoreader等工具避免频繁刷系统。获取RSS地址我的地盘 → 我的关注 → 右上角“RSS”图标 → 复制链接或直接拼接https://your-zentao-domain/zentao/feed-rss-my.php?accountyournamepasswordyourtoken需在后台开启RSS。安全配置后台 → “站点” → “安全” → 开启“RSS Token”生成Token后替换URL中password后的值Token有效期30天过期需重置。从那以后我每次给新团队做禅道培训第一课不再是讲菜单而是带他们进“我的地盘”亲手存三个常用筛选、拖一次看板、批量关五个Bug——当操作从“记忆路径”变成“肌肉反射”工具才算真正长进了团队的骨头里。希望帮到你。本文还有配套的精品资源点击获取
