Jira、TAPD、禅道概念对照

准备导入或同步前，先确认外部平台中的对象会落到 HiFox 的哪一层。名称相似不代表含义相同：例如 Jira Epic 会成为专项，TAPD 中名为“史诗故事”的需求类别仍然是任务类型，禅道 22.x 的业务需求也会成为父任务而不是专项。

下表以当前 API 导入与同步实现为准。CSV / Excel 文件导入按文件向导中的字段映射执行，不在本页范围内。连接步骤、凭证要求和故障排查请直接查看各平台的详细指南。

先理解 HiFox 的五个概念

HiFox 概念含义与其他概念的关系
Space（空间）团队持续协作和权限管理的范围，承载任务、任务类型、迭代、成员、视图和自动化。每个任务只属于一个 Space。导入或同步时，需要把外部来源范围绑定到一个目标 Space。
专项围绕目标或交付组织一组任务，并跟踪负责人、状态、优先级和进度。任务可以不属于专项；专项可以关联多个 Space。专项不是时间周期。
迭代Space 内的一段工作周期，用来安排本周期的任务范围和进度。迭代只属于一个 Space；任务可以同时属于一个专项和一个迭代。
任务实际执行、讨论和验收工作的基本单位。每个任务都有所属 Space 和任务类型，也可以关联专项、迭代、父任务和其他任务。
任务类型说明任务是什么工作对象，例如需求、缺陷、研发任务或研究。任务类型归属于 Space，并决定任务可用的工作流与自定义字段。

进一步了解这些概念：Space、专项、迭代、任务和任务类型。

Jira 对照

Jira 对象或信息HiFox 对应当前映射与限制
Jira project目标 Space 的来源范围和同步边界Jira project 本身不会创建同名专项。一个 Jira project 的有效同步链接对应一个 Space；多个 Jira project 可以接入同一个 Space。
Epic专项Epic 的标题、描述、状态、优先级和负责人会落到专项；Epic 的标签与组件成为专项标签；截止日期、报告人、版本、自定义字段等专项没有对应位置的信息保存在专项元数据中。属于该 Epic 的 issue 会关联到对应专项。Epic 本身不再创建一条任务；Epic 的评论与附件不会导入，导入结果会给出告警。
Sprint迭代开启导入 Sprint 后，Sprint 会在目标 Space 中成为迭代，任务会关联到对应迭代；持续同步时，只有 Jira 这次变更确实调整了 Sprint，任务才会跟着换迭代（空间中没有同名迭代时会自动新建）；Jira 侧的其它改动不会覆盖你在本地调整过的迭代，Jira 侧清空 Sprint 也不会清空本地迭代。未开启时 Sprint 名称仍作为文本自定义字段保留。
非 Epic issue任务Story、Bug、Task、Sub-task 等非 Epic issue 都会成为任务。
Issue Key 中的数字后缀（如 HF-47）任务编号只有在导入开始时目标 Space 为空，系统才会为本次导入开启编号复用，并把可解析的数字后缀用于 HiFox 编号（如 HF-47 → <SPACE>-47）。这个决定会随导入任务持久化，断点续跑时继续沿用，不会因 Space 已写入部分任务而改变。目标 Space 非空、编号复用未开启或 Issue Key 无法解析时，由 HiFox 在该 Space 中顺序分配编号。
Issue Type任务类型每种非 Epic Issue Type 会匹配或创建目标 Space 中的任务类型；不会再折叠成标签。任务类型不会写回 Jira：持续同步时只有 Jira 这次变更确实改了 Issue Type，本地任务类型才会跟着变。
Parent / Sub-task父子任务非 Epic 的父子关系会成为 HiFox 的父任务和子任务关系；Issue 与 Epic 的关系改由“任务属于专项”表达。
Summary、Description、Status、Priority、Assignee、日期和 Estimate任务原生字段标题、描述、状态、优先级、处理人、开始/截止日期和预估会落到对应原生字段，创建时间、更新时间和状态变更时间取 Jira 原值。优先级不在映射表内的按“无”导入，原名保存在「原始优先级」（导入完成页会列出，持续同步时不因此显示告警）。预估按 Space 的预估口径二选一，另一种保留为「原始预估」或 Story Points 数字字段；已用时间、剩余预估、工作日志、解决结果、解决日期、环境、安全级别、影响的版本和子任务列表都作为自定义字段保留。持续同步时，Jira 侧没有填写开始日期不会清空本地的开始日期；Jira 推送没有改动描述时（例如只调整了排序）不会重写本地描述。截止日期写回 Jira 时按你选的那一天，不受时区影响。描述写回 Jira Cloud 时保留标题、粗体、列表、代码块、链接和表格。状态写回仍受状态映射、Jira 工作流和必填字段约束。
Labels、Components、Watchers标签和关注者Labels 会成为同名任务标签；Components 会成为「Component: 名称」标签，以便与标签区分且不会被写回成 Jira 标签。可匹配成员的 Watchers 会成为任务关注者，无法匹配的姓名保存在「关注者（全部）」并给出告警。
Comments、Attachments、Issue Links评论、附件和任务关联评论保留原作者与时间，受可见性限制的评论会在正文首行标注可见范围。附件保留 Jira 上的上传者（是成员时）与上传时间，下载或上传失败的附件会在导入结果中列出。Issue Links 在两端都导入时成为任务关联并保留 Jira 的关联类型名，否则以带链接的文本保存在「链接的问题」。持续同步只覆盖支持的变更，不等同于完整复制 Jira 的所有协作行为。
Jira 自定义字段及其他字段HiFox 自定义字段所有自定义字段都会导入：文本、数字、日期、单选、多选、布尔、链接和单个成员按对应类型保存；级联选择、分组、项目、版本、团队、标签型数组等没有对应类型的以文本保存。多人选择器只能存一人，全部姓名保存在「字段名（全部）」。组织内已有同名字段时，类型相同（单选、多选还要求 Jira 的选项在已有字段中都能找到）就复用，否则新建一个同名字段，类型和选项取自 Jira；因此设置中可能出现同名字段，导入完成页会在“以下字段与已有同名字段不兼容，已新建同名字段”下单独列出这些新建的字段，不计为失败。Reporter、Fix Version、Votes 等没有原生位置的信息也作为自定义字段保存。持续同步时，Jira 自定义字段的空值不会清空本地已有的值，Jira 这次变更没有改到的自定义字段也不会覆盖你在本地的修改；Reporter、解决结果、解决日期等系统信息跟随 Jira，Jira 侧清空时本地也随之清空，但 Jira 推送中没有携带的字段（如 Jira Cloud 推送不含工作日志）保持原值；同步选用字段的规则与导入相同，选定后始终写入同一个字段，Jira 侧新增的选项会追加到该字段。
无法原样保存的值导入告警 / 同步状态多人溢出、成员未匹配、类型不支持、解析失败、附件跳过等降级都会在导入完成页“部分字段或关系未能导入”的列表中逐条列出；持续同步中出现时显示在任务的同步状态提示里。

