#禅道集成

禅道集成目前仅适用于国内版 HiFox。它可以将禅道产品线或项目中的工作导入到 HiFox Space，并可按需配置后续同步。

禅道仍可以作为团队已有的任务来源；导入后，团队可以在 HiFox 中组织、指派、执行和验收这些工作。

#禅道导入与禅道同步的区别

导入时也可以选择在导入完成后开启后续同步。该选项只有在对应禅道连接和回调都已配置完成时才可用。

#连接前的准备

开始前，请确认：

• 你是 HiFox 组织的 owner 或 admin，能够管理外部应用集成；
• 用于连接的禅道账号可以访问要导入或同步的产品线、项目及其中的工作；
• 已确定接收数据的 HiFox Space，并确认相关成员可在该 Space 中处理任务；
• 禅道地址可从执行导入的环境访问；
• 如果要启用后续同步，禅道管理员可以按照页面提供的指引配置回调。

连接禅道并不会自动给 HiFox 成员增加禅道权限，也不会给禅道账号增加 HiFox Space 的访问权限。两边的权限仍需分别满足。

#支持的禅道版本

HiFox 通过禅道的 RESTful API v1 读取和写回数据，禅道需要是以下版本或更高版本：

依据禅道官方说明：RESTful API v1 在开源版 16.5 加入；企业版 6.5、旗舰版 3.0 与开源版 16.5 同期发布，官方发布说明均注明“兼容开源版 16.5”。云禅道（禅道官方托管版）同样适用以上要求。

版本过低时，连接会提示「当前禅道版本不支持 REST API，请升级到开源版 16.5 及以上」。这不是账号或密码问题，重新输入密码无法解决，请先升级禅道。

#实例地址填访问根地址

禅道地址请填写打开禅道时使用的访问根地址，不要填写某个页面的地址：

找访问根地址的办法：打开禅道登录页，地址栏中 user-login 或 index.php 之前的部分（例如 https://pm.example.com/zentao/）就是访问根地址。

如果填成了页面地址，系统会先去掉页面部分（*.html、index.php 及其后的路径和参数），再逐级向上查找禅道的安装目录，并保存整理后的根地址；只填了域名、而禅道装在 /zentao/ 下时，会自动再试 {根地址}/zentao/。仍然找不到禅道接口、地址返回的是网页时，会提示「这是页面地址，请填写禅道的访问根地址，例如 https://xxx/zentao/」。

#从外部应用集成打开禅道

在组织设置中打开外部应用集成，选择禅道。页面名称或具体入口可能随产品界面调整，以线上显示为准。

在禅道页面中可以：

• 连接或更新禅道实例；
• 检查连接状态并刷新可用的产品线、项目；
• 创建或管理产品线 / 项目与 HiFox Space 的同步链接；
• 打开导入向导和查看导入记录；
• 按页面指引配置禅道回调。

#导入禅道数据

导入向导会依次引导你完成连接信息、范围检查、工作选择、状态和成员映射、导入选项以及确认导入。

#1. 选择来源和目标 Space

在导入向导中填写禅道地址、账号和密码。识别为内网地址时，导入和绑定会使用内网代理电脑。选择的是电脑，不是 Runtime。列表里离线电脑可见但不可选，并提示该电脑已离线。云端实例不使用内网代理。代理不可用或鉴权失败时看页面报错。系统读取连接后，会列出你可访问的禅道产品线和项目。

选择来源后，在目标 Space 选择器中可以使用第一项 +创建新空间 直接创建接收数据的 Space。创建完成后，向导会自动回到当前流程，并将新 Space 设为导入目标。

选择一项来源，并选择接收数据的 HiFox Space。产品线通常会包含与其相关的工作；项目适合只迁移某一交付范围。选择前请确认来源和目标 Space，避免把数据导入错误的团队范围。

#2. 检查导入预览

系统会先验证连接并显示预览，不会在这一步创建 HiFox 数据。

