研发历史记录遗漏通常发生在迁移的盘点与映射环节：评论、附件、状态变更、关联关系等信息分散保存在源系统中，导出时未被纳入范围，或在字段映射时被归并、截断。本文按盘点、映射、试迁移、核验、回退五个环节给出可执行方法，帮助负责研发数据迁移的团队定位遗漏位置并保留可复核的证据。
要点总览（TL;DR）
- 研发历史记录遗漏多发生在盘点与导出阶段：评论、状态流转、字段变更、附件、关联关系等附属内容未进入导出集，或在字段映射时被归并、截断。
- 盘点按对象类型逐类统计载体与数量，并写明迁移的项目、工作项类型、时间范围和归档记录边界，为后续核验提供可比对基准。
- 字段映射先比对取值域与约束，同名不同义按语义拆分或合并并记录依据；无法对应的内容保留原值、转文本或单独存档。
- 正式迁移前用覆盖边界情况的样本做试迁移，逐条比对后回写映射表；迁移后按对象类型做总量核对，并对附属内容抽样比对，保留导出文件、映射表与比对结果。
- 回退条件在迁移前约定：关键对象总量差异超过阈值时停止切换，附属记录缺失比例无法解释时回退到试迁移阶段，回退时保留已导入数据与原始导出集。
迁移范围里，哪些内容算研发历史记录
盘点前先明确一个判断：研发历史记录的范围大于工单正文。一条工作项的正文只记录当前描述，真正承载研发过程的是围绕它产生的评论、状态流转、字段变更、附件、关联关系和操作人信息。迁移时如果只按正文导出，目标系统里会留下一条“看起来完整、实际缺少过程”的记录。
建议按对象类型建立载体盘点清单，逐类确认源系统中该类内容存放在哪里、以什么形式存在、能否被导出。下表可作为盘点起点，具体条目按实际源系统调整。
| 对象类型 | 需盘点的载体 | 盘点要点 |
|---|---|---|
| 工作项 | 标题、描述、富文本正文 | 富文本中的图片、表格、嵌入内容是否随正文导出 |
| 评论 | 评论文本、评论人、评论时间、评论内附件 | 评论是否在导出接口的默认范围内 |
| 状态流转 | 状态变更时间、变更前后状态、操作人 | 是否以独立记录保存，还是只保留当前状态 |
| 字段变更 | 字段修改历史、修改人、修改时间 | 变更历史是否可查询、可导出 |
| 附件 | 附件文件、文件名、上传人、上传时间 | 导出的是文件本体还是下载链接 |
| 关联关系 | 工作项之间的父子、依赖、关联链接 | 关联关系是否随单条记录导出，还是需要单独导出关系表 |
| 操作人 | 创建人、经办人、评论人、变更人 | 人员账号能否映射到目标系统的用户 |
同时要划定本次迁移的起止时间和对象边界：迁移哪些项目、哪些工作项类型、时间范围从何时到何时、已归档或已关闭的记录是否纳入。边界写清楚，盘点数量才有可比对的基准；边界模糊时，后续核验很难判断差异是遗漏还是范围外内容。
遗漏从哪里发生：盘点与导出阶段的常见缺口
历史记录遗漏多数不是迁移执行时突然发生的，而是在盘点和导出阶段就已经埋下。定位时按阶段逐项检查，比在目标系统里翻找更有效。
导出范围缺口
导出接口或导出模板通常以工作项主表为核心，评论、变更历史、附件等附属记录需要单独导出或显式勾选。如果直接使用默认模板，附属记录不会进入导出集。检查动作：对照盘点清单，逐类确认导出文件中是否包含对应数据，而不是只看工作项条数是否一致。
分页、时间窗与权限过滤
大批量导出常按分页拉取，分页参数设置不当会造成重复或漏页；按时间窗导出时，边界时间点的记录容易被前后两个窗口同时排除；导出账号的权限范围小于实际数据范围时，部分项目或字段会被静默过滤。检查动作：记录导出时的分页参数、时间窗起止和账号权限范围，并用源系统的查询总数与导出条数做一次对账。
附件与富文本丢失
附件在导出时可能只保留链接，链接在源系统停用后失效；富文本中的图片、嵌入表格在转换为纯文本或简化格式时被丢弃。检查动作：抽取含多附件和复杂富文本的记录，确认导出结果中附件是文件本体、富文本结构是否保留。
| 阶段 | 风险点 | 检查动作 |
|---|---|---|
| 盘点 | 只统计工作项条数，未统计评论、变更、附件数量 | 按对象类型分别统计源系统数量 |
| 导出 | 默认模板不含附属记录 | 核对导出文件字段与盘点清单 |
| 导出 | 分页重复或漏页 | 记录分页参数，与查询总数对账 |
| 导出 | 时间窗边界记录被排除 | 检查边界时间点记录是否在导出集中 |
| 导出 | 权限过滤导致部分数据缺失 | 确认导出账号权限覆盖迁移范围 |
| 导出 | 附件仅保留链接、富文本结构丢失 | 抽样检查多附件与复杂正文记录 |
同名字段含义不同时的映射方法
字段映射的目标是让源字段中的信息在目标系统中仍有明确去处。同名不同义是最容易造成历史信息被错误归并的情况，例如源系统的“状态”包含自定义流程节点，目标系统的“状态”只有固定的几个枚举值；源系统的“优先级”是五级，目标系统是三级。处理这类字段，先比对再决定，不按字段名直接对应。
映射判定步骤
- 比对取值域：列出源字段与目标字段的全部取值，确认枚举项数量、含义和顺序是否一致。
- 比对约束：确认目标字段是否必填、是否有长度限制、是否只接受特定格式。
- 判定映射方式：取值域一致可直接对应；同名不同义按语义拆分到多个目标字段，或合并到语义更宽的目标字段，并记录判定依据。
- 处理无法对应的字段：确定保留原值、转为文本存入描述或备注、单独存档三种方式之一，不默认丢弃。
对于状态流转和变更记录这类附属内容，映射规则要单独说明：状态值映射到目标枚举后，原始状态名称应作为文本保留在记录中，避免映射后无法还原源系统的实际状态。无法确认等价关系的内容，保留原始记录并标注来源字段，比强行归并更利于后续追溯。
字段映射表模板
| 源字段 | 目标字段 | 转换规则 | 无法对应时的处理 | 责任人 |
|---|---|---|---|---|
| 示例：issue_status | 工作项状态 | 按枚举对照表转换，原始值写入备注 | 保留原值并标注 | 数据迁移负责人 |
| 示例：priority | 优先级 | 五级映射为三级，映射表附后 | 转文本保留 | 业务字段负责人 |
| 示例：comment_body | 评论内容 | 富文本转目标格式，图片转附件 | 原文单独存档 | 内容迁移负责人 |
映射表要覆盖全部纳入迁移范围的字段，包括附属记录的字段，并由业务字段负责人确认语义判定。映射表本身是后续试迁移和核验的对照依据，版本需要固定，修改时记录变更原因。
在ONES的迁移实践中，从Jira迁移问题数据时涵盖属性和属性值、附件、评论等信息，迁移方案围绕项目、工作项、状态、字段、流程、附件和历史记录展开。这意味着映射工作可以直接以这些对象类型为清单逐类推进；具体字段的映射规则和无法对应内容的保留方式，仍需在迁移前按上述方法逐项确认。
试迁移：用小批量样本验证映射是否成立
正式迁移前用小批量样本跑一遍完整链路，目的是在数据量可控时暴露映射错误。样本选择要覆盖各对象类型和边界情况，而不是随机抽取正常记录。
- 每种工作项类型至少选取若干条，包含有评论、无评论、评论含附件的记录。
- 包含空值字段、超长文本字段、多附件记录、富文本含图片和表格的记录。
- 包含状态流转次数多、字段变更频繁的记录，验证变更历史的映射结果。
- 包含跨项目关联关系，验证关联关系在目标系统中的指向是否正确。
试迁移完成后逐条比对源记录与目标记录：正文内容是否一致、评论条数与内容是否对应、附件数量与文件是否可打开、状态流转记录是否完整、关联关系是否指向正确的工作项。发现的差异逐条记录，并回写映射表——差异属于映射规则问题的修改规则，属于导出范围问题的回到导出环节补数据。试迁移的差异记录要保留，作为正式迁移前的检查依据。
核验与证据：如何判断历史记录没有丢
完整性核验分两层：总量核对回答“数量对不对”，抽样比对回答“内容对不对”。两层都通过，才能认为该类历史记录迁移完整。
总量核对
按对象类型分别核对源导出条数与目标导入条数：工作项、评论、附件、状态流转记录、关联关系各做一次。差异要能解释，例如范围外记录、重复数据去重、权限过滤，无法解释的差异按遗漏处理。
抽样逐条比对
对评论、变更记录等附属内容，按对象类型和边界情况分层抽样，逐条比对内容、时间、操作人。抽样比例和抽样规则在迁移前约定，抽样结果记录在核验表中。
证据留存
- 源系统导出原始文件，保留导出时间、导出账号和导出参数。
- 字段映射表及版本变更记录。
- 试迁移差异记录与正式迁移的比对结果。
- 对确认无法迁移的内容形成书面说明，写明内容类型、数量、原因和处理方式。
| 核验对象 | 核验方式 | 通过标准 | 证据 |
|---|---|---|---|
| 工作项 | 总量核对 | 差异可解释 | 导出文件、导入统计 |
| 评论 | 总量核对加抽样比对 | 条数一致，抽样内容一致 | 抽样比对记录 |
| 附件 | 总量核对加文件可打开检查 | 数量一致，文件可访问 | 附件清单 |
| 状态流转与变更记录 | 抽样比对 | 关键节点完整，原始值可追溯 | 比对记录 |
| 关联关系 | 抽样比对 | 指向正确 | 关系对照表 |
ONES迁移方案把数据完整、业务连续和系统稳定作为迁移目标，并建议在正式迁移前确认数据范围、功能匹配和系统适配。核验记录正是确认数据范围的依据，迁移前约定的核验口径应与实际执行保持一致。
回退与停止条件
回退条件需要在迁移开始前约定，而不是发现问题后再讨论。以下条件可作为约定起点，阈值按项目规模和业务影响确定。
- 关键对象总量差异超过约定阈值时，停止切换，回到导出与映射环节排查。
- 附属记录缺失比例无法解释时，回退到试迁移阶段，用样本重新验证映射规则。
- 附件不可访问或富文本结构大面积丢失时，暂停正式迁移，先解决导出格式问题。
回退操作要保留现场：已导入的数据不删除，原始导出集和映射表保持可访问，差异记录完整保留。这样重新映射后可以只补导差异部分，避免全量重跑。回退完成后，更新映射表和核验记录，再决定是否重新进入正式迁移。
常见问题
源系统里只保留了当前状态，查不到状态变更历史，这类记录迁移时怎么处理？
先确认源系统是否真的没有保存变更历史，还是导出接口未开放该数据。若源系统本身只保留当前状态，迁移时能带走的是当前状态值和最后变更时间，历史流转过程无法还原。这种情况下应在书面说明中记录：该类记录在源系统不存在可导出的变更历史，目标系统只保留当前状态，并标注数据来源。核验时把这类记录从“变更记录完整性”的核对范围中单列，避免与遗漏混为一谈。
迁移范围里包含已归档项目，但归档数据导出受限，是否应该纳入本次迁移？
是否纳入取决于业务对历史追溯的要求和导出可行性。如果归档项目仍需支持查询和审计，建议纳入，并在盘点阶段单独统计其工作项、评论和附件数量；如果导出接口对归档数据有限制，先确认限制的具体表现（无法导出、只能导出部分字段、附件不可下载），再决定是分批导出还是转为离线存档。无论哪种选择，都要在迁移范围说明中写明归档项目的处理方式，核验时按同一口径核对，避免把范围外内容算作遗漏。
评论里的图片和富文本表格在目标系统中格式不同，算不算历史记录丢失？
判断标准是信息内容是否可获取，而非格式是否完全一致。图片转为附件、表格转为目标系统支持的表格结构，内容仍可查看，属于格式转换；图片只保留失效链接、表格结构被压成纯文本导致行列关系丢失，则属于内容丢失。试迁移阶段应专门抽取含图片和表格的评论记录，确认转换后的可读性，并把转换规则写入映射表。对无法保真的内容，保留原始导出文件作为存档，并在核验记录中说明转换方式。
总量核对时源系统条数和目标系统条数对不上，但差异在阈值内，还需要继续排查吗？
需要。阈值内只表示可以继续推进切换，不表示差异可以忽略。每一处差异都应归入可解释类别：范围外记录、重复数据去重、权限过滤、格式转换产生的拆分记录等，并留下对应证据。无法归类的差异即使数量很小，也应按遗漏处理，回到导出或映射环节定位。核验记录中建议逐条列出差异原因和证据位置，便于后续审计时复核。
试迁移发现映射规则有误，修改映射表后需要重新跑全部样本吗？
建议重跑受影响的样本，并补充与原错误相关的边界样本。映射规则修改会影响所有使用该规则的记录，只重跑发现错误的那几条不足以确认修复范围。实际操作中可先重跑该字段涉及的全部样本，确认转换结果一致后，再对未受影响的样本做抽查。映射表的每次修改都要记录变更原因和修改人，试迁移差异记录同步更新，正式迁移以最新版本映射表为准。
