飞书项目迁移 TAPD 教程

• Fork 本仓库到你任意组织下 → tapd.cn/migrate-collaboration
• 点击 一键部署迁移 按钮，等待加载出项目协同迁移界面
• 开始迁移
• 迁移日志：页面「下载日志」按钮，或构建调试按钮执行 docker logs -f migrate-collaboration-web

📋 【汇总】TAPD迁移工具

掌握正确的产品迁移姿势，让迁移事半功倍 ✅

---

---

---

TAPD 中手动创建工作项类别，选择飞书项目工作项类别和 TAPD 工作项类别的迁移映射关系。

---

客户手动创建需要的版本名称，读取「飞书版本下的需求 list」，更新需求 API 写入版本字段。

---

客户操作：

1. 在【迭代】下手动创建需要的自定义字段，名称和飞书中保持一致作为映射关系
2. 在「应用设置 → 迭代」打开支持将父需求规划进入迭代开关

迁移说明：

• 创建迭代 API：add_iteration
• TAPD：【迭代】拉取 cus_{$自定义字段别名}，并迁移数据
• 读取飞书项目「版本/迭代」list → TAPD 中映射创建
• 飞书【迭代】→ TAPD【迭代】，工作流不需要迁移

---

为每个工作项创建工作流（包含用户故事、需求、自定义需求、缺陷、任务）。获取飞书各个工作项的工作流，然后在 TAPD 中创建工作流。

备注： 迁移为一套工作流，增加一个「流程」下拉单选字段，区分 飞书的工作流流程

额外说明： 客户需求流程结束，飞书项目 API 不返回节点信息。「节点流程」到最后一个节点没有 current_nodes 的情况，代表工作项全部节点完成，直接写入文案【结束】

---

写入 TAPD 工作项：1、识别字段创建；2、创建 TAPD 工作项。

迁移范围：

• 飞书【项目集、项目】→ TAPD【工作项】
• 除了「迭代、版本」，其余都迁移为工作项

⚠️ 注意事项：

1. 非 TAPD 已有字段类型 不支持迁移，如：富文本（详情除外）、日期区间、投票、链接等红框字段

2. 「角色与人员」迁移为人名字段

---

识别飞书附件类型字段，迁移为 TAPD 附件。字段类型：附件、单文件附件。

---

1. 节点下的工作项，迁移为子需求
2. 层级关系仅支持父子

3. 迭代中的需求

4. 父子需求的关系（项目集、项目 → 迁移为工作项）

💡 附件字段迁移到 TAPD 附件；关联关系字段后续迁移关联。

---

客户：在【迭代】下手动创建需要的自定义字段，名称和飞书中保持一致作为映射关系。

TAPD：【迭代、版本】拉取 cus_{$自定义字段别名}，并迁移数据。

TAPD 字段	飞书字段	备注	截图参考
状态	work_item_status	客户需手动更新"迭代状态"的系统候选值
目标	description	—
创建人	owner	—
开始日期	field_adbe79	遇到「迭代周期」字段且类型为"日期区间"，开始/结束时间分别写入 TAPD 两个日期字段
结束日期	field_adbe79	同上
自定义字段	飞书其他字段	—

---

TAPD 字段	飞书字段	备注	截图参考
标题	name	—
详细描述	description	—
优先级	priority	客户需手动更新"优先级"系统候选值
预计开始	-	无	—
预计结束	-	无	—
预估工时	评估支持时间	—	—
处理人	current_status_operator	—
开发人员	-	无	—
分类	-	无	—
自定义字段	飞书自定义/系统字段	飞书每个类别一套自定义字段，候选值不同。TAPD 中是一套。API：add_custom_field_config

---

序号	不支持项	说明	截图参考
1	TAPD 不存在的字段类型	无法迁移	—
2	需求详情中的工作项链接	迁移存在前后置关系，保持飞书项目中的链接。后续：文档迁移映射	—
3	关联项目集、关联项目字段	不支持迁移
4	需求联动：挂载的视图	不支持迁移