预览会帮助你了解将要导入的工作数量，以及相关项目、迭代、工作类型、进行中和已完成工作等范围。请先确认数量和来源符合预期，再继续下一步。

#3. 选择工作范围

你可以选择导入：

• 进行中的工作；
• 已完成的工作；
• 两者都导入。

如果这是第一次导入，建议先用较小范围验证结果。历史数据量较大时，可先导入正在进行的工作，再根据团队需要补充已完成记录。

#4. 映射状态

禅道中的需求、任务和缺陷可能使用不同的状态字典。导入向导会列出识别到的状态，并提供建议映射。

对每个来源状态，你可以：

• 映射到已有的 HiFox 任务状态；
• 创建一个新的 HiFox 任务状态；
• 调整状态在工作流中的顺序。

创建新状态时，选项会显示为 新建状态（来源平台状态名），括号内保留对应的禅道原状态名称。

状态映射会影响导入后任务在列表、看板和后续同步中的表现。开始导入前，请确认同名状态在两边代表的实际流程一致。

#5. 映射成员

成员映射是可选的。你可以把禅道成员映射到现有的 HiFox 成员，或导入为外部账号；「不导入」是明确跳过。未处理过的成员默认导入为外部账号，已经按邮箱匹配到成员的保持匹配。

这样历史任务不会因为成员没映射而失去处理人，也不会因一次导入把禅道用户批量变成组织成员。需要对方以成员身份继续协作时，再把他们映射为成员或邀请加入。

这一步会按来源平台的能力决定：来源平台不提供「快速获取用户列表」的能力时，向导会跳过这一步；当前凭据没有读取用户列表的权限时也会自动跳过，并在「导入选项」里说明已跳过用户映射，不会再长时间停在「正在获取用户…」。跳过后，成员会按邮箱自动关联，其余保留为外部账号。

#6. 选择导入选项

确认导入前，按页面提供的选项决定本次导入方式。常见选项包括：

• 导入后保持同步：在连接和回调均已就绪时，开启后续同步；
• 导入迭代：当预览中包含可导入的迭代时，决定是否一并导入；
• 为导入的任务添加 Migrated 标签：可选，默认不勾选；需要筛选导入结果时再勾选；
• 覆盖导入：仅用于再次导入同一来源时，用来源数据刷新可更新的已导入内容。

导入会保留可支持的工作上下文，例如任务内容、评论和附件。不同禅道版本、产品配置和字段类型的支持范围可能不同，以向导预览和页面提示为准。

#7. 确认、跟踪进度和检查结果

确认页会汇总本次将导入和跳过的工作、成员、项目、任务类型和状态。确认无误后开始导入。

导入期间，可以在进度页查看完成、跳过和失败的项目，并可根据页面提供的操作取消正在进行的导入。导入完成后：

1. 打开目标 Space 检查任务数量、状态和处理人；
2. 如果勾选了 Migrated 标签，用它筛选本次导入的任务；
3. 查看进度页或导入记录中的失败说明；
4. 修正权限、连接、映射或来源范围后，再按页面提示继续处理。

取消导入不会自动替你判断哪些已创建数据应保留或清理。请先检查实际导入结果，再决定下一步操作。

#配置禅道同步

禅道同步由连接、同步链接和回调三部分组成。仅保存连接信息不足以接收禅道后续变更。同步过来的任务详情里，来源和链接等展示与 Jira 同步任务一致。

#1. 连接禅道实例

在禅道集成页添加连接，填写页面要求的禅道地址和账号信息。地址请填写禅道的访问根地址（见实例地址填访问根地址）；粘贴完整的禅道页面地址也可以——系统会自动去掉页面路径和参数，定位到安装根地址；只填域名时会默认按 https 尝试，失败后再按 http 兜底，禅道装在 /zentao/ 下时还会自动再试 /zentao/。连接成功后会弹出引导：优先配置同步数据，其次导入数据。绑定本身不会自动完成同步或导入。之后可以检查连接状态、更新凭据或刷新可用来源。

