#Jira 集成

Jira 集成用于把 Jira 里的项目、issue、epic、状态、评论和附件接入 HiFox。接入后，团队可以继续保留 Jira 中已有的工作流，同时把任务交给 HiFox 里的成员、Agent 或小队处理。

HiFox 里和 Jira 相关的能力主要分成两类：

• Jira 导入：把 Jira 里已有的 issue / epic 批量导入到 HiFox；
• Jira 同步：把一个 Jira 项目和一个 HiFox Space 绑定，让后续变更在两边同步。

如果你只是想把历史数据迁进 HiFox，从导入开始。
如果你还需要继续和 Jira 双向协作，应该配置 Jira 同步。

#Jira 集成能做什么？

Jira 集成可以帮助你：

• 把 Jira issue 导入为 HiFox 任务；
• 把 Jira epic 导入或同步为 HiFox 项目；
• 把 Jira project 绑定到一个 HiFox 空间；
• 保留 Jira issue 的标题、描述、状态、优先级、负责人、标签、评论、附件、关联关系等上下文；
• 将 Jira labels 导入为 HiFox 任务标签；
• 将 Jira issue links 同步为 HiFox 任务关联；
• 根据需要把 HiFox 中的任务更新写回 Jira。

这样，Jira 可以继续作为外部任务来源，HiFox 则成为成员和 Agent 执行、追踪、协作和 review 的地方。

#连接 Jira 前需要准备什么？

连接 Jira 需要一个可以访问目标 Jira 项目的账号，以及对应令牌。

通常需要准备：

• Jira 主机名，例如 acme.atlassian.net；
• 邮箱或用户名；
• Jira Cloud 的 Atlassian API token，或 Jira Server / Data Center 的 Personal Access Token（PAT）；
• 目标 Jira project 的访问权限；
• 如果要自动安装 webhook，账号需要具备对应 Jira 实例和项目的管理权限。

HiFox 会在连接时验证凭据。令牌只提交一次，会加密保存；接口不会把完整令牌返回给前端，只会显示尾号，方便你确认当前使用的是哪一个令牌。

#Jira 导入和 Jira 同步的区别

导入适合迁移历史数据。同步适合保留 Jira 作为外部协作入口，或者让已有 Jira 流程继续运行。

导入时也可以勾选「导入后与 Jira 保持双向同步」。系统会用本次向导里填写的 Jira 账号建立绑定，不必先离开向导单独绑一次。不勾就是一次性导入，之后仍可在「外部应用集成」补开。

#导入 Jira 数据

Jira 导入位于设置里的导入流程。导入向导会引导你完成配置、检查、选择范围、映射状态、映射用户、选择导入选项和确认导入。

#1. 选择导入方式

Jira 有两种导入：

1. API 导入：用 Jira 主机名、账号和 token 读取 issue / epic。适合完整迁移，也是导入后继续同步的路径。
2. 文件导入：在设置的「导入与导出」里选 Jira，上传 CSV。向导会引导你映射列/字段，再导入到指定空间。

完整历史、评论、附件和持续同步仍建议用 API 导入。文件导入适合已经从 Jira 导出过 CSV、或暂时不便走 API 的情况。

请从 Jira 用 Issues → Export → CSV (all fields) 导出，并选择全部字段。映射步骤会要求把一列映射为标题；未映射字段可能导入为自定义字段。具体映射项以向导为准。

其它来源（Linear、TAPD、Asana 等）也走同一个「导入与导出」入口。TAPD 文件导入用的是官方 Excel（.xls / .xlsx），字段映射以各来源向导为准。TAPD 的 API 导入和双向同步见 TAPD 集成。

#2. 配置 Jira 连接信息

你需要填写：

• Jira 主机名；
• 邮箱或用户名；
• API token 或 PAT；
• Jira project key；
• 可选 JQL；
• 目标 HiFox Space。

私有化 / Server / Data Center 才会出现 使用内网代理。云端 Jira 不显示这一项。默认是 不使用内网代理（由服务器直连）。选了某台电脑后，导入和双向同步都走这台电脑。代理不可用或鉴权失败时看页面报错，不要凭记忆对照错误码。

JQL 用于限制导入范围。例如你可以只导入某个组件、某个时间之后创建的 issue，或某一类 issue。

#3. 检查导入内容

HiFox 会先读取 Jira 数据并展示预览。

预览中通常会看到：

• 将导入多少 issue；
• 将导入多少 epic；
• 发现多少状态、标签、用户、任务类型和自定义字段；
• open issue 与 closed / done issue 的数量；
• 目标 Space 中是否已经存在同来源的 Jira issue。

