#TAPD 集成

TAPD 集成用于把 TAPD 里的项目接入 HiFox：可以先导入已有条目，再按连接上的同步设置保持更新。

欢迎页已经提到可以接入 TAPD。具体入口在设置里的导入流程，以及外部应用集成。菜单名称以线上为准。

#两种凭证

TAPD 开放 API 有两种凭证。导入向导和同步连接都可以二选一，形态参照 Jira 导入的分段切换。

绑定页会用黄字写清这两点：

• 只有 TAPD 付费版才能用「API 账号」；免费版请改用「个人访问令牌」。
• 「个人访问令牌」仅支持从 HiFox 同步到 TAPD，不支持双向实时同步。双向实时同步需要 API 账号。

个人令牌下列出的是你参与的项目。已结束的 TAPD 项目仍会出现在列表中，项目名后有 已结束 标签。实时同步方向以绑定页提示和线上开关为准。绑定成功后会弹出引导：优先配置同步数据，其次导入数据。绑定本身不会自动完成这两步。

#导入和同步

• 导入：把 TAPD 里已有的条目批量搬到 HiFox。适合迁历史数据。
• 同步：按连接上的方向，让之后的变更在两边保持更新。如果目标空间已开启分拣台，同步新建的条目会先进入待分拣。一次性导入历史数据仍按状态映射处理，不一定进入分拣台。同步过来的任务详情里，来源和链接等展示与 Jira 同步任务一致。

如果连接上有「立即检测」，它是按需增量拉取，不是后台不停轮询。免费公司没有 webhook 时，可以用它补入站更新。

自定义字段、开始日期和迭代不会写回 TAPD。持续同步时，只有 TAPD 上这个字段的值变了，HiFox 中的值才会被覆盖；TAPD 只改了别的字段（例如标题）时，你在 HiFox 中的修改会保留。升级前就已同步的任务，第一次同步只补上 HiFox 中为空的字段。完整规则见Jira、TAPD、禅道概念对照中的「持续同步时，本地修改什么时候会被覆盖」。

导入历史数据时可以加一层筛选条件（可选），用法和 Jira 导入的 JQL 类似：先按字段限定范围，再导入。填写后界面会预估按字段筛选后会导入多少需求和缺陷，并和全项目的数量放在一起对比，方便在真正导入前确认范围。不填则等同「不筛选」，导入所选范围内的全部条目。通过私有电脑导入时暂不支持按字段筛选，这种情况会直接导入所选范围内的全部需求和缺陷。

#同步配置

TAPD 集成页的 项目同步 卡片提供 新建同步，向导分五步：配置（绑定、项目、目标 Space 和同步方向，默认双向）→ 映射状态 → 映射用户 → 导入选项 → 确认。

同步列表的每一行，箭头前会显示灰色的 同步配置。点开后这条同步的配置从抽屉里打开，分为 同步设置（持续同步开关、方向、历史数据补导）、用户映射 和 状态映射 三个页签；改动需要保存才生效，带着未保存的更改离开时会先确认。

需要你处理时，不用展开这一行：行下方会直接出现一条黄色提示条，写明需要做什么，尾部带对应的操作按钮，例如重新配置 Webhook 时给出 配置 Webhook。提示条自身的操作不会影响点整行打开同步配置。

用个人访问令牌连接 TAPD 时，定时检测是多个同步项合并做的，所以同一条连接下的同步项会共用一条黄色提示条：说明采用定时检查的原因、上次检查时间和下次检查时间，并给出 立即检测。点它会立即拉取一次并恢复高频检查，正在检测、检测完成（已应用多少项变更）和检测失败都会显示在这条提示条上。

#建立同步后导入历史数据

单独建立 TAPD 同步不会自动把历史条目回填到 HiFox。建立同步关系后，仍可以从 TAPD 集成或导入历史入口选择该工作区，发起一次历史导入；系统会复用已保存的凭证，不要求重新填写 token 或账号。

历史导入默认跳过已经按 TAPD 来源识别到的任务。只有明确打开覆盖导入并确认已有任务数量后，才会刷新这些任务的可变字段；覆盖在原任务上进行，不会因为重新导入而创建重复任务。导入进度、失败项、限流等待、取消和回滚仍按导入任务处理，和后续增量同步是两条不同的流程。

导入后的创建人会尽量保留 TAPD 原始创建人，不要一律显示成导入操作人。对于受支持的人员字段和评论作者，HiFox 会使用 TAPD 与 HiFox 的成员映射；无法匹配到 HiFox 成员时，界面会做兜底展示，具体文案以线上为准。

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

#导入目标和状态映射

在支持该选择器的 TAPD 导入流程中，目标 Space 选择器第一项是 +创建新空间。选择后可以直接创建接收数据的 Space；创建完成后会回到导入流程，并自动将新 Space 设为目标。

导入的用户映射可以把来源用户映射到现有成员，也可以导入为外部账号；「不导入」是明确跳过。未处理过的用户默认导入为外部账号，已经按邮箱匹配到成员的保持匹配。TAPD 成员可能没有邮箱，没有邮箱的用户不能被邮箱匹配，可以保留为外部账号。

#外部账号

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

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

状态映射中选择创建新状态时，会显示 新建状态（来源平台状态名），括号内保留对应的 TAPD 原状态名称，便于确认映射。

#个人访问令牌限流

个人令牌触发 TAPD 限流时，导入界面会展示原因和预计恢复时间。额度恢复后导入会自动继续，一般不必重新发起。

不要把限流等待当成导入失败。普通失败仍走原来的失败提示。

#常见问题

#免费 TAPD 公司应该用哪种凭证？

用个人访问令牌。API 账号需要 TAPD 付费版。

#个人令牌能不能做双向实时同步？

不能。绑定页写明：个人访问令牌只支持 HiFox → TAPD 的单向实时同步。要双向实时同步，需要 API 账号。

#个人令牌要不要填 company_id？

不用。只填 token。可选项目是你参与的项目。