建议使用权限与用途匹配的账号。连接账号需要能读取目标产品线或项目；如需将 HiFox 的兼容变更写回禅道，还应具备相应的创建或编辑权限。

#2. 创建同步链接

在禅道集成页创建同步链接，选择：

• 已连接的禅道实例；
• 一个禅道产品线或项目；
• 一个目标 HiFox Space；
• 同步方向。

项目同步 卡片的 新建同步 会用一个向导完成上面的选择，分五步：配置（绑定、来源、目标 Space 和同步方向，默认双向）→ 映射状态 → 映射用户 → 导入选项（可选择建立同步后补导历史数据）→ 确认。

打开某条同步的配置后，详情分为 同步设置（持续同步开关、方向、历史数据补导）、用户映射 和 状态映射 三个页签；改动需要保存才生效，带着未保存的更改离开时会先确认。

可根据团队协作方式选择让禅道变更进入 HiFox，或启用双向同步。双向同步适合同时在两边持续协作的团队；如果禅道仍是唯一的修改入口，先使用禅道到 HiFox 的方向通常更稳妥。

选择错误的产品线、项目或 Space 时，请按页面操作调整或重新建立链接，不要依赖后续导入来修正同步关系。

#3. 按页面指引配置回调

创建连接后，在禅道集成页面打开回调配置。页面会针对当前连接提供需要填写的回调地址和配置步骤。

创建连接或同步时，HiFox 会一并生成该连接固定不变的回调地址和密钥，不必等到打开配置弹窗时才创建。回调状态会记录最近一次收到回调的时间：相应同步收到过回调即视为配置成功，只有从未收到回调时才提示继续配置。

请在禅道设置中严格按页面指引完成配置，并使用一个测试变更确认回调已送达。不要把页面中的回调地址或连接信息复制到公开文档、截图或不受信任的渠道。

连接和回调页面会显示当前状态，例如连接是否正常、回调是否已配置，以及是否正在等待或未能处理回调。出现提示时，先根据页面说明检查连接、权限和回调设置，再继续操作。

如果禅道实例只能从内网访问，可以在连接表单中选择可用的内网代理电脑。内网代理基于电脑执行，不依赖 Runtime。没有可用电脑时，页面可能提供连接电脑入口；连接电脑的流程会在当前表单上方打开，完成后可以回到原表单继续，不需要重新填写已经输入的连接信息。具体选项以当前部署和页面提示为准。

#外部账号

导入或同步遇到禅道上无法对应到组织成员的用户时，HiFox 会自动创建外部账号承接：保留「平台 + 实例 + 姓名」的来源身份，作为任务处理人显示，但不是组织成员、不占名额、不能登录。

外部账号在 人员 → 外部账号 页签统一管理：可以按平台、实例和关联状态筛选搜索，把外部账号关联到组织成员（邮箱唯一匹配或本人验证过绑定会自动关联，手动关联优先）。关联后自动补全该账号名下历史任务的处理人（人工修改过的不覆盖），解除关联后恢复外部身份。详见 Jira 集成中的「外部账号」说明——各平台行为一致。

#状态写回禅道

同步方向为双向时，你在 HiFox 里改的任务、Bug 和需求的状态会写回禅道；方向为「禅道到 HiFox」时不写回。禅道的编辑接口改不了状态，HiFox 会按禅道自己的操作（开始、完成、解决、关闭、激活等）逐步流转，流转使用连接禅道时填写的账号执行。

#写回成哪个禅道状态

HiFox 按这条同步链接上的状态映射反推目标禅道状态。需求、任务、Bug 的状态映射分开配置，也分开判断：