这一步只检查，不会创建任务。

#4. 选择导入 open 还是 closed issue

你可以选择导入：

• open issue；
• closed / done issue；
• 两者都导入。

默认适合导入完整历史。如果你只想先迁移仍在进行中的工作，可以只导入 open issue。

#5. 映射状态

Jira 状态会映射到 HiFox 的 任务状态。

HiFox 会根据 Jira 状态名称和状态分类给出默认映射。你可以：

• 使用已有 HiFox 状态；
• 为某个 Jira 状态创建新的 HiFox 状态；
• 调整状态所属分类和顺序。

建议在导入前认真检查状态映射。状态映射会影响导入后任务在列表、看板、视图和 Agent 执行流程里的位置。

#6. 映射用户

Jira 导入会扫描 assignee、reporter 以及支持的用户类型自定义字段。

你可以选择：

• 不导入用户；
• 将 Jira 用户映射到已有 HiFox 成员；
• 用 Jira 用户邮箱邀请新成员；
• 跳过某些 Jira 用户，让相关任务保持未分配。

默认更谨慎：不自动导入用户。这样可以避免把历史 Jira 用户批量变成组织成员。需要保留负责人和评论作者信息时，再显式映射用户。

如果你选择用邮箱创建用户，HiFox 会创建或复用对应用户，并发送组织邀请。受邀人接受后，会加入导入目标 Space。

#7. 选择导入选项

导入前可以选择一些额外选项：

• 导入后与 Jira 保持双向同步：可直接勾选，不再要求预先绑定。勾选后，系统会用本次向导里的 Jira 账号建立绑定。同步是双向的：Jira 改动会进来，HiFox 里的改动也会写回 Jira。只同步导入之后的新变动，不回放更早的历史。以后可在「外部应用集成」改成单向、暂停或解除。第 1 步如果选了内网代理电脑，同步绑定也走这台电脑，不会改成云端直连。想用另一套长期账号时，用向导里的「用其他账号」（Jira 地址保持本次导入的同一实例）；
• 导入 Sprint：导入 Jira Sprint 信息；
• 切换到 Jira Sprint 模式：当目标 Space 仍使用自动迭代模式时，可以切换为手动 Jira 模式；
• 添加 Migrated 标签：默认给导入的任务添加 Migrated 标签；
• 覆盖导入：重新导入时，用 Jira 中的数据覆盖已导入任务的可变字段。

如果不确定，建议先保留默认选项。Migrated 标签对后续筛选、检查和回滚都很有帮助。

#8. 查看导入进度

导入开始后，HiFox 会显示导入任务的进度，包括总数、已完成数量、跳过数量和失败项。

导入过程中可以取消。取消后，已经创建的任务会保留；如果需要清理，可以使用导入历史中的回滚能力。

导入完成后，可以进入目标 Space 查看导入任务。通常可以用 Migrated 标签筛选导入结果。

#导入会创建哪些 HiFox 数据？

导入 Jira issue 时，HiFox 会尽量保留 Jira 上下文。

常见结果包括：

• Jira issue → HiFox 任务；
• Jira epic → HiFox 项目；
• Jira issue type → HiFox 任务类型；
• Jira status → HiFox 任务状态 / 工作流状态；
• Jira labels → 目标 Space 的标签；
• Jira watchers → 任务关注者；
• Jira comments → 任务评论；
• Jira attachments → 任务附件；
• Jira issue links → 任务关联；
• Jira sub-task / parent 关系 → HiFox 子任务关系；
• Jira Sprint → HiFox 迭代相关数据。

导入的标签归属于目标 Space，避免影响其他 Space 的标签选择器。如果组织中已经存在同名标签，导入会复用该组织标签，不再创建同名的 Space 标签。

不是每个 Jira 字段都会一比一同步。Jira 中某些高度自定义或只在特定项目配置中存在的字段，可能会作为自定义字段导入，或在当前版本中被跳过。

#回滚导入

导入历史会记录每次 Jira 导入任务。

如果导入后发现范围选错、映射不合适，或目标 Space 不正确，可以在允许时间窗口内回滚导入。回滚会删除这次导入创建的任务和项目，并标记导入记录为已回滚。

注意：回滚只清理 HiFox 中这次导入产生的数据，不会删除 Jira 里的 issue 或 epic。

#配置 Jira 同步

Jira 同步位于外部应用集成中的 Jira 设置。

配置一般分两步：

1. 绑定 Jira 实例；
2. 创建 Jira project 与 HiFox Space 的同步链接。

#绑定 Jira 实例

