研发数据迁移准备中，迁移数据清单和迁移映射表经常被混用，实际分工很明确：清单回答“要搬哪些数据”，按对象逐条界定范围、数量、来源位置和批次；映射表回答“每个字段怎么搬”，按字段记录来源与目标、类型转换、取值规则和异常处理。清单先定范围，映射表再定规则，两者前后衔接。本文按统一维度对照两份文档，并给出可直接起草的字段结构。
要点总览（TL;DR）
- 迁移数据清单以数据对象为单位界定范围，回答“要搬哪些数据、搬多少、先搬哪一批”；迁移映射表以字段为单位界定规则，回答“每个字段怎么搬、搬不过去怎么办”。
- 两份文档的差异来自用途不同：清单服务于范围确认和批次排期，映射表服务于字段转换和结果核对，不涉及重要程度高低。
- 清单的核心字段是对象名称、来源位置、目标对象、记录数量、迁移方式、批次、负责人和状态；映射表的核心字段是来源与目标字段、数据类型、转换规则、空值处理、枚举对照、校验规则和异常负责人。
- 推进顺序是先清单定范围、再映射表定规则；范围变更先改清单，规则变更先改映射表，两份文档都保留版本记录。
- 小规模单对象迁移可以简化文档，底线是对象范围有书面记录、关键字段的转换规则有明确约定。
两者各自解决什么问题
迁移数据清单是以数据对象为单位的范围文档。它把本次迁移涉及的项目、工作项、文档空间、附件、用户与权限等对象逐条列出，说明每个对象从哪个系统、哪个位置来，要迁到哪个目标对象，涉及多少条记录，安排在哪个批次。它回答的核心问题是“搬什么、搬多少、先搬哪一批”。
迁移映射表是以字段为单位的规则文档。它针对清单中已确认的对象，逐字段说明来源字段与目标字段的对应关系、数据类型是否需要转换、枚举值如何对照、空值和默认值怎么处理、校验不通过时由谁处理。它回答的核心问题是“每个字段怎么搬、搬不过去怎么办”。
两份文档在流程中的位置不同。迁移准备通常先梳理对象和范围，形成清单并据此排批次；随后针对进入批次的每个对象编写映射表，把字段级规则确定下来。清单是映射表的输入，映射表是清单在字段层面的展开。缺少清单，映射表不知道要覆盖哪些对象；缺少映射表，清单只能说明搬多少，无法说明搬过去之后字段取值是否正确。
同口径差异对照
两份文档的差异来自用途不同，不涉及重要程度高低。清单服务于范围确认和批次排期，映射表服务于字段转换和结果核对。下表按同一组维度对照。
| 对照维度 | 迁移数据清单 | 迁移映射表 |
|---|---|---|
| 管理粒度 | 以数据对象为单位，一个对象一行 | 以字段为单位，一个字段映射一行 |
| 核心字段 | 对象名称、来源系统与位置、目标对象、记录数量、迁移方式、批次、负责人、状态 | 来源对象与字段、目标对象与字段、数据类型、转换规则、空值处理、枚举对照、校验规则、异常负责人 |
| 主要责任人 | 迁移项目负责人或数据 owner，负责确认范围与批次 | 熟悉源系统与目标系统字段结构的业务或技术人员，负责确认转换规则 |
| 产出时点 | 迁移准备早期，用于范围评审和批次排期 | 对象进入批次前后，用于开发配置和评审 |
| 变更影响范围 | 范围增减会影响批次、工作量和资源投入 | 规则调整影响字段转换逻辑和核对结果，通常不改变批次 |
| 在验收中的作用 | 核对对象是否齐全、数量是否对得上 | 核对字段取值、枚举和空值是否符合约定规则 |
从表中可以看出，清单的变更往往牵动排期，映射表的变更更多落在转换逻辑上。实际项目中两份文档都需要评审和版本记录，区别在于评审的关注点：清单评审看范围是否有遗漏或多余，映射表评审看规则是否覆盖全部字段、异常是否有归属。
迁移数据清单的核心字段与填写要点
清单可以直接按下面的字段结构起草。对象粒度建议与目标系统中的管理单元对齐，例如一个项目、一个文档空间、一类配置各占一行，避免把整个系统写成一行导致后续无法排批次。
| 字段 | 填写内容 | 填写要点 |
|---|---|---|
| 数据对象 | 项目、工作项、状态与流程、字段配置、附件、评论、用户与权限、文档页面等 | 按目标系统的管理单元切分，粒度细到可以单独安排批次和验收 |
| 来源系统与位置 | 源系统名称、空间或项目标识、具体路径 | 写清可定位的位置，便于后续取数和核对 |
| 目标对象 | 目标系统中的对应项目、空间或配置项 | 与来源对象一一对应，合并迁移时注明合并关系 |
| 记录数量 | 对象内的记录条数或文件数量 | 注明统计口径，例如按工作项条数还是按含子任务条数统计，同一份清单保持口径一致 |
| 迁移方式 | 全量、增量或抽样 | 增量需注明时间范围或起始基线；抽样需注明抽样规则和用途 |
| 优先级与批次 | 批次编号与批次内顺序 | 按业务依赖和停机窗口安排，被依赖的对象先迁 |
| 负责人 | 对象级负责人 | 负责确认范围、提供取数条件和验收本对象 |
| 状态 | 待确认、已确认、迁移中、已核对等 | 状态随批次推进更新，作为进度同步的依据 |
数量口径是清单中最容易产生分歧的地方。同一批工作项，按主记录统计和按含子任务、含评论统计会得到不同数字，清单应在表头或备注中固定一种口径，并在验收时沿用同一口径。批次排期则依赖对象之间的依赖关系：用户与权限通常先于业务数据，字段与流程配置先于工作项记录，附件和评论跟随所属对象同批处理。
迁移映射表的核心字段与填写要点
映射表按字段逐行填写，下面的结构覆盖了常见迁移场景所需的规则信息。
| 字段 | 填写内容 | 填写要点 |
|---|---|---|
| 来源对象与字段 | 源系统中的对象名和字段名 | 使用源系统中的实际字段标识，避免只写显示名称 |
| 目标对象与字段 | 目标系统中的对象名和字段名 | 与来源字段对应，目标字段需已存在或列入配置准备 |
| 数据类型 | 来源类型与目标类型 | 类型不一致时在转换规则中写明转换方式 |
| 转换规则 | 直接对应、格式转换、拼接、截取、计算等 | 规则写到可执行的程度，例如日期格式、字符串截断长度 |
| 默认值与空值处理 | 源字段为空时目标字段的取值 | 区分“留空”“填默认值”“跳过该条记录”三种处理，并注明适用条件 |
| 枚举值对照 | 源枚举值与目标枚举值的对应关系 | 逐值列出，源系统中存在但目标系统没有的值需单独标注处理方式 |
| 校验规则 | 必填、长度、取值范围、唯一性等 | 校验不通过时的处理动作与映射规则写在同一行，便于执行 |
| 异常处理与负责人 | 异常类型、处理方式、责任人 | 明确哪些异常由业务确认、哪些由技术处理 |
常见映射情形需要在表中明确表达。一对多映射，例如一个来源字段拆成目标系统的多个字段，可以拆成多行，每行写清拆分规则；多对一映射，例如多个来源字段合并为一个目标字段，在转换规则中写明合并顺序和分隔符；字段合并与拆分涉及取值冲突时，需在异常处理中写明冲突时的取舍规则。枚举值对照建议单独维护一张对照子表，映射表主表引用对照关系，避免同一组枚举在多行中重复维护。
映射表与清单通过对象和字段两级关联：映射表的每一行都应能追溯到清单中的某个对象，清单中的每个对象在进入批次时应有对应的映射表覆盖其全部需迁移字段。评审时可以按清单对象逐个检查映射表覆盖率，发现未覆盖字段及时补充。
如何配合使用与选择建议
推进顺序建议是先清单、后映射表。先通过清单确认对象范围、数量口径和批次，组织范围评审；范围确认后，再针对首批对象编写映射表，逐字段确认转换规则并评审。两份文档都定稿后再进入实际迁移配置，可以减少因范围反复导致的规则返工。
维护上按变更类型分流：对象增减、数量口径调整、批次调整，先改清单，再同步检查受影响对象的映射表是否需要增删；字段对应关系、转换规则、枚举对照、异常处理调整，先改映射表，清单通常不变。两份文档都保留版本记录，评审结论与变更原因一并留存，便于迁移核对时追溯。
小规模单对象迁移可以适当简化。例如只迁移一个项目的工作项且字段结构简单时，清单可以压缩为一张对象范围说明，映射表可以只保留来源字段、目标字段、转换规则和异常负责人四列。简化的底线是对象范围有书面记录、关键字段的转换规则有明确约定，避免迁移完成后无法说明哪些数据在范围内、字段取值依据是什么。
进入核对阶段后，清单用于核对对象是否齐全、记录数量是否与统计口径一致，映射表用于核对字段取值、枚举和空值是否符合约定规则。两份文档在这一阶段作为核对依据被引用，具体的核对方法与切换安排属于另外的工作内容。
当迁移对象较多、需要多人协作维护清单与映射表时，可以把每个对象作为一项工作项跟踪状态和负责人，把映射表作为与对象关联的文档管理，评审记录和版本留在文档中。ONES 的 Jira 迁移范围可覆盖项目、工作项、状态、字段、流程、附件和历史记录，迁移问题数据时包含属性和属性值、附件、评论等信息，项目迁移还可包含问题类型、工作流、字段配置、权限配置等系统配置；Confluence 迁移支持用户、用户组、空间与页面权限，以及页面正文、附件、图片、常用宏和批注，迁移方式支持批量迁移与数据包导入。这些范围信息可以帮助在清单阶段确认对象边界。对于存在插件依赖的场景，ONES 建议先梳理实际使用的插件并逐项评估定制场景，这一评估结论也可以回写到清单的对象备注中，作为范围确认的一部分。
常见问题
迁移数据清单和迁移映射表可以合并成一份文档吗？
可以合并，但需要保留两级结构。常见做法是在同一份表格中先按对象列出范围行，再在每个对象下展开字段映射行，用层级或分组区分。合并的前提是对象数量不多、参与维护的人较少；当对象数量增加、多人分头维护时，建议拆成两份文档，避免范围变更和规则变更混在一起，评审时难以区分关注点。
迁移过程中发现清单漏了一个对象，应该怎么处理？
先补清单，再判断该对象是否进入当前批次。补充内容包括来源位置、目标对象、记录数量、迁移方式和负责人，并重新评估批次排期与工作量。如果该对象已进入当前批次，还需要为其补写映射表并完成评审；如果安排到后续批次，则在清单中标注批次并同步通知相关核对人员。范围变更记录与变更原因一并留存，便于后续追溯。
源系统字段在目标系统中没有对应项，映射表里怎么写？
在映射表中单独标注该字段的处理方式，常见选择有三种：写入目标系统的备用字段或描述字段、合并到某个已有字段、放弃迁移并在文档中记录原因。无论选哪种，都要在异常处理列写明责任人和确认结论。枚举值在目标系统中缺失时，同样需要逐值标注处理方式，避免迁移后出现无法解释的取值。
两份文档在迁移核对阶段分别怎么用？
清单用于核对对象是否齐全、记录数量是否与既定统计口径一致；映射表用于核对字段取值、枚举对照和空值处理是否符合约定规则。核对时按清单对象逐个检查映射表覆盖率，发现未覆盖字段及时补充。具体的核对方法、抽样比例和切换安排属于迁移验证与切换管理的工作内容，本文不展开。
使用 ONES 的迁移能力时，清单和映射表还需要自己准备吗？
需要。ONES 的 Jira 迁移范围可覆盖项目、工作项、状态、字段、流程、附件和历史记录，迁移问题数据时包含属性和属性值、附件、评论等信息，项目迁移还可包含问题类型、工作流、字段配置、权限配置等系统配置；Confluence 迁移支持用户、用户组、空间与页面权限，以及页面正文、附件、图片、常用宏和批注，迁移方式支持批量迁移与数据包导入。这些范围信息可以帮助在清单阶段确认对象边界。对于存在插件依赖的场景，ONES 建议先梳理实际使用的插件并逐项评估定制场景，评估结论可以回写到清单的对象备注中。