连接 Jira、选择范围、配置状态和处理同步问题，请查看 Jira 集成。

TAPD 对照

TAPD 对象或信息HiFox 对应当前映射与限制
TAPD 项目（workspace）目标 Space 的来源范围和同步边界TAPD 的项目用于确定读取和同步范围，不会创建同名专项。
Story（需求）任务当前 API 导入只读取 Story 和 Bug 两类工作项。Story 会成为任务，TAPD 自身的“任务”等其他实体不会作为独立任务导入。优先级优先按 TAPD 的优先级名称映射，无法识别的按中等导入并保留「优先级（原始值）」。
Story 的需求类别 / Workitem Type任务类型需求、史诗故事、特性、调研和自定义需求类别会成为对应任务类型。即使类别名是“史诗故事”，它仍然是任务类型，不会创建专项。
Bug（缺陷）任务Bug 会成为“缺陷”任务类型的任务，并使用 Bug 自己的状态字典。严重程度成为「严重程度」下拉自定义字段（致命 / 严重 / 一般 / 提示 / 建议）；Bug 关联的需求成为与对应需求任务的关联，需求未导入时保留为「关联需求 ID」。
Iteration（迭代）迭代开启导入迭代后，TAPD Iteration 只会在目标 Space 中创建或匹配 HiFox 迭代，并保留名称、日期、状态、描述、创建人和创建时间；不会创建专项，也不会作为任务导入。持续同步时，Story / Bug 换到的迭代如果在目标 Space 中已有同名迭代，任务会随之调整；同步不会新建迭代，也不会因为 TAPD 侧清空迭代而清空本地迭代。
Story Parent父子任务Story 的父子层级会成为任务父子关系。TAPD Bug 没有对应的父子层级。
Story / Bug Status任务状态Story 与 Bug 使用两套独立状态字典；即使状态 key 相同，也会按对象类型分别映射。
标题、描述、优先级、人员、日期和工时任务原生字段标题、描述、优先级、处理人、创建人、预计开始/截止日期和预估工时会按 Story / Bug 可提供的字段落入原生字段，导入和持续同步都会更新（持续同步时 TAPD 未填写开始日期不会清空本地值，也不会改动已有任务的任务类型；开始日期不会写回 TAPD，只有 TAPD 侧的开始日期变了才覆盖本地）；任务的创建、更新时间取 TAPD 的创建、修改时间。
标签和 Story 分类树标签TAPD 标签会成为任务标签；Story 的分类会按完整路径落到目标 Space 的“分类”标签组中。
自定义字段及没有原生位置的系统字段HiFox 自定义字段已配置且有值的自定义字段会按文本、数字、日期、单选、多选、布尔、链接或成员类型导入，字典中没有或类型不支持的按文本保存（字段名为 TAPD 原始键名）。所有没有原生位置的系统字段都会作为自定义字段保存：开发人员、抄送人、版本、模块、业务价值、规模、完成工时、剩余工时、来源、完成时间、进度、超出工时、发布计划、层级、特性、测试重点、层级路径、子需求 ID、祖先需求 ID，以及 Bug 的发现 / 验证 / 合入 / 关闭版本、缺陷根源、四类基线、解决 / 关闭时间、解决期限、接受处理时间、验证时间、预计解决时间、缺陷类型、解决方法、缺陷原因、引入 / 发现阶段、软件平台、操作系统、浏览器、重现规律、测试方式 / 阶段 / 类型、重现步骤、回归次数、测试人员、参与人、最后修改人、修复人、审核人、验证人、关闭人、分配 / 拒绝 / 重新打开 / 审核 / 挂起时间、里程碑，以及需求的技术风险。上面没有列出的其它返回字段（包括 TAPD 以后新增的字段）也会保存为文本字段，字段名取 TAPD 字段配置里的中文名，没有中文名时用原始键名；应用 ID、模板 ID、创建渠道、流程、保密相关等内部字段不会导入。多人的人员字段只保存第一个能匹配的成员，全部姓名保存在「字段名（全部）」；无法按类型解析的值保存在「字段名（原始值）」；组织内已有同名字段时，类型相同（单选、多选还要求 TAPD 的选项在已有字段中都能找到）就复用，否则新建一个同名字段，类型和选项取自 TAPD；因此设置中可能出现同名字段，导入完成页会在“以下字段与已有同名字段不兼容，已新建同名字段”下单独列出这些新建的字段，不计为失败。持续同步时，TAPD 没有返回值不会清空本地已有的值；TAPD 明确置空的系统字段（如取消归档、取消保密、剩余工时或进度归零、清除完成时间）本地会随之清空。同步选用字段的规则与导入相同，选定后始终写入同一个字段，TAPD 侧新增的选项会追加到该字段。
Comments、Attachments、Relations评论、附件和任务关联导入会保留可读取的评论（含编辑时间）、附件（含 TAPD 上的添加时间）和 Story / Bug 之间的关联；描述内嵌的图片会尝试全部转存，转存失败的保留 TAPD 链接并给出告警。与 TAPD 任务、测试用例、Wiki 的关联不会建立，但会在告警中列出。持续同步方向和能力还会受到连接类型限制。
专项不创建当前 TAPD 映射没有 Epic→专项或 Iteration→专项路径，导入的任务默认不因 TAPD 层级获得专项。
无法原样保存的值导入告警 / 同步状态未匹配成员、多人溢出、解析失败、字典缺失、附件跳过、关联对象不在范围等都会在导入完成页“部分字段或关系未能导入”的列表中逐条列出；持续同步中出现时显示在任务的同步状态提示里。私有机（内网代理）连接的同步暂不读取字段字典，自定义字段值不同步并给出告警，发布计划只保留 ID。