在 Jira 集成页点击设置或管理，填写：

• 主机名；
• 邮箱或用户名；
• API token 或 PAT。

绑定成功后，HiFox 会保存这个组织级 Jira 连接，并缓存 Jira project 列表。之后可以手动刷新 Jira 项目元数据。

组织 owner / admin 可以绑定、更新凭据、刷新项目列表或断开 Jira。

#创建 Jira 同步链接

一个同步链接会把一个 Jira project 绑定到一个 HiFox Space。

创建链接时需要选择：

• Jira project；
• HiFox Space；
• 同步方向；
• issue 状态和项目状态映射。

一个 Jira project 只能主动链接到一个 Space；但多个 Jira project 可以链接到同一个 Space。

#手动恢复 Webhook

如果自动安装失败，已停用的链接会显示“配置 Webhook”。请将其中的一次性配置包交给 Jira 管理员：它包含回调 URL、产品品牌请求头 X-HiFox-Webhook-Secret、查询参数备选、所需事件和项目 JQL。关闭前请复制配置包；重新生成会立即使旧令牌失效。

管理员保存 Webhook 后，请修改已绑定 Jira 项目中的一个测试 issue。只有 HiFox 收到并成功处理该签名事件后，才会启用链接。如果状态显示“已收到回调，但处理失败”，请使用显示的时间和请求 ID 联系支持；这表示入站处理异常，而不是 Jira 权限问题。

Jira project 和 Space 在链接创建后不能直接改成另一个目标。如果选错，需要删除链接后重新创建。

#同步方向

Jira 同步支持两种方向：

如果团队仍把 Jira 作为主要入口，可以先使用 Jira → HiFox。
如果团队希望在 HiFox 中创建、拆分、分配任务，同时保持 Jira 更新，可以使用双向同步。

#会同步哪些字段？

当前 Jira 同步重点覆盖任务、项目和协作中最常用的字段。

常见同步内容包括：

• 标题 / summary；
• 描述；
• 优先级；
• 状态；
• 负责人；
• 标签；
• 截止日期；
• 预估；
• Jira epic 与 HiFox 项目；
• 评论；
• 附件；
• issue link / 任务关联。

状态同步依赖状态映射。如果某个 HiFox 状态没有映射到 Jira 状态，状态更新可能不会写回 Jira，并会在任务或项目的 Jira 同步状态中显示警告。

预估会根据 Space 的估算方式和 Jira 项目配置写入。Story Points 会写入 Jira 的 Story Points 字段；时间估算会写入 Jira original estimate，并使用 Jira 实例的工作日历换算工作日和小时。

#个人 Jira 账号

组织级 Jira 绑定使用的是共享集成凭据，适合执行同步、创建 issue、更新字段和安装 webhook。

如果你希望从 HiFox 写到 Jira 的评论尽量以你自己的 Jira 身份发布，可以绑定个人 Jira 账号。

绑定个人 Jira 账号后：

• 你在 HiFox 中发布到 Jira 的评论，会优先使用你的个人 Jira 凭据；
• assignee、creator / reporter、project lead 等 Jira 身份字段可以更准确映射；
• 如果个人凭据失效，评论会回退为组织级集成账号发布。

个人 Jira 账号只影响你的身份映射和评论身份，不会断开或修改组织级 Jira 同步。

#在任务中查看 Jira 同步状态

已经和 Jira 同步的任务，会在任务详情里显示 Jira 同步信息。

常见状态包括：

• 已同步；
• 待同步；
• 同步警告；
• 同步错误；
• 远端已删除；
• 存在冲突。

如果同步失败，可以查看错误说明。部分失败可以重试，例如 Jira 必填字段、权限、状态映射或凭据问题修复后，再重新触发同步。

任务详情里也可以打开对应 Jira issue。需要停止单个任务和 Jira 的关系时，管理员可以断开该任务的 Jira 同步链接；断开不会删除 HiFox 任务或 Jira issue。

#断开 Jira 或删除同步链接

断开 Jira 实例会停用这个组织的 Jira 绑定，并停用相关 Jira project 与 Space 的同步链接。后续同步会停止。

删除某个同步链接，只会停止这个 Jira project 与 Space 之间的后续同步。

这两种操作都不会删除：

• Jira issue；
• Jira epic；
• HiFox 任务；
• HiFox 项目；
• 已经导入或同步过的评论和附件。

如果只是 Jira token 过期，建议更新凭据，而不是断开整个 Jira 集成。

#权限和安全

通常规则是：

