迁移数据清单的价值，在于把“要搬什么、搬到哪、按什么规则搬”提前固定成可核对的对象。它是否值得建立，取决于迁移对象数量、字段差异和参与团队复杂度：对象多、字段口径不一致、需要分批切换时，清单能显著降低漏迁和返工；范围小、来源系统可一次性导出核对时，可以先建简版清单。本文按条件分层说明采用判断、清单结构、投入前提与启动阶段。
要点总览（TL;DR）
- 迁移数据清单的核心价值是把迁移对象、字段映射、责任人和状态提前固定成可核对的对象，减少漏迁、口径分歧和返工。
- 对象类型多、字段差异大、多团队协同或需要分批切换时，建议建立完整清单；对象单一、字段简单、可一次性导出核对时，简版记录即可。
- 清单应覆盖对象级信息（对象、来源与目标、数量、负责人、状态）和字段级信息（来源字段、目标字段、转换规则、必填处理），并保留抽样与确认记录。
- 清单建议在迁移立项与范围确认阶段启动，先建对象级骨架，字段映射阶段补充规则，再用一个小对象或团队试点校准颗粒度后推广全量。
- 暂缓完整清单时仍应保留最小核对记录，并在迁移范围扩大时重新评估是否补建。
条件式结论：什么情况下值得建立迁移数据清单
迁移数据清单值得建立的前提，是迁移工作已经复杂到无法靠少数人凭记忆和临时沟通来掌控。判断标准可以落在三个维度上：迁移对象是否超过一类、字段在不同系统间是否存在含义或格式差异、是否有多个团队或多方角色参与确认。三项中占了两项以上，清单就从“额外文档”变成必要的协作基础。
具体来说，以下情况建议建立完整清单：迁移涉及工作项、需求、缺陷、文档、附件、用户与权限等多类对象；来源系统与目标系统的字段名称、枚举值、必填规则存在差异；业务方、技术方、迁移执行方需要分别确认口径。清单在这些条件下承担的是范围基线和核对依据的作用，让各方讨论的是同一份对象列表，而不是各自理解中的迁移范围。
可以简化的前提同样明确：迁移对象单一，例如只迁移一类工作项；字段结构简单，来源字段与目标字段基本一一对应；来源系统支持一次性完整导出，且数据量小到可以人工逐条核对。此时建一份简版清单，记录对象、数量、负责人和核对结果即可，不必投入完整的字段级台账。
结论应分层使用：复杂迁移用完整清单管范围和映射，简单迁移用简版清单管核对，两者都不建议完全不做记录。清单的颗粒度随迁移复杂度调整，而不是按团队规模或项目预算一刀切。
清单要解决的问题：迁移中哪些环节容易失控
迁移项目最常见的失败原因集中在三类失控，清单的价值正是把这三类问题在正式迁移前暴露出来。
范围失控表现为漏迁、多迁和重复迁。漏迁通常发生在附件、评论、历史状态、权限配置这类“附属但重要”的对象上；多迁是把不再使用的历史项目或测试数据一并搬入目标系统，增加清洗成本；重复迁则出现在分批执行时，同一批对象被两次导入。清单以对象为单位登记来源、目标、数量和状态，每一类对象是否有遗漏、是否已执行，都能在表上直接看到。
口径失控表现为同一字段在不同系统中含义不同。例如来源系统中的“状态”包含自定义流程节点，目标系统的状态集合更少；来源系统的“优先级”是五级，目标系统是三级；日期字段的时区处理方式不一致。这些问题在迁移执行时才被发现，往往需要回退重做。清单在字段映射列中提前记录转换规则，把口径分歧变成可评审的条目。
责任失控表现为谁确认口径、谁负责映射、谁执行验收不清晰。迁移期间一个问题从发现到解决，如果找不到对应责任人，就会在多方之间反复流转。清单为每类对象和每组字段指定负责人和确认人，并记录当前状态，使责任落到具体条目上。
这三类问题对应清单的四个基本维度：对象、字段、责任人、状态。清单的作用是把隐性问题变成表上可见、可分配、可关闭的显性问题。
清单应包含的内容与字段结构
一份可用的迁移数据清单通常分为对象级信息和字段级信息两层。对象级信息回答“搬什么、搬多少、谁负责、进展如何”，字段级信息回答“怎么对应、怎么转换、是否核对过”。两层可以放在同一张表的不同区块，也可以拆成对象清单和映射清单两份文档，通过对象编号关联。
| 信息层级 | 字段 | 填写内容示例 | 作用 |
|---|---|---|---|
| 对象级 | 迁移对象 | 工作项、需求、缺陷、文档、附件、用户、权限 | 界定迁移范围 |
| 对象级 | 来源系统 / 目标系统 | 来源项目空间 → 目标项目 | 明确迁移路径 |
| 对象级 | 数量 | 按对象类型统计的条数 | 作为完整性核对基准 |
| 对象级 | 负责人 / 确认人 | 技术执行人、业务确认人 | 落实责任 |
| 对象级 | 迁移状态 | 待盘点、映射中、已迁移、已核对 | 跟踪进度 |
| 字段级 | 来源字段 / 目标字段 | 来源“问题类型” → 目标“工作项类型” | 建立对应关系 |
| 字段级 | 转换规则 | 枚举值对照、格式转换、默认值填充 | 统一口径 |
| 字段级 | 必填与选填 | 目标系统必填但来源缺失时的处理方式 | 提前发现缺口 |
| 核对信息 | 抽样结果 / 差异说明 | 抽样条数、差异条目及原因 | 支撑验收 |
| 核对信息 | 确认人 / 确认日期 | 业务方签字确认 | 留痕 |
对象类型的选择应覆盖研发工具中的主要数据：工作项及其状态流转记录、需求与缺陷、文档页面与附件、用户账号与用户组、角色与权限配置。对于从 Jira 迁移到 ONES 的场景，ONES 的迁移范围覆盖项目、工作项、状态、字段、流程、附件和历史记录，以及用户、用户组和系统配置，清单的对象维度可以参照这一范围逐项登记，避免只登记工作项而遗漏配置类数据。文档类迁移同理，ONES 的 Confluence 迁移覆盖空间、页面、附件和权限结构，清单中应把权限结构单独列为对象，而不是并入页面条目。
字段级信息不必一次填满。范围确认阶段先登记对象和数量，字段映射阶段再逐项补充来源字段、目标字段和转换规则，核对阶段补充抽样结果和确认人。清单随阶段推进逐步细化，比一开始就追求完整更可持续。
适用条件：哪些迁移场景最需要这份清单
清单发挥作用的大小，与迁移场景的复杂度直接相关。以下四类场景最需要完整清单。
- 跨系统且对象类型多、字段差异大。从一套研发工具迁移到另一套，工作项类型、状态机、自定义字段往往无法直接对应。对象类型越多、自定义字段越多，靠口头沟通维持口径的成本越高，清单是唯一能逐条核对的载体。
- 涉及历史数据保留与合规留痕要求。研发过程数据常被用于审计、复盘或交付物追溯，哪些历史记录必须保留、保留到什么颗粒度，需要在清单中明确登记，并在验收时留下确认记录。
- 多团队或多供应商协同迁移。业务团队确认口径、IT 团队执行导出导入、外部服务商负责工具转换时，各方对“迁移完成”的理解容易不一致。清单提供共同的范围定义和状态语言，减少交接争议。
- 需要分批迁移、逐步切换的场景。分批执行时，批次划分、每批包含哪些对象、批间依赖关系都需要记录。清单按批次标注对象归属，可以避免重复迁移和遗漏，也为回退保留依据。
反之，如果迁移只涉及单一项目、对象类型不超过两类、字段基本一一对应，且一次性完成切换，清单的必要性下降，简版记录即可满足核对需要。
投入与前提：建立和维护清单需要什么
建立清单的投入主要在三类人力上。业务方需要投入时间确认口径，包括哪些对象必须迁移、字段的业务含义如何对应、历史数据保留到什么范围；技术方需要梳理来源系统的导出能力和目标系统的字段结构，把可导出、可映射、需转换的情况登记清楚；迁移执行方负责在每批执行后更新状态和核对结果。三类角色缺一类，清单就容易停留在纸面。
前置条件有两项需要提前确认。来源系统能够按对象类型导出数据，且导出结果包含字段定义和数量统计，否则清单中的数量基准无法建立；目标系统的字段结构、必填规则和枚举值可以查阅，否则映射规则无从填写。这两项条件在迁移立项阶段就应核实，发现缺口时调整迁移方案，而不是等到执行阶段。
维护成本集中在迁移期间。清单需要随盘点、映射、执行、核对各阶段持续更新，状态字段才有意义；切换完成后，清单应作为迁移记录归档，供后续审计或二次迁移参考，不再日常维护。
清单与相邻文档有明确分工：清单管对象、数量、责任人和状态；映射文档管字段转换规则的详细定义；验证记录管抽样结果、差异条目和处理结论。三者可以合并在一份工作簿中，但职责不能混在一起，否则清单会因承载过多细节而难以维护。ONES 在迁移方法上建议正式迁移前确认数据范围、功能匹配和系统适配，并把迁移工具、原厂服务和分阶段切换结合使用，清单正是“确认数据范围”这一动作的可核对产物。
暂缓条件：什么时候可以先不建完整清单
完整清单并非所有迁移项目的必需项。以下条件同时成立时，可以先不建字段级台账，改用简版记录。
- 迁移对象单一，例如只迁移一个项目下的工作项，不涉及文档、权限和配置数据。
- 字段结构简单，来源字段与目标字段基本一一对应，无需枚举值转换或格式处理。
- 来源系统可一次性完整导出，数据量在人工可核对范围内，导出结果本身就能作为范围基准。
- 一次性切换，没有分批执行和回退安排，迁移窗口短，协调方少。
暂缓完整清单时，仍应保留最小核对记录：迁移对象及数量、导出时间、核对人、核对结论、发现的差异及处理方式。这份记录可以是一张简单的表格或一段归档说明，作用是切换后出现数据疑问时有据可查。暂缓的是字段级映射台账和状态跟踪，不是核对本身。
需要提醒的是，暂缓判断应随迁移范围变化重新评估。最初计划只迁工作项，后来加入文档和权限，清单的必要性就上升，应及时补建，而不是沿用简版记录硬撑。
试点判断：从哪个阶段开始建立并验证清单
清单建议在迁移立项与范围确认阶段启动，此时先建对象级骨架，只登记迁移对象、来源系统、目标系统、预估数量和负责人。这个阶段的清单不追求字段完整，目的是让各方对迁移范围形成同一份列表，并在立项评审中确认哪些对象纳入、哪些排除。
进入字段映射阶段后，再为每类对象补充字段级信息：来源字段、目标字段、转换规则、必填处理方式。此时清单与映射文档同步细化，映射评审的结论直接回写到清单中，避免两份文档各说各话。
在推广到全量之前，建议用一个小对象或一个团队做试点，验证清单是否够用。试点可以选择一类字段较多的工作项，或一个数据量适中的项目，完整走一遍盘点、映射、迁移、核对流程。试点要回答三个问题：清单中的字段是否足以支撑核对；状态定义是否让执行方清楚下一步做什么；责任分配是否让问题能找到人。根据试点结果调整字段和颗粒度，再推广到全量迁移。
试点还有一个作用，是校准数量基准。用试点对象的实际迁移条数与清单登记数量比对，可以验证导出统计口径是否一致，这个校准结果直接用于全量迁移的完整性核对。清单在试点中暴露的缺口，修改成本远低于全量执行后返工。
常见问题
迁移数据清单和字段映射文档、验证记录有什么区别，能不能合成一份？
三者职责不同：清单管对象、数量、责任人和迁移状态，回答“搬什么、搬多少、谁负责”；映射文档管字段转换规则的详细定义，回答“怎么对应、怎么转换”；验证记录管抽样结果、差异条目和处理结论，回答“核对过没有、差异怎么处理”。
三者可以放在同一份工作簿的不同区块，通过对象编号关联，但职责不宜混在一起。如果清单承载过多字段细节，维护成本会上升，状态跟踪也容易失焦。实际操作中，范围确认阶段先维护清单，映射评审的结论回写到映射区块，核对阶段再补充验证记录。
迁移进行到一半才发现清单漏了对象类型，应该怎么处理？
先评估遗漏对象的影响范围：是否已进入映射或执行阶段、是否与其他对象存在依赖关系、是否影响已完成的核对结论。如果遗漏的是附件、评论、权限配置这类附属对象，通常可以在当前批次补充登记，并重新核对受影响对象的数量基准。
如果遗漏的是独立的对象类型，例如文档或用户权限，建议暂停相关批次的执行，补建对象级条目和字段映射后再继续。此时清单的颗粒度应重新评估，因为对象类型增加往往意味着字段差异和协同复杂度同步上升。补建完成后，把这次遗漏的原因记录在清单的差异说明中，作为后续批次和二次迁移的参考。
来源系统导出能力有限，无法按对象类型统计数量，清单还能建立吗？
可以建立，但数量基准需要换一种方式确认。先登记对象类型和负责人，数量字段暂填“待确认”，并在前置条件中标注导出能力的缺口。随后与来源系统的管理员确认可用的导出方式，例如按项目导出、按时间范围导出或通过接口分批获取，用多次导出的结果汇总出数量。
如果确实无法获得准确数量，核对方式改为抽样比对：从来源系统抽取一定比例的记录，与迁移后的目标系统逐条比对，并在清单中记录抽样比例和差异情况。这种方式的范围基准弱于全量统计，需要在验收结论中说明其局限，避免把抽样通过当成全量完整的证明。
分批迁移时，清单的批次信息应该怎么记录？
建议在对象级信息中增加批次字段，标注每个对象归属的批次编号，并记录批次之间的依赖关系，例如用户与权限需要在工作项迁移之前完成。每批执行前确认该批对象的映射规则已评审，执行后更新状态和核对结果。
批次划分还应考虑回退需要：同一批内的对象如果存在强依赖，回退时会一起受影响，清单中应注明这种关联。批间核对时，用累计已迁移数量与清单登记数量比对，可以及时发现重复迁移或遗漏。批次信息在切换完成后随清单一起归档，供后续追溯。
使用 ONES 的迁移方案时，清单的对象维度可以参考哪些范围？
从 Jira 迁移到 ONES 的场景，ONES 的迁移范围覆盖项目、工作项、状态、字段、流程、附件和历史记录，以及用户、用户组和系统配置，清单的对象维度可以参照这一范围逐项登记，避免只登记工作项而遗漏配置类数据。文档类迁移同理，ONES 的 Confluence 迁移覆盖空间、页面、附件和权限结构，清单中应把权限结构单独列为对象。
ONES 在迁移方法上建议正式迁移前确认数据范围、功能匹配和系统适配，并把迁移工具、原厂服务和分阶段切换结合使用。清单是“确认数据范围”这一动作的可核对产物，具体字段结构仍需结合自身迁移范围设计。
