开源项目管理软件的数据迁移：从旧系统搬进来要过的四道关

迁移上线后的第一个周一，常见三类问题同时出现：需求与任务的关联断了，附件能显示文件名却下载失败，工时总数正确但按项目拆分后对不上。

问题通常不在导入脚本，而在迁移设计。字段语义、状态机和停写窗口没有提前定义，导出再导入只会复制旧系统的问题。

数据迁入开源项目管理软件要过四道关：定范围与基线，做映射与清洗，试迁并校验，控制切换与回退。前一关的产出，就是后一关的输入。

一、迁移范围界定：明确对象边界与数据基线

1. 迁移范围：按业务对象与关联关系界定

范围不能按数据库表划分。业务人员使用的是对象：组织与用户、项目集、项目、执行、需求、任务、Bug、用例、发布、评论、附件、工时和权限角色。逐项列出对象，标注数量、关联对象和最后更新时间。

判断是否迁入只看三条：当前是否在用，审计或合同是否要求可查，关联关系是否必须保留。三条都不成立的进入只读归档；有一条成立就不能直接丢弃。范围清单写明迁移、归档、丢弃三种处置，并落实到验收人。

范围清单用于冻结边界。 试迁后再新增对象，映射表、校验样本和工期都要重算。环境与回退安排可对照迁移前准备清单核对。

2. 迁移基线：用六维指标评估源数据质量

GB/T36344-2018《信息技术 数据质量评价指标》定义了规范性、完整性、准确性、一致性、时效性和可访问性六个维度，标准于2019年1月1日实施。

落到项目管理数据，逐项检查：状态值与日期格式是否合法，负责人和附件是否缺失，工时与明细是否一致，需求、任务、Bug关联是否双向存在，更新时间是否可信，历史附件能否打开。

每类核心对象抽100条以上，统计空值率、重复率、孤儿记录率和附件缺失率，形成基线报告。源数据问题迁移前修，映射错误试迁时修，两类问题不能混。

二、数据映射设计：建立字段转换与清洗规则

范围回答迁什么，映射回答怎么迁。映射表必须写到值一级。

1. 字段映射：统一字段类型、状态机与枚举值

映射表至少五列：源字段、目标字段、转换规则、责任人、例外处理。类型、长度、必填和默认值写清，枚举值逐项对应。

需求和Bug的状态机是重点。旧系统的已解决、已验证、已关闭、重新打开，在目标系统中未必一一对应。目标系统只有完成和关闭两个终态时，需业务方确认哪些合并、哪些保留为自定义状态。合并错了，修复验证记录失真，质量报表失去可比性。

映射表需经业务评审，状态语义由业务定义。

2. 主体映射：用户身份、角色权限与附件存储

用户映射不能以姓名为主键，重名、离职、跨部门调动都会让负责人错位。改用邮箱或工号，离职账号迁为禁用状态，保留历史归属。角色按最小权限映射。

附件核对数量、大小、文件名编码和存储路径，迁移后按哈希抽验。内嵌图片从正文剥离，正文链接重新指向新地址。正文按目标编辑器规则转换，不直接搬运HTML。附件要能打开、能下载、内容一致。

3. 清洗导入：规则留痕与依赖顺序编排

清洗按去重、补全、标准化执行。去重先判定主记录，再合并评论、附件和关联。补全区分空值与未知。标准化统一日期格式、枚举大小写和文件名编码。

每步写清洗日志，记录原值、新值、规则和操作人。无法修复的记录放入异常表，不阻断整批导入。

导入按依赖排：用户、项目、需求、任务与Bug、用例与执行、评论附件、工时、关联、权限。每批带唯一业务键，重复导入执行更新而非新增。验收标准是关联不断裂、重复记录为0。 字符集差异通常在这一步暴露，字段与编码兼容可提前排除。

映射表、清洗日志和导入批次完成后，才进入验证。

三、迁移验证：通过试迁与分层校验确认可用

映射规则是否成立，只能用真实数据检验。试迁用于提前暴露错误。

1. 试迁设计：样本选择与两轮验证

样本不要挑最干净的。选跨项目关联多、附件多、状态复杂、有离职用户和自定义字段的项目，至少跑两轮。

第一轮暴露映射和格式问题，第二轮验证修正。记录导入成功率、字段截断数、附件缺失数、关联断裂数和单批耗时。问题回到映射表和脚本修正，不要手工补，手工补的数据没有规则。

图1展示选样本、冻结快照、导入、校验、修正映射、再次试迁的闭环。

2. 校验标准：总量、明细、关联与业务四层

总条数一致只说明没有整批丢失。校验分四层执行。

图2展示校验从数据层推进到业务层的顺序。前两层解决数据是否正确，后两层解决业务是否可用。结果由业务负责人确认，具体动作可对照导入与校验步骤。

3. 差异处置：归因分类与返工范围控制

差异先归因，不要直接重导。口径差异先统一完成率、工时和Bug状态定义；迁移缺陷回到映射表和脚本；源数据问题按清洗规则处理并留痕。

把源数据问题当成系统缺陷，只会反复重导、始终对不上。

图3对应统一口径、修正映射和清洗留痕三种处置。四层校验通过并形成书面放行结论后，才具备切换条件。

四、系统切换：控制停写窗口与回退风险

验证通过后，切换才进入执行阶段。目标是让切换可控，出问题能退回。

1. 停写切换：窗口控制与增量数据合并

切换前冻结旧系统写入，导出最后一次增量，按业务键和时间戳合并到新系统。窗口内新增事项用登记表收集，切换后补录。

需要并行时，旧系统只读、新系统主写。双轨并行必须单向写入，两套都可写会产生第二份不一致。

2. 回退保障：触发条件与恢复演练

回退预案写清触发条件、执行动作、决策人和时间窗口。触发条件要可判定，例如核心对象缺失超阈值、核心流程阻断、附件大面积不可访问、权限越权。

动作包括停止新系统写入、恢复旧系统为主、增量回灌并通知团队。备份不等于可回退，恢复演练才算。 切换前至少恢复一次旧系统，确认备份可用、恢复时长可接受。风险台账可参照数据迁移风险。

3. 上线复核：数据抽检与旧系统归档

上线30天后复核孤儿记录、重复记录、附件可访问性、权限越权和报表口径。旧系统归档要只读可查、附件能打开，不能只拷走数据库文件。

五、常见问题

1. 迭代进行到一半时切换系统，剩余工时怎么处理？

先在旧系统记录当前剩余工时，切换后按任务写入新系统。已完成与剩余工时不要合并成一个字段，迭代起止日期一并保留，燃尽图才有可比性。

2. 历史操作日志和字段变更记录需要迁移吗？

通常不全量迁移。日志量大、格式差异明显。保留关键对象的最后修改时间和修改人；审计要求高的项目单独归档并保留检索入口。

3. 迁移后的项目编号可以沿用旧编号吗？

可以。旧编号写入外部编号或自定义字段，不要占用自增主键，文档、合同和报表的历史引用才不会断裂。

4. 迁移后用户登录名和密码怎么处理？

账号可沿用旧登录名或改为邮箱，密码一般无法迁移。常见做法是首次登录强制重置，或接入统一身份认证。