• 组织 owner / admin 可以绑定 Jira、更新凭据、创建或删除同步链接；
• 普通成员可以查看已有 Jira 同步状态；
• 成员可以绑定自己的个人 Jira 账号；
• Jira token 会加密保存，完整 token 不会在接口中返回；
• Jira 导入时使用的临时凭据只用于本次导入流程，任务完成后不会作为普通可读配置展示。

建议为 Jira 集成准备权限合适的服务账号或管理员账号，并定期轮换 token。

#最佳实践

#先小范围导入

第一次迁移时，不建议直接导入整个 Jira 历史。可以先用 JQL 限制一个项目、一个组件或最近一批 issue，确认状态、用户、标签和任务类型映射符合预期后，再扩大范围。

#先检查状态映射

状态映射会影响看板、视图和同步写回。导入或创建同步链接前，建议先确认 Jira 状态和 HiFox 状态的含义一致。

#用 Migrated 标签验收导入结果

导入时保留 Migrated 标签，可以在任务列表里快速筛选这批任务，检查数量、状态、负责人、评论和附件是否符合预期。

#不确定时先用 Jira → HiFox

如果团队还没有决定是否在 HiFox 中创建 Jira issue，可以先使用 Jira → HiFox。等团队确认 HiFox 中的任务流程稳定后，再切换到双向同步。

#让 Agent 读取同步后的任务上下文

Jira 导入或同步后的任务会保留描述、评论、附件、标签和关联任务。把这些任务委派给 Agent 前，建议补充清楚目标和验收标准，让 Agent 不只是读取历史上下文，还知道下一步要做什么。

#常见问题

#Jira Cloud 和 Jira Server / Data Center 都支持吗？

支持。Jira Cloud 通常使用邮箱和 Atlassian API token；Jira Server / Data Center 通常使用用户名和 PAT。

#导入会删除 Jira 里的 issue 吗？

不会。导入只在 HiFox 中创建任务、项目和相关数据，不会删除 Jira 数据。

#同步链接删除后，已有任务还在吗？

还在。删除同步链接只停止后续同步，不删除已经存在的 HiFox 任务或 Jira issue。

#为什么绑定成功后看不到 Jira project？

可能是账号没有访问项目的权限，或者项目元数据还没有刷新。可以在 Jira 集成页刷新 Jira 项目列表，并确认凭据账号能在 Jira 中浏览对应项目。

#为什么状态没有同步回 Jira？

通常是状态映射缺失、Jira 工作流不允许直接切换到目标状态，或 Jira 项目有必填字段 / workflow rule 拦截。先检查同步状态里的错误说明，再调整状态映射或 Jira 工作流配置。

#评论一定会同步到 Jira 吗？

不是。只有通过支持“发布到 Jira”的评论入口发布的顶层成员评论，才会写回 Jira。普通本地评论、回复和 Agent 评论会保留在 HiFox 任务中。

#附件会重复上传吗？

HiFox 会记录 Jira 附件的远端 ID，避免已从 Jira 拉取或已经上传过的附件再次上传。

#我应该用导入还是同步？

如果目标是一次性迁移历史数据，用导入。
如果目标是让 Jira 和 HiFox 在之后继续保持更新，用同步。
如果既要迁移历史，又要保持后续更新，在导入向导里直接勾选「导入后与 Jira 保持双向同步」即可；系统会用本次填写的账号建立绑定。

#Jira 同步故障排查

当任务或项目顶部出现 Jira 同步提示时，先看分类标题后面的原文（例如 no transition to status "进行中"），再按下表做对应操作。修复后，在任务或项目详情中重试同步。

#根据横幅原文选择操作

#Jira 权限或认证失败

这通常表示当前组织级 Jira 凭据、个人 Jira 凭据或账号权限不可用。

可以按顺序检查：

1. 在 Jira 集成页更新组织级 Jira token；
2. 确认该账号可以在 Jira 中浏览目标项目，并有创建或编辑 issue 的权限；
3. 如果失败发生在评论同步，确认评论发布者是否需要绑定或更新个人 Jira 账号；
4. 更新凭据后重试同步。

#未找到 Jira 条目

这通常表示 HiFox 中的同步任务仍在，但对应的 Jira issue 已被删除、移动、归档，或当前 Jira 账号已经无法访问。

可以按顺序检查：

1. 从任务详情打开 Jira issue，确认 Jira 中是否仍能访问；
2. 如果 issue 被误删或归档，先在 Jira 中恢复；
3. 如果只是权限变化，恢复集成账号对该项目或 issue 的访问权限；
4. 如果不再需要同步，断开这个任务和 Jira issue 的同步链接。

#Jira Epic 类型不可用

