研发数据增量迁移是在首次全量迁移完成后，按固定节奏把源系统中新增和变更的研发数据持续写入目标系统。它成立的关键条件有三项：全量与增量之间有明确分界点，增量数据能被稳定识别，字段与关联关系有可核验的映射规则。本文按范围划定、前置依赖、增量识别与映射、试迁移核验、停止与回退五个阶段展开，适用于工作项、需求、缺陷、迭代、评论、附件元数据等数据内容的迁移。
要点总览（TL;DR）
- 增量迁移以全量迁移截止时间为分界点，先冻结范围清单：明确源系统与目标系统、纳入增量的对象（工作项、需求、缺陷、迭代、评论、附件元数据）以及排除项。
- 启动前需具备四项条件：可读取的变更时间字段或变更日志、目标端对象与必填字段已建好、稳定的唯一标识方案、字段字典与枚举值清单，并区分执行人与核对人。
- 增量识别可用更新时间戳、变更日志或版本号；同名字段先比对定义与取值范围，再决定直接映射、转换、拆分或合并，枚举值与状态单独建对照表。
- 试迁移选取覆盖不同状态、含附件评论与关联关系的代表性批次，按数量核对、字段抽样、关联抽查、状态核对四步验证，并留存比对记录、差异清单与批次结论。
- 预设停止与回退条件：差异率超阈值、关键字段映射失败、关联断裂时暂停后续批次，按影响面选择单批回退或回到稳定恢复点，恢复后从对应水位重新识别增量。
增量迁移的源、目标与对象范围怎么划定
范围清单是增量迁移的第一份交付物。它要回答三个问题：数据从哪个系统流向哪个系统、哪些对象进入增量通道、增量从什么时间点开始计算。范围含糊会直接导致后续映射表和核验口径失焦，因此这份清单应在动手写任何迁移脚本或配置之前完成评审。
源系统与目标系统的角色需要写清楚，包括产品名称、版本和部署形态。方向只有一个：源系统是读取方，目标系统是写入方。如果迁移过程中存在中间库或临时表，也要在清单中标注其位置和用途，避免执行时把中间表误当目标端统计条数。
纳入增量的对象应逐项列出，常见研发数据对象包括：
- 工作项（任务、故事等）及其状态变更记录；
- 需求与缺陷条目；
- 迭代或版本信息；
- 评论与操作历史；
- 附件元数据（文件名、大小、上传人、关联对象）。
全量与增量的分界点通常取全量迁移的截止时间戳，并预留一段重叠窗口。例如全量迁移在某一时刻完成快照，增量起点可以回拨若干小时，用重叠数据检验识别规则是否漏数。分界点一旦确定，应写入范围清单并冻结，后续调整需走变更记录。
排除项同样要写明。流程配置、插件行为、权限设置等属于系统配置与行为迁移，归其他主题处理，不进入本文的增量数据通道。附件正文文件是否随增量同步、历史评论是否全量保留，也应在清单中给出明确取舍，而不是留给执行阶段临时决定。
| 清单项 | 填写内容 | 示例 |
|---|---|---|
| 源系统 | 产品、版本、部署形态 | 源端项目管理系统，版本待确认 |
| 目标系统 | 产品、版本、项目空间 | 目标端研发管理平台，指定项目 |
| 迁移方向 | 源→目标，单向 | 只读源端，只写目标端 |
| 增量对象 | 对象类型清单 | 工作项、需求、缺陷、迭代、评论、附件元数据 |
| 分界点 | 全量截止时间与重叠窗口 | 全量快照时刻回拨若干小时 |
| 排除项 | 不纳入本阶段的内容 | 流程配置、插件行为、权限设置 |
增量迁移需要哪些输入与前置依赖
增量迁移启动前，需要同时具备数据条件、目标端条件、标识条件和人员条件。任何一项缺失，都会让后续核验失去基准。建议把下列内容做成核对表，逐项确认后再进入试迁移。
数据条件。源系统必须能读取变更时间字段或变更日志。变更时间字段要求覆盖所有纳入增量的对象类型，且时区口径统一；变更日志则要求能按时间区间拉取新增、修改、删除三类事件。如果源系统只提供最后修改时间而无删除记录，删除类变更需要单独约定处理方式，例如在目标端做标记而非物理删除。
目标端条件。目标系统中对应的对象类型、必填字段和状态值应已建好。必填字段缺失会导致写入被校验拦截，这类拦截在试迁移阶段暴露比在正式增量阶段暴露代价小得多。字段类型也要提前确认，例如源端的单选字段在目标端是单选还是多选，直接影响映射规则。
唯一标识方案。每条增量记录需要稳定的标识，用于判断“这条数据是否已迁移过”。常用方案是源系统ID加对象类型前缀，业务编号可作为辅助校验。标识方案要写入映射表，并在目标端保留可查询的源ID字段，便于后续对账和差异定位。
字段字典与枚举值清单。从源系统导出字段清单，包含字段名、类型、取值范围和是否必填；同时导出目标端字段清单。两份清单是建立映射表的输入，也是发现同名字段含义差异的依据。
人员分工。执行人负责跑增量、记录批次和处理写入异常；核对人负责抽样比对和签署核验结论。两个角色由不同人员承担，可以减少“自己迁移自己验收”带来的盲区。涉及字段定义争议时，还需要业务侧字段负责人参与裁定。
增量识别与字段映射怎么做
增量识别解决“哪些数据要搬”，字段映射解决“搬过去变成什么”。两者共同决定增量通道的准确性，建议先定识别规则，再逐字段建映射，最后用一张映射表把规则固化下来。
增量识别规则
常见的识别方式有三种，可按源系统能力选择或组合使用：
- 更新时间戳：按“最后修改时间大于上次同步水位”拉取记录，实现简单，适合大多数工作项类数据。水位应记录到批次表中，每次成功后推进，失败时不推进。
- 变更日志：按时间区间读取新增、修改、删除事件，能覆盖删除和字段级变更，适合对完整性要求高的对象。
- 版本号或递增序列：源系统提供记录版本号时，按版本号变化识别变更，可与时间戳互为校验。
识别规则要写明边界处理：同一秒内多条变更如何排序、水位时间是否包含端点、跨时区数据如何归一。规则说明与批次表一起归档，作为后续排查“某条数据为何没同步”的依据。
同名字段含义不同时的映射处理
同名字段不等于同一含义。例如源端的“状态”可能包含“待评审、开发中、已关闭”，目标端的“状态”可能按工作流阶段划分且取值不同；源端的“优先级”是三级，目标端是五级。处理顺序是：先比对字段定义与取值范围，再决定映射动作。
- 直接映射：定义与取值范围一致，字段值原样写入。
- 转换映射：含义对应但取值不同，通过对照表转换，例如三级优先级映射到五级中的对应档位。
- 拆分映射：源端一个字段承载多种信息，目标端拆成多个字段，例如“模块/子模块”拆为两个字段。
- 合并映射：源端多个字段在目标端合并为一个，需要约定合并优先级和冲突时的取值规则。
枚举值与状态字段必须单独建对照表，逐值列出源值、目标值和转换说明。对照表中出现“无对应值”时，要明确落到默认值、保留原值还是进入差异清单人工处理，不能留空。
| 源字段 | 目标字段 | 转换规则 | 负责人 |
|---|---|---|---|
| issue_key | 源ID（自定义字段） | 直接写入，作为唯一标识 | 迁移执行人 |
| status | 工作项状态 | 按状态对照表转换，无对应值进差异清单 | 业务字段负责人 |
| priority | 优先级 | 三级转五级，按对照表取值 | 业务字段负责人 |
| component | 模块、子模块 | 按分隔符拆分为两个字段 | 迁移执行人 |
| assignee | 负责人 | 按人员账号对照表转换，未匹配进差异清单 | 迁移执行人 |
| updated | 最后更新时间 | 时区归一后写入 | 迁移执行人 |
关联关系的处理
一对多和多对一关系是增量迁移中最容易断裂的部分。父子工作项、工作项与迭代、评论与所属工作项、附件与关联对象，都需要先迁移被引用方或同批次写入，再建立关联。处理方式有两种：按依赖顺序分批写入，或先写主体再回填关联字段。无论哪种，映射表都要记录关联字段的源端表达方式和目标端表达方式，并在核验阶段抽查关联是否可打开。
在ONES的Jira迁移方案中，迁移范围覆盖项目、工作项、状态、字段、流程、附件和历史记录，问题数据的属性与属性值、附件、评论也在迁移内容之列。这为建立字段映射表提供了对象层面的参照：映射表应按这些对象类型分组维护，每组指定负责人，状态与字段配置的对应关系在迁移前逐项确认。
分批试迁移与核验证据如何组织
试迁移的目的不是搬完全部数据，而是用有代表性的小批量验证识别规则和映射表是否正确。建议选取覆盖不同对象类型、不同状态、含附件与评论、含跨对象关联的批次，数量控制在便于逐条核对的规模。
每批试迁移完成后，按以下顺序核验：
- 数量核对：源端该时间窗口内的增量条数与目标端写入条数对比，分别统计新增、修改、删除三类，差额要能逐条解释。
- 字段抽样比对：按对象类型抽取样本，逐字段比对源值与目标值，重点检查经过转换和拆分的字段。
- 关联关系抽查：从目标端打开工作项，确认父项、迭代、评论、附件关联均可访问且指向正确对象。
- 状态与枚举核对：抽查状态字段，确认对照表在真实数据上成立，无对应值的记录已进入差异清单。
核验证据要能支撑“这批数据可以继续增量”的判断，建议留存三类材料：比对记录（批次号、时间窗口、样本清单、比对结果）、差异清单（差异记录、差异类型、处理结论、处理人）、批次结论（通过、有条件通过、退回修改）。差异按原因分类，便于定位责任环节：映射错误归映射表维护人，源数据缺失归源系统数据负责人，目标校验拦截归目标端配置负责人。
试迁移通过后，正式增量按相同规则分批执行，每批保留同样的证据材料。批次记录与水位表配套保存，形成可追溯的迁移日志。
增量迁移的回退与停止条件
增量迁移需要预设停止线和回退方案，并在启动前与相关方确认。停止条件用于阻止问题扩散，回退条件用于把目标端恢复到可继续工作的状态。
触发停止的典型条件包括：
- 单批差异率超过事先约定的阈值，且差异原因未定位；
- 关键字段映射失败，例如状态、负责人、所属项目出现大面积无对应值；
- 关联关系断裂，目标端出现无法打开父项或迭代的工作项；
- 目标端写入被校验大面积拦截，批次成功率明显低于试迁移水平。
阈值应在试迁移阶段根据实际差异情况设定，并写入停止与回退判断清单。达到停止条件时，先暂停后续批次、保留当前批次记录，再判断是修正映射后重跑本批，还是进入回退。
回退范围按影响面选择：单批映射错误且影响可枚举时，按批次回退该批写入的数据；出现跨对象关联错乱或标识冲突时，考虑回退到上一个稳定恢复点。回退前要留存目标端当前数据快照或导出差异记录，明确恢复点对应的批次号和水位时间。恢复完成后，重新增量的起点取恢复点对应的水位，重叠窗口内的数据重新识别，避免遗漏或重复。
回退与停止的判断结论应记录在案，包含触发条件、影响批次、处理动作和恢复后的水位。这份记录与范围清单、映射表、核验记录一起，构成增量迁移的完整交付物。
常见问题
全量迁移已经做过一次，增量起点为什么还要留重叠窗口？
全量迁移的快照时刻与增量读取之间存在时间差，快照生成过程中仍在变更的数据可能落在两者之间。把增量起点从全量截止时间回拨一段重叠窗口，可以让这部分数据被重新识别一次，再通过唯一标识判断是否已写入，从而检验识别规则是否漏数。重叠窗口的长度按源系统变更频率和数据量确定，写入范围清单后冻结，调整时走变更记录。
源系统只记录最后修改时间，没有删除日志，删除类变更怎么处理？
这种情况下，增量识别只能覆盖新增和修改，删除动作需要在方案中单独约定。常见做法是在目标端做标记而非物理删除，例如增加“源端已删除”状态字段，由源系统定期导出删除清单或由业务方确认后批量标记。无论采用哪种方式，都要在范围清单和映射表中写明处理规则，并在核验阶段抽查标记记录是否与源端一致，避免目标端长期保留已不存在的条目。
字段映射表由谁维护，出现映射争议时怎么裁定？
映射表通常由迁移执行人维护结构和转换规则，业务字段负责人确认字段定义与取值口径。出现争议时，以字段字典中的定义和取值范围为依据裁定，裁定结论写入映射表的转换规则列并注明日期。状态、优先级、负责人这类影响业务判断的字段，建议在试迁移前完成对照表评审，减少正式增量阶段反复修改映射。
增量迁移过程中目标端写入被校验拦截，应该先改映射还是先改目标端配置？
先看拦截原因。如果是必填字段缺失或字段类型不匹配，属于目标端对象配置问题，由目标端配置负责人补齐字段或调整类型；如果是枚举值无对应项，属于映射问题，由映射表维护人补充对照关系。两类问题在差异清单中分开记录，处理完成后重跑受影响批次。试迁移阶段暴露这类拦截的成本低于正式增量阶段，因此建议在试迁移时就把目标端校验规则跑一遍。
增量迁移切换到正式运行后，还需要保留哪些记录？
正式增量按批次执行时，每批保留与试迁移相同的证据材料：批次号与时间窗口、水位值、写入条数、差异清单及处理结论。这些记录与范围清单、映射表、停止与回退判断清单一并归档，形成可追溯的迁移日志。后续排查某条数据为何未同步或重复写入时，可以按批次号和水位时间定位到具体执行记录。