连接 TAPD、了解不同连接类型的同步方向和处理限流，请查看 TAPD 集成。

禅道对照

禅道有两条并行结构：产品承载需求与缺陷，项目下的执行承载研发任务。HiFox 因此提供“产品线”和“项目线”两种范围，而不是把两条线强行当成同一棵树。

禅道对象或信息HiFox 对应当前映射与限制
选择的产品线或项目线目标 Space 的来源范围两种范围都导入到用户选择的目标 Space，不会仅因选择了禅道容器就另建 Space。两种范围读取的对象集合不同。
产品线范围需求链 + 缺陷 + 交付链导入所选产品的需求与缺陷，还会沿产品与项目的关联读取交付该产品的项目、执行和任务，使“需求由哪些任务实现”的关系能在同一个 Space 中闭合。
产品线中的 ZenTao Project专项与所选产品关联的每个禅道项目会成为专项；同一禅道项目经多个产品线导入时会复用同一专项，并关联相应 Space。项目负责人（PM）成为专项负责人（可匹配成员时），项目的优先级、创建时间会落到专项；计划 / 实际起止、PO / QD / RD、白名单和工时汇总保存在专项元数据。
项目线范围一个专项 + 其迭代、任务和缺陷仅 hasProduct=0 且未关联任何产品的禅道项目可作为项目线入口。hasProduct=1 的项目不会出现在选择器中；即使手工发起，系统也会拒绝并要求改为导入对应产品。对于合法的项目线，所选项目本身会成为专项；其 Execution 成为迭代，Execution 中的 Task 成为任务，项目关联的 Bug 也成为任务。项目线不会导入 Story / Epic / Requirement，避免把某个产品的部分需求重复导入到项目 Space。
Execution迭代开启导入迭代后，Execution 会在目标 Space 中成为迭代，保留名称、起止日期和状态；Execution 的描述、负责人、实际起止、工时和团队成员写入迭代描述。其中的任务会关联到该迭代和所属专项。
Task任务Task 会成为任务，并按禅道类型映射为设计、开发、需求、测试、研究、讨论、界面、事务或其他等任务类型；禅道自定义或未知的类型归入“其他”，原值保存在「禅道原始类型」并给出告警。多人任务的团队成员和各自工时保存在「团队成员」与「团队成员工时」。Task 的父子树会保留为父子任务。
Bug任务Bug 会成为“缺陷”任务类型的任务。Bug 可从产品线或项目线被读取；同一个缺陷会按稳定来源身份复用，而不是有意创建两份。
22.x 的 Epic → Requirement → Story业务需求 → 用户需求 → 研发需求三类父子任务三层都属于禅道需求金字塔，因此都成为任务，并用父子任务保留层级；Epic 和 Requirement 不会成为专项。无法识别的需求层级按研发需求导入，原值保存在「禅道原始类型」并给出告警。
18.x 的 Story研发需求任务18.x 没有 Epic 和 Requirement 两个上层概念，只导入 Story 层，不展示或伪造空的上层。实现会按实例实际返回的层级字段判断，而不是把 22.x 结构套到 18.x。
对象之间的关系任务关联关联会按禅道语义区分类型：需求与实现它的 Task 为“实现”，Bug 转化的需求 / 任务、需求拆分的任务为“转化”，需求或任务与 Bug 之间为“关联缺陷”，孪生需求为“孪生”，相关需求 / 相关 Bug 为普通关联，重复 Bug 为“重复”。产品线范围会同时读取需求链和交付链，这些关系才能在同一个 Space 中闭合。测试用例的关联不会建立关系，保存在「关联用例」文本中。
标题、正文、状态、优先级、人员、日期和工时任务原生字段各对象提供的标题、正文、状态、优先级、处理人、创建人、开始/截止日期和预估会按字段能力落入原生字段；创建、更新时间取禅道的 openedDate / lastEditedDate。不在禅道开源版字典中的状态会落到兜底状态并给出告警。不同对象可提供的字段并不完全相同。
禅道特有字段HiFox 自定义字段没有原生位置的字段都会成为自定义字段，无值时不会为了占位创建。共有字段：需求阶段、缺陷严重程度、关闭原因、解决方案、类别、来源、所属计划、操作系统、浏览器、影响版本、所属模块、总计消耗、预计剩余、指派 / 关闭 / 激活日期、关闭者、最后修改者、子状态、卡片颜色、层级路径、所属分支、通知邮箱、反馈者、关联用例、代码仓库 / 合并请求 / 代码文件 / 代码行 / 代码版本。需求还有评审人、评审日期、评审结果、来源备注、需求层级、根需求、路线图、需求池条目、工期、变更 / 撤回 / 提交评审 / 阶段设置的人和日期、批准 / 发布 / 验收日期、来源版本、父需求版本、孪生需求；任务还有完成者、完成日期、取消者、取消日期、实际开始日期、任务模式、关联设计、来源 Issue、进度、计划 / 实际工期；Bug 还有解决者、解决日期、激活次数、硬件、解决版本、缺陷识别、缺陷注入、测试结果、发现方式、用例版本、关联 Issue、关联任务、仓库类型。字典之外的阶段、严重程度、关闭原因、解决方案按原值追加为选项；多人字段只存一人，全部姓名保存在「字段名（全部）」；组织内已有同名字段时，类型相同（单选、多选还要求禅道的选项在已有字段中都能找到）就复用，否则新建一个同名字段，类型和选项取自禅道；因此设置中可能出现同名字段，导入完成页会在“以下字段与已有同名字段不兼容，已新建同名字段”下单独列出这些新建的字段，不计为失败。开启“完整入站同步”后，同步选用字段的规则与导入相同，选定后始终写入同一个字段，禅道侧新增的选项会追加到该字段。上面没有列出的其它返回字段（如企业版、旗舰版的工作流扩展字段）也会以列名作为字段名保存为文本字段；所属产品名、上一条 / 下一条等详情页的展示辅助字段不会导入。禅道开源版没有工时日志的读取接口，工时只有消耗 / 剩余两个汇总值。
Keywords、Comments、Attachments、抄送标签、评论、附件和关注者Keywords 会成为标签；评论和附件按导入选项保留：状态流转、指派、关闭等动作附带的备注也会导入为评论并在正文前标注动作，作者无法映射时由导入者代发并标注原作者；附件保留禅道上传者（是成员时）与添加日期，被拒绝的内嵌图片和超过大小上限的附件会在告警中列出。抄送（mailto）中可匹配的成员成为关注者，全部姓名保存在「抄送（全部）」。18.x 某些 Task 响应不提供 Keywords，此时不会把“未知”误当成“没有标签”。
持续同步按对象和字段受限默认只同步任务的标题、状态和处理人。管理员在同步配置中开启“完整入站同步”后，需求（含业务需求、用户需求）和 Bug 也会同步，正文、优先级、日期、预估、全部自定义字段、标签、关注者、评论和附件会随禅道更新（其中不能写回禅道的字段——需求类的正文、处理人和状态，任务与 Bug 的状态，预估和自定义字段——只有禅道侧的值变了才覆盖本地）；禅道的空值不会清空本地内容，尚未推送到禅道的本地修改也不会被覆盖；新增的关联会补上，已有关联不会被删除或改类型。所有绑定（包括新建的）默认关闭此开关。任何情况下都不同步新建对象、任务类型变更、父子关系和专项 / 迭代归属。写回方向仍受限：禅道三类工作项的可写字段不同，状态当前不能安全写回；不支持的写回会保留在 HiFox 并显示限制，而不是假装同步成功。
无法原样保存的值导入告警未匹配成员、多人溢出、未知类型或枚举、解析失败、附件或图片跳过、关联对象不在范围等都会在导入完成页“部分字段或关系未能导入”的列表中逐条列出；持续同步中出现的降级同样按上述规则保存为文本自定义字段，但目前不会在界面上单独提示。