这通常发生在同步项目或 epic 时：目标 Jira 项目没有可用的 Epic issue type，或项目配置不允许创建 Epic。

可以按顺序检查：

1. 在 Jira 项目设置中确认 Epic 类型已启用；
2. 确认集成账号有创建 Epic 的权限；
3. 如果当前 Jira 项目不使用 Epic，改用单向同步或避免把 HiFox 项目写回为 Jira Epic；
4. 调整后重新触发同步。

#Jira 必填字段拦截了同步

这通常表示 Jira 项目的创建或编辑界面中有 HiFox 当前不会写入的必填字段，例如组件、版本、自定义字段或安全级别。

可以按顺序检查：

1. 查看 Jira 返回的具体字段错误；
2. 在 Jira 项目配置中移除这类字段的必填要求，或给字段设置默认值；
3. 确认该字段出现在 Jira 的创建或编辑界面中，且集成账号有权限写入；
4. 修复 Jira 配置后重试同步。

#Jira 工作流或字段约束拦截了同步

这是最常见的一类提示。分类标题相同，但后面的原文决定你该做什么。

#原文是 no transition to status "xx"

Jira 有这个状态，但当前 issue 不能从现在的状态一步转到它。常见原因：自定义工作流不能任意跳；多个 HiFox「进行中」类状态被自动映射到同一个 Jira 状态（例如把「开发中」写成「进行中」）。

按这个顺序处理：

1. 从任务详情打开 Jira issue，看当前状态和页面上实际能点的流转；
2. 打开 Space 的 Jira 同步链接，检查状态映射：HiFox「开发中」应映射到 Jira「开发中」，不要把所有进行中都指到「进行中」；
3. 确认目标 Jira 状态能从当前状态直接到达。如果必须经过中间状态，先在 Jira 里走完，或改映射；
4. 调整后重试同步。

#原文含 not mapped to a Jira issue status

这个 HiFox 状态没有映射。打开同步链接的状态映射，给它指定 Jira 状态，或明确设为不同步，然后重试。

#原文含 field cannot be set 或 unknown field

当前 Jira 界面或字段上下文不允许写这个字段。检查编辑界面、字段上下文和 issue type，修好后重试。

如果原文对不上上面三类，再按顺序检查：

1. 状态映射是否指向了正确的 Jira 状态；
2. Jira 工作流的 validator、condition、post function 是否限制了字段、角色或流转路径；
3. 调整 Jira 配置或状态映射后重试同步。

#Jira webhook 或项目范围需检查

这通常表示 Jira 到 HiFox 的后续更新没有进入同步链路，常见原因是 webhook JQL、项目范围或 Jira 项目绑定不匹配。

可以按顺序检查：

1. 确认 Jira project 已经和正确的 HiFox Space 建立同步链接；
2. 检查 Jira webhook 的 JQL 是否覆盖目标项目和 issue 范围；
3. 确认导入时使用的 JQL 只影响导入范围，不会自动限制后续同步 webhook；
4. 如果项目范围变更过，刷新 Jira 项目元数据或重新创建同步链接。

#正在显示按分类的默认状态映射

这通常表示 HiFox 暂时无法读取 Jira 的实时状态列表，只能根据 Jira 状态分类显示默认映射。

可以按顺序检查：

1. 更新或重新绑定 Jira 凭据；
2. 确认集成账号可以读取 Jira 项目状态和工作流信息；
3. 刷新 Jira 项目元数据；
4. 重新打开状态映射配置，选择准确的 Jira 状态。

#评论使用了集成账号

这通常表示当前成员没有可用的个人 Jira 账号，或个人 Jira 凭据失效。HiFox 会回退为组织级集成账号发布 Jira 评论。

可以按顺序检查：

1. 成员在个人设置中绑定或更新自己的 Jira 账号；
2. 确认个人 Jira 账号可以浏览并评论目标 issue；
3. 如果团队接受统一身份发布评论，也可以继续使用集成账号；
4. 重新发布需要同步到 Jira 的评论。

#Jira 附件同步需要关注

这通常表示附件上传或读取失败，常见原因包括附件过大、Jira 附件权限不足、Jira 项目禁用了附件，或网络请求失败。

可以按顺序检查：

1. 确认 Jira 项目允许上传附件；
2. 确认集成账号有读取和上传附件的权限；
3. 检查附件大小是否超过 Jira 或组织配置限制；
4. 删除或压缩异常附件后重试同步。

如果提示不是以上类型，而是泛化的“Jira 写入失败”，通常需要查看同步提示里的 Jira 原始错误，再按字段、权限、工作流或附件方向继续排查。