• 状态映射里「HiFox 推送到禅道的状态」一栏为这个 HiFox 状态选的禅道状态，就是写回目标。只在「没有本产品状态推送过去的禅道状态」一栏里指向它的禅道状态，只决定禅道状态同步过来时落到哪里，不作为写回目标。
• 同一个 HiFox 状态对应了多个可作为写回目标的禅道状态时，优先取与 HiFox 状态同名的，其次取最近修改的；仍分不出时按固定规则取其中一个，每次取到的都相同。
• 这一类条目一条状态映射都没有配置时，按禅道默认的状态名匹配，例如 HiFox 的「进行中」对应禅道任务的「进行中」；名字对不上的记为未映射。
• 这一类条目配置了状态映射、但没有一条能作为这个 HiFox 状态的写回目标时，记为未映射：状态不写回，HiFox 里的状态保持你改的值。
• 禅道上的当前状态按映射本来就落到这个 HiFox 状态时（例如映射里禅道的「已暂停」和「进行中」都落到 HiFox 的「进行中」），不会流转。

#支持的流转

• 目标状态和当前状态隔着几步时，按禅道界面允许的顺序逐步流转。例如未开始的任务改成「已关闭」，会先完成再关闭；激活状态的 Bug 改成「已关闭」，会先解决再关闭。
• 每走一步都会回读禅道，确认状态真的变了（关闭和解决还要核对关闭原因或解决方案）。禅道返回成功但状态没变，算作失败。
• 动手前先把整条路径每一步要带的字段都准备好；只要有一步缺字段，一步都不执行。

#自动带上的字段

• 关闭原因 / 解决方案：按目标 HiFox 状态的状态类别决定。类别为「已完成」时，需求以「已完成」关闭，Bug 以「已解决」解决，任务先完成再关闭（禅道里已取消的任务直接关闭，不要求填写工时；已关闭的任务不再流转）；类别为「已取消」时，需求以「已取消」关闭，Bug 以「不予解决」解决，任务先取消再关闭。其他类别按「已完成」处理。
• 解决版本：Bug 以「已解决」解决时，解决版本填「主干」。
• 日期：完成、解决的日期，以及开始或完成时禅道还没有的实际开始日期，取你在 HiFox 改状态的时刻，按禅道实例的时区换算。
• 预计剩余：开始、继续、激活任务需要大于 0 的预计剩余工时，依次取禅道当前的预计剩余、禅道的最初预计、HiFox 的预估（仅当 Space 用时间估算时）、你在同步条填写的值。
• 本次消耗：禅道的总计消耗已经大于 0 时，完成任务不再记新的工时；为 0 时需要你填写，见下文。
• 处理人：流转时带上禅道当前的处理人，不会换人。激活已关闭的条目时，禅道上的处理人已变成 closed，这时带上 HiFox 中的处理人（能对应到禅道账号时），否则用禅道的默认值（完成者、解决者或关闭者）。取消任务时禅道会把处理人改成任务创建者，这是禅道取消操作本身的行为。
• 影响版本：激活 Bug 时带上 Bug 原有的影响版本。
• 流转不带备注，禅道里不会多出 HiFox 写的备注。

#需要补填工时的情况

在任务详情顶部的禅道同步条里填入大于 0 的小时数，点 填写并重试。填写的工时只随这一次重试带给禅道，不会保存到 HiFox 的任何字段。本次消耗工时不会从预估推算，只能由你填写。

#写回失败时

• 禅道拒绝或无法完成流转（例如缺工时、禅道不允许这样流转、多人任务、当前禅道版本不支持）：同步条显示「状态未写回禅道」和具体原因，处理后可以点 重试同步（缺工时时是 填写并重试）。同时，HiFox 里的状态改回禅道上的实际状态（禅道当前状态在映射中能落到某个 HiFox 状态时）；重试成功后，HiFox 会回到你改的状态。
• 网络问题、禅道限流、禅道服务端错误，或禅道实例没有可用的时区：自动稍后重试，HiFox 的状态不回退。
• 未映射的 HiFox 状态、需求的评审类状态：改状态时就判定不写回，同步条显示「部分字段本次未回写禅道：状态」，HiFox 的状态保持你改的值，不回退。
• 短时间内连续改了几次状态，只写回最后一次。

#不支持或有边界的情况