连接禅道、选择导入范围、配置回调和查看同步提示，请查看 禅道集成。

持续同步时，本地修改什么时候会被覆盖

有些字段在 HiFox 里改了也不会写回外部平台，例如 TAPD 和禅道的自定义字段、TAPD 的开始日期、禅道需求的描述、Jira 的任务类型。对这类字段，同步遵循同一条规则：

  • 外部平台上这个字段的值变了：以外部平台为准，覆盖本地的值。
  • 外部平台只改了别的字段（例如只改了标题）：保留你在本地的修改。
  • 升级前就已绑定、还没有同步记录的任务：第一次同步只补上本地为空的字段，不覆盖已有的值；之后按前两条处理。

Jira 依据每次推送附带的变更记录判断字段是否变化；TAPD 和禅道会记住上次同步到的值，用来比较。能写回的字段（如标题、优先级、处理人）仍按写回规则处理：本地修改会推送到外部平台，尚未推送成功前不会被外部的旧值覆盖。禅道上推送失败的本地修改，在禅道那边之后有人编辑过这条对象时，以禅道为准。

选择范围时的快速判断

  • 想把 Jira Epic 及其工作项一起迁入：选择对应 Jira project，Epic 会成为专项，其余 issue 成为任务。
  • 想迁入 TAPD 需求和缺陷：选择 TAPD 项目；Iteration 只用于迭代，不会补出专项。
  • 想保留禅道的 完整需求链与交付关系：选择产品线范围。
  • 只想迁入禅道 某个项目的执行、任务和缺陷：仅当该项目为 hasProduct=0 且未关联任何产品时选择项目线；hasProduct=1 的项目不会出现在选择器中，手工发起也会被拒绝并要求改为导入对应产品。合法的项目线不包含需求链。