研发数据迁移与映射的核心，是先确定来源系统、目标系统和迁移对象范围，再为每个对象建立字段级映射表，明确同名字段的真实含义、值域、必填性和关联关系。执行时按“盘点—映射—试迁移—核验—切换”推进，用样本数据验证映射结果，并为无法自动映射的字段设定人工处理规则和回退点。映射表、差异清单与核验记录可以在ONES文档与工作项中沉淀和流转。
要点总览（TL;DR）
- 先划清来源系统、目标系统与纳入迁移的对象清单，把工作流配置、插件行为、权限策略列为排除项，避免范围在执行中反复扩大。
- 映射的基本单位是字段：每个对象建一张字段映射表，逐行写明源字段、目标字段、类型、值域、转换规则和必填性，枚举值另建对照表。
- 同名不同义以业务定义为准，由字段确认人裁定；无法映射的字段逐项选定丢弃并记录、落到备注或人工补录，并写明理由。
- 试迁移按用户与组织→基础字典→工作项→关联关系→附件的顺序执行，样本覆盖各对象类型、各状态及含附件与关联的记录，问题回写映射表形成修订版。
- 核验按数量、字段、关联三层进行，留存核验记录表、差异清单与确认签字；关键字段大面积失败、关联断裂或账号缺失时暂停当前批次并评估回退。
迁移范围怎么划：来源、目标与对象清单
迁移范围决定后续映射表要建多少行、试迁移要跑多少批。范围不清，字段映射就会在“这个字段要不要迁”“这条记录算不算研发数据”上反复返工。范围清单至少要写清三件事：从哪个系统迁到哪个系统、两个系统各自的版本与部署形态、哪些数据对象纳入本次迁移。
来源系统与目标系统的版本和部署形态需要先记录。版本影响字段清单的导出方式和可用字段，部署形态（本地部署或云端）影响数据导出通道、附件获取方式和迁移窗口的协商对象。这些信息写在范围清单首页，后续映射和试迁移都以此为准。
纳入迁移的数据对象通常包括：工作项、需求、缺陷、迭代、版本、附件、评论、用户与组织。每个对象要标注预计记录数、是否含附件、是否含跨对象关联。对象清单建议按“对象—记录数—关联对象—负责人”四列组织，便于划分批次。
明确排除项同样重要。工作流配置、插件行为、权限策略等属于相邻主题，不在本次数据迁移范围内，应在清单中单独列出并注明“另行处理”，避免执行阶段被临时拉进来扩大工作量。排除项写清楚，也能防止业务方误以为迁移后流程行为会原样保留。
对象数量决定批次划分。记录量大的对象（如工作项、评论）可按时间区间或项目分批；用户与组织、基础字典这类体量小但被广泛引用的对象应放在首批。批次划分结果直接作为试迁移和全量迁移的执行顺序依据。
| 清单项 | 记录内容 | 示例填写 |
|---|---|---|
| 来源系统 | 名称、版本、部署形态 | 来源A系统，版本待确认，本地部署 |
| 目标系统 | 名称、版本、部署形态 | 目标B系统，版本待确认，云端 |
| 纳入对象 | 对象名、记录数、关联、负责人 | 缺陷，约1.2万条，含附件与关联需求 |
| 排除项 | 项目与处理去向 | 工作流配置、插件行为、权限策略，另行处理 |
| 批次 | 批次号、对象、时间区间 | 批次1：用户与组织；批次2：需求与迭代 |
映射前要准备哪些输入与依赖
字段映射不是对着两个系统的界面猜字段，而是基于双方字段清单和数据字典做逐项比对。准备工作做得越完整，映射表返工越少。以下输入应在建表前齐备，并指定责任人。
- 来源系统字段清单与数据字典：导出每个对象的全部字段，包含字段名、类型、长度、是否必填、值域说明。枚举字段要附上全部可选值及其中文含义。
- 目标系统字段定义与必填约束：目标对象的字段清单、必填项、类型限制、值域范围。必填约束决定哪些源字段必须有映射结果，否则记录无法创建。
- 用户与组织账号对应关系：来源账号与目标账号的对照表，包含离职账号、重名账号、外部协作账号的处理约定。账号对应不上，工作项的创建人和指派人在迁移后就会丢失归属。
- 附件存储与容量：附件总量、单文件大小上限、存储位置与访问方式，以及目标系统对附件容量和格式的限制。
- 迁移窗口与停机安排：可用的迁移时间段、期间来源系统是否只读、业务方能否接受停机，以及试迁移与全量迁移各自的时间预算。
- 字段含义确认人：每个业务对象指定一名确认人，负责裁定同名字段的真实含义和枚举值的对应关系。确认人名单与对象清单一并维护。
这些输入整理成一张“映射输入清单与责任人表”，每项标注提供方、完成状态和确认日期。输入未齐备的对象不进入映射阶段，避免用猜测填补空缺。
同名字段含义不同时怎么做字段映射
两个系统都有“状态”“优先级”这类字段，但取值和含义往往不同。映射的基本单位是字段，不是对象：每个对象建一张字段映射表，逐行写明源字段、目标字段、类型、值域、转换规则和必填性。
| 源字段 | 目标字段 | 类型 | 值域/转换规则 | 必填 |
|---|---|---|---|---|
| 状态（来源枚举） | 状态（目标枚举） | 枚举 | 按枚举对照表逐值映射 | 是 |
| 优先级（P0–P3） | 优先级（高/中/低） | 枚举 | P0、P1→高；P2→中；P3→低 | 是 |
| 描述（富文本） | 描述（富文本） | 文本 | 保留正文，图片转附件并记录原位置 | 否 |
| 自定义字段A | 无对应字段 | 文本 | 落入备注并标记来源字段名 | 否 |
同名不同义的处理以业务定义为准。先请字段确认人说明来源字段在业务上记录的是什么，再判断目标字段能否承载同一含义。含义相近但粒度不同的，考虑拆分或合并：例如来源的“类型”同时包含需求与任务，目标系统分设两个对象时，就按类型值分流到不同对象，而不是硬塞进一个字段。
状态、优先级、类型等枚举值要单独建值值对照表，列出源值、目标值、转换说明和未匹配时的处置。对照表要覆盖全部源值，包括历史遗留的废弃值。未在对照表中出现的值，试迁移时应报错而不是静默丢弃。
富文本、附件和关联关系的映射方式需要单独约定。富文本中的内嵌图片通常转为附件并在正文保留引用位置；附件按原文件名迁移并记录来源记录ID；父子关系、关联需求与缺陷等关联关系在记录迁移完成后按ID对照表重建，不能随记录一起直接写入。
无法映射的字段有三种处置方式，逐字段选定一种并记录理由：丢弃并记录（字段无业务价值，登记在差异清单）、落到备注（保留信息但不占目标字段）、人工补录（关键字段，迁移后由责任人补齐）。三种方式都要在映射表中标注，避免执行时临时决定。
试迁移怎么跑：样本选择与执行步骤
试迁移的目的是用少量数据验证映射规则，把问题暴露在全量之前。样本不在多，在于覆盖典型情况。选取原则是：覆盖每个纳入迁移的对象类型，覆盖各主要状态，包含带附件和带关联关系的记录，并纳入至少一条含无法映射字段的记录。
试迁移按依赖顺序执行，前一步的结果是后一步的输入：
- 用户与组织：先迁账号和组织结构，后续记录才能挂上创建人和指派关系。
- 基础字典：迁移状态、优先级、类型等枚举定义，确保记录写入时目标值已存在。
- 工作项：按对象逐类迁移记录主体字段，记录每类对象的成功与失败条数。
- 关联关系：依据ID对照表重建父子关系、关联需求与缺陷，逐条核对关联两端都存在。
- 附件：迁移附件并校验文件可访问、大小一致、与记录的挂接正确。
每一步记录耗时、成功条数、失败条数和失败原因。失败条目保留原始数据片段，便于定位是映射规则问题还是数据本身问题。试迁移结束后，把发现的问题回写到映射表：修正转换规则、补充枚举对照、调整无法映射字段的处置方式，形成映射表修订版。修订版是后续全量迁移的唯一依据。
核验与证据：怎么判断映射结果可用
核验回答一个问题：迁移后的数据能否支撑业务正常使用。核验按数量、字段、关联三个层面逐项进行，每项留下可复查的记录。
- 数量核验：各对象迁移前后条数比对，差异逐条说明原因（如排除项、重复记录合并、失败待补录）。数量一致不等于内容正确，但数量差异必须先解释清楚。
- 字段核验：按对象抽样比对关键字段值，重点检查枚举映射结果、必填字段完整性、富文本与附件的对应关系。抽样覆盖各状态和各批次。
- 关联核验：抽查父子关系、关联需求与缺陷的完整性，确认关联两端都存在且指向正确记录，没有出现指向不存在记录的悬空关联。
证据留存包括核验记录表、差异清单和确认签字。核验记录表按对象列出核验项、抽样量、通过数和差异数；差异清单逐条记录差异内容、原因、处置方式和责任人；确认签字由业务方确认人对核验结果签字，作为进入下一阶段的依据。核验记录与差异清单随映射表一起版本化保存。
回退与停止条件：什么情况下暂停迁移
迁移过程中出现以下情况应暂停并评估是否回退：关键字段大面积映射失败，导致记录无法创建或核心信息缺失；关联关系断裂比例超出可接受范围，父子关系或需求缺陷关联大量悬空；账号对应缺失，造成记录归属无法确定。这些属于阻断条件，触发后先停止当前批次，定位原因并修订映射规则，再决定重跑还是回退。
回退点设在三个阶段：试迁移结束后、全量迁移开始前、正式切换前。每个检查点核对映射表修订版、核验记录和差异清单是否齐备，未通过检查点不进入下一阶段。回退方式上，来源系统在迁移期间保持只读，确保数据可回溯；全量迁移按批次执行，某批次失败时只回滚该批次，不影响已通过核验的批次。
恢复迁移需要前置确认：阻断原因已定位并修复、映射表已更新、受影响的样本重新试迁移通过、业务方确认人书面同意继续。确认记录与核验证据一并归档，作为本次迁移的过程留痕。
映射过程中的协作与记录怎么落到工具里
字段映射和核验涉及多个角色反复确认，记录散落在聊天和表格里容易丢失版本。把这类管理动作放进工作项和文档，可以让确认过程有据可查。
映射表、枚举值对照表、差异清单作为文档沉淀，每次修订保留版本，修订说明写清改了哪条规则、依据是什么。待确认字段和试迁移失败条目登记为工作项，指派给字段确认人或对应模块负责人，工作项里附上原始数据片段和映射表行号，处理完成后关联回文档的对应版本。试迁移记录与核验结果作为评审材料留痕，评审结论和确认签字记录在文档中，后续切换阶段直接引用这些记录，不必重新收集。
ONES的文档与工作项可以承载上述流程：映射表在文档中版本化管理，待确认字段和失败条目以工作项流转并指派责任人，核验记录与评审结论随文档留存。这样映射规则、处理过程和核验证据集中在同一处，迁移各阶段的责任边界和确认结果都能追溯。
常见问题
来源系统里有些历史废弃的枚举值，映射时怎么处理？
枚举对照表要覆盖全部源值，包括历史遗留的废弃值，不能只列当前在用的取值。废弃值在对照表中单独标注，并选定处置方式：归并到某个现行目标值、落到备注，或按无法映射字段处理。试迁移时如果出现对照表中没有的值，应报错并记录，而不是静默丢弃，这样能及时发现对照表遗漏。
账号对应关系缺失时，能不能先迁记录、后补归属？
可以先迁记录主体，但创建人和指派人会暂时空缺，需要在差异清单中登记，并在核验阶段逐条确认补录。如果账号缺失比例较高，导致大量记录归属无法确定，就属于阻断条件，应先补齐账号对照表再继续。离职账号、重名账号和外部协作账号建议在映射阶段就定好统一规则，避免试迁移和全量迁移各用一套处理方式。
试迁移通过后，全量迁移还需要重新核验吗？
需要。试迁移验证的是映射规则，全量迁移验证的是规则在全部数据上的执行结果。全量阶段仍要按对象做数量比对，抽样检查字段值和关联完整性，并保留差异清单。试迁移的核验记录可以作为基线，用来对比全量结果是否出现新的偏差类型。
迁移期间来源系统要不要停机？
取决于迁移窗口和业务方对停机的接受程度。常见做法是迁移期间将来源系统设为只读，阻止新增和修改，保证迁移数据与来源一致；如果业务无法接受只读，则需要约定增量数据的处理方式，并在核验时说明数据截止时间。停机安排应在映射准备阶段就与业务方确认，写入迁移窗口计划。
映射表和核验记录用什么形式保存比较合适？
关键是可版本化、可追溯。映射表、枚举对照表和差异清单作为文档保存，每次修订保留版本并写明修改依据；待确认字段和失败条目登记为工作项，指派责任人并附上原始数据片段和映射表行号。核验记录与评审结论随文档归档，后续切换阶段直接引用，不必重新收集。ONES 的文档与工作项可以承载这类记录。
