PingCode 集成
PingCode 集成用于把 PingCode 里的项目接入 HiFox：先导入已有工作项，再按同步设置保持更新。范围按 企业 → 项目 → 工作项 逐级选择。
PingCode 集成页分为两个分组：连接与凭据 管理绑定和凭证健康；导入与增量同步 负责发现项目、导入和持续同步。菜单名称以线上为准。
PingCode 集成能做什么？
导入是幂等的：重复执行会按来源识别已有任务并收敛，不会因为重新导入而创建重复任务。
连接 PingCode 前需要准备什么？
连接方式有两种，在 PingCode 集成页的 获取方式 里切换：
几点说明：
- 访问令牌有效期约 30 天，失效后需要重新授权，系统不会自动续期；
- 应用密钥只提交到服务端按 PingCode 官方接口交换令牌，不会保存在浏览器本地；
- 一键授权还需要一个成员授权应用：成员在自己的 PingCode 账号上完成授权时使用，成员不会接触 Client Secret。更换 Client ID 后，已通过一键授权绑定的成员需要重新授权，手动令牌不受影响；
- 连接后可以配置成员授权应用，供组织里其他成员绑定自己的 PingCode 账号。
导入 PingCode 数据
- 在 PingCode 集成页选择已绑定的连接，填入 PingCode 企业 ID；
- 系统发现该企业下你有权限的项目（项目发现），从列表中选择一个，或直接粘贴项目 ID；
- 选择后先做只读预览，确认工作项数量和内容再继续；
- 配置工作项类型映射：选择每种 PingCode 工作项导入后对应的 HiFox 任务类型，未映射的类型会导入为空间默认任务类型；
- 确认导入选项后执行。导入过程显示进度；完成后显示结果，无法以原生字段形式保存的值会在字段告警里逐条列出（见下文）。
导入后的创建人会尽量保留 PingCode 原始创建人。无法匹配到组织成员的用户按下面的「外部账号」处理。
结果页的字段告警
部分字段值无法以 HiFox 原生字段形式保存时会降级处理：能保留的以文本自定义字段保存，不能保留的不写入，并在结果里按 字段、原因 逐条列出。常见原因有五类：
- 成员字段多人：PingCode 一个成员字段里写了多个人，HiFox 对应字段只能存一人（全部姓名会保留在「字段名（全部）」里）；
- 用户未匹配：字段里的 PingCode 用户无法匹配到组织成员；
- 字典缺失：单选 / 多选的选项在 HiFox 同名字段里不存在；
- 类型不支持：该字段类型没有对应的 HiFox 字段类型；
- 与已有同名字段类型不同：组织里已有同名字段但类型不兼容，值无法写入。
配置 PingCode 同步
在 导入与增量同步 分组里选择项目并 新建同步，向导分五步：配置（绑定、项目、目标 Space 和同步方向）→ 映射状态 → 映射用户 → 导入选项 → 确认。
- 同步是定时拉取 PingCode 的改动，不是实时推送；
- 状态映射里选择创建新状态时，会显示 新建状态（来源平台状态名），括号内保留 PingCode 原状态名；
- 已连接的任务上，评论框可以勾选 发布到 PingCode，把这条评论同步写到对应的 PingCode 工作项。任务还没有可发布的 PingCode 链路时不会显示这个入口——需要先把当前空间的项目关联和该任务的工作项同步建好。
外部账号
导入或同步遇到 PingCode 上无法对应到组织成员的用户时，HiFox 会自动创建外部账号承接：保留「平台 + 实例 + 姓名」的来源身份，作为任务处理人显示，但不是组织成员、不占名额、不能登录。
外部账号在 人员 → 外部账号 页签统一管理：可以按平台、实例和关联状态筛选搜索，把外部账号关联到组织成员（邮箱唯一匹配或本人验证过绑定会自动关联，手动关联优先）。关联后自动补全该账号名下历史任务的处理人（人工修改过的不覆盖），解除关联后恢复外部身份。详见 Jira 集成中的「外部账号」说明——各平台行为一致。
回滚导入
导入开始后可以取消；已完成的导入可以在导入历史里回滚。回滚按那次导入的范围撤销，不影响导入之外的任务；重复导入不会再次创建之前已导入的任务，需要重新导入时可以先在导入历史里回滚上一次。
常见问题
访问令牌过期了怎么办？
PingCode 访问令牌有效期约 30 天，失效后集成页会提示凭证问题。一键授权的连接点 重新授权，手动令牌的连接换一个新令牌保存即可。
一键授权和手动令牌可以混用吗？
可以。组织共享连接用哪种方式取决于建立它的人；成员个人绑定走成员授权应用时不会接触 Client Secret，手动令牌不受 Client ID 更换影响。
导入后 PingCode 侧会变化吗？
不会。导入是只读的，只有你配置了同步或在评论框选择 发布到 PingCode 后，HiFox 侧的变化才会写到 PingCode。