• 需求的草稿、评审中、变更中：只能经禅道的评审、变更流程产生，评审和变更请在禅道中进行。激活一个关闭前处于这些状态的需求时，禅道会恢复成原来的状态，同步条会提示评审、变更只能在禅道中进行。
• Bug 的确认：确认不是一种状态，不会写回。
• 关闭为重复（要在禅道关闭或解决、而 HiFox 状态的类别是「重复」）：需要指明重复的是哪一条，请到禅道中关闭。
• 任务改回未开始：禅道没有这样的流转，不会写回；同步条会提示，HiFox 里的状态退回禅道的实际状态。
• 禅道 18.x（实测 18.12）没有取消任务：需要经过取消的流转（把任务改成已取消，或以已取消的类别关闭任务）在这些版本上不支持；无法识别禅道版本时也按这类版本处理。
• 企业版、旗舰版的自定义工作流状态：禅道当前处于标准流程之外的状态时，无法规划流转；HiFox 状态映射到标准流程之外的状态时，记为未映射。
• 多人任务（串行或并行）：暂停、取消、关闭作用于整个任务，可以写回；开始、继续、完成、激活在禅道里只作用于某一位成员的那一份（激活还会改写团队），需要团队成员在禅道中各自处理，HiFox 不写回并在同步条提示。
• 关闭后的处理人：需求、任务、Bug 关闭后，禅道会把处理人显示为 closed，这不会同步到 HiFox，HiFox 中的处理人保持不变。

#查看同步状态与处理问题

已建立同步关系的任务会在任务详情和禅道集成页面显示相关状态或提示。常见处理方式如下：

• 连接或权限提示：更新连接账号信息，并确认账号仍可访问和编辑目标来源；
• 回调未到达或处理异常：按回调配置页重新检查禅道设置，并用测试变更验证；
• 禅道新建条目的推送：在禅道里新建、还没有进入 HiFox 的条目，推送到达后会自动建成 HiFox 任务，并像导入的任务一样建立同步链接，之后的变更照常同步。默认的窄同步只自动新建任务（Task）；开启完整入站同步后，Bug 和需求（Story / Requirement / Epic）也会自动新建，否则这两类的推送记为「忽略」。同 Space 内的父子任务关系在窄同步和完整入站同步下都会自动挂载，开启完整入站同步后需求父子层级（Epic / Requirement / Story）也会自动挂载；子条目先到达、父条目后到达时，会在父条目同步后自动补齐父子关系。新建到哪个 Space 由该连接上启用中、方向为「禅道到 HiFox」或双向的产品线 / 项目线同步链接决定；同一条目在短时间内连续推送（例如新建后马上指派）只会建一个任务，之前手动导入过的条目也不会重复建单。条目不在任何这类同步链接的范围内，或已在禅道删除、不存在时，推送记为「忽略」，不算失败，也不影响回调和同步的健康状态。已导入的任务被挪到其他执行后对不上的，仍按失败暴露，不会另建新任务；
• 归属的 Space 不明确：同一条目同时落在指向不同 Space 的多条同步链接里（例如两个产品线的同步链接分别绑到不同 Space）时，HiFox 无法判断该建到哪里，这条推送会记为失败，不会随意挑一个 Space 建单。请让该产品线或项目只保留一个 Space 的同步链接，再重新处理这条推送；
• 状态或成员不同步：检查来源状态与 HiFox 状态的映射，以及相关成员是否已正确映射；
• 可重试的同步失败：先按页面提示解决原因，再重新触发同步；
• 写回限制说明：某些禅道对象或字段当前无法写回时，任务详情会明确说明这一限制。这不是通过反复重试就能解决的同步失败，应根据限制调整操作或继续在禅道中处理该项变更。

开启完整入站同步后，不能写回禅道的字段（需求类的描述和处理人，预估，自定义字段）只有禅道上的值变了才会覆盖 HiFox；禅道只改了别的字段（例如标题）时，你在 HiFox 中的修改会保留。升级前就已同步的任务，第一次同步只补上 HiFox 中为空的字段。默认的窄同步（只同步任务的标题、状态和处理人）行为不变。完整规则见Jira、TAPD、禅道概念对照中的「持续同步时，本地修改什么时候会被覆盖」。

状态现在可以写回禅道（见状态写回禅道），因此无论窄同步还是完整入站同步，状态都和标题、优先级一样按写回规则处理：你在 HiFox 改的状态还没写回禅道（正在排队），或写回失败而 HiFox 里仍是你改的那个状态时，不会被禅道的旧状态覆盖；写回失败之后禅道上这一条又有人编辑过，就以禅道为准。禅道拒绝了流转、HiFox 已改回禅道的实际状态后，之后的同步照常跟随禅道。方向为「禅道到 HiFox」的同步不写回状态，禅道推送过来时以禅道的状态为准。

不要根据旧截图、内部错误码或非正式对照表猜测问题原因。以当前页面显示的状态和操作指引为准；仍无法解决时，保留相关任务和时间信息后联系支持。

#权限边界

通常情况下：

• 组织 owner 和 admin 可以连接禅道、更新凭据、配置回调，以及创建、修改或删除同步链接；
• 禅道账号的访问范围决定可读取和写入哪些产品线、项目及工作；
• HiFox Space 的成员和权限决定谁能查看或处理导入后的任务；
• 禅道连接信息仅用于集成功能，页面不会把可直接使用的敏感凭据展示给其他成员。

开始双向同步前，建议先用小范围来源验证状态、成员和写回边界，再扩大到更多产品线或项目。

#常见问题

#导入后还能开启同步吗？

可以。在禅道集成页完成连接、同步链接和回调配置后，再按页面指引为相应来源开启同步。也可以在导入向导中，在配置已就绪时选择「导入后保持同步」。

#禅道里新建的任务、Bug 或需求会自动进入 HiFox 吗？

会，前提是已配置回调，且该条目所属的产品线或项目有启用中、方向为「禅道到 HiFox」或双向的同步链接。默认的窄同步只自动新建任务；开启完整入站同步后，Bug 和需求（Story / Requirement / Epic）也会自动新建。同 Space 内的父子任务关系（以及开启完整入站同步后的需求父子层级）会自动关联，子条目先推送、父条目后推送也会自动补齐。仍有这些边界：不会自动新建专项或迭代；不同步任务类型和专项 / 迭代归属的变更；不支持写回的字段（例如需求的描述和处理人、预估、自定义字段）不会写回禅道，状态按状态写回禅道中的规则写回；只能通过内网代理电脑访问的禅道实例收不到回调，也就不会自动建单，这类实例的新条目仍需通过导入或「补导历史数据」加入。

#提示「当前禅道版本不支持 REST API」怎么办？

说明禅道实例还没有 RESTful API v1，账号和密码并未被校验。请将禅道升级到开源版 16.5、企业版 6.5、旗舰版 3.0 或更高版本后，再重新连接。版本要求见支持的禅道版本。

#提示「这是页面地址」怎么办？

说明填写的地址返回的是禅道或其他站点的网页，而不是禅道接口。请改为禅道的访问根地址，例如 https://pm.example.com/zentao/，填写方法见实例地址填访问根地址。

#为什么看不到产品线或项目？

先检查连接账号是否有访问该来源的权限，再在禅道集成页刷新来源列表。若仍不可见，请确认填写的是正确的禅道地址和账号。

#为什么不能直接重试写回？

页面若说明某个对象或字段目前不支持写回，重试不会改变该限制。请在禅道中完成相应操作，或按页面说明调整同步方式；只有提示明确为可重试的错误时，才应在修正原因后重试。状态写回失败时，同步条会写明原因：要补工时的，填写后点「填写并重试」；其余原因见写回失败时。

#删除同步链接会删除已有任务吗？

删除同步链接会停止后续同步，不会自动删除已导入或已同步到 HiFox 的任务。处理前请先确认团队是否仍需要保留这些历史记录。