源字段与目标字段类型不一致时，映射报错往往集中在少数几类：字符串与数值或日期互转失败、枚举值在目标字段中不存在、必填字段迁移后为空、超长内容或数值精度被截断。排查时先取一条失败记录，对照源值与目标字段定义确认差异类别，再用小样本试迁移验证转换规则，最后按类别统一处置并做回归验证。
要点总览（TL;DR）
- 类型不一致的映射问题先按症状归类：字符串与数值或日期互转失败、枚举值不在目标选项内、必填字段为空、超长或精度被截断。
- 排查从一条失败记录入手，对照源值、目标字段定义和报错信息判断差异类别，再用三到五条最小样本试迁移验证假设。
- 处置按类别分开：数值与日期统一格式、枚举建立映射表并单列未匹配值、必填字段补齐来源或设明确默认值、超长内容截断并保留原文备份。
- 批量修改前备份源数据与目标环境并设定停止点，处置后抽样比对记录数与关键字段值，重点检查边界值。
- 把校验规则和字段定义核对清单固化到迁移流程中，让类型不一致问题在写入前暴露。
类型不一致的映射问题有哪些典型症状
类型不一致并不总是以“类型错误”的字样出现。迁移工具、导入脚本或中间转换层可能给出不同的提示，甚至静默写入一条看起来正常、实际含义已经变化的数据。把症状先归类，能让后续排查有明确的入口，避免在大量报错中逐条猜测。
常见的可观察症状可以归为以下几类：
| 症状类别 | 典型表现 | 需要留意的细节 |
|---|---|---|
| 字符串与数值互转失败 | 导入报错提示格式无效；数值字段出现空值；带千分位、单位或货币符号的值无法写入 | 源值可能是“12,000”“3.5万”这类带格式文本，目标字段只接受纯数字 |
| 字符串与日期互转失败 | 日期字段为空或写入异常日期；时区偏移导致日期差一天；时间戳被当作普通数字 | 源系统使用本地时间、目标系统使用 UTC，或格式为“2024/01/05”而目标要求“2024-01-05” |
| 枚举或选项值不存在 | 下拉字段为空；报错提示选项无效；值被写入但显示为未分类 | 源选项名称与目标选项名称存在同义不同名，如“处理中”与“进行中” |
| 必填字段迁移后为空 | 记录创建失败；记录写入但关键字段缺失；批量任务在部分记录处中断 | 源字段本身允许为空，目标字段设为必填，或源字段未包含在映射配置中 |
| 超长文本或精度被截断 | 描述内容末尾缺失；数值小数位减少；编号被截断后出现重复 | 截断可能不报错，需要在迁移后抽样比对才能发现 |
需要与流程和插件行为问题区分开。若报错指向状态流转不允许、触发器执行失败或插件未安装，这类问题属于流程配置或扩展行为范畴，与字段值本身的类型约束无关。判断方法很简单：看报错是否指向某个具体字段的值，以及把该字段从映射中移除后错误是否消失。若错误随字段值变化而出现，优先按类型不一致处理；若错误随状态或动作变化而出现，应转入流程与插件方向排查。
逐类排查：从一条失败记录定位差异
排查的起点是一条具体的失败记录，而非全部失败数据。单条记录能提供完整的源值、目标字段定义和报错信息，便于把假设收敛为可验证的结论。
建议按以下顺序推进，每一步都留下证据：
- 取失败记录并记录源值。从迁移日志或失败清单中选一条报错明确的记录，复制源字段的原始值，包括前后空格、单位符号和格式。原始值比界面上显示的值更能说明问题。
- 对照目标字段定义。确认目标字段的数据类型、是否必填、长度上限、小数位精度、选项列表和日期格式要求。字段定义是判断差异类别的基准。
- 判断差异类别。源值是文本而目标要求数值，属于类型差异；源值在目标选项列表中找不到对应项，属于枚举差异；源值为空而目标必填，属于必填差异；源值长度或精度超过目标限制，属于长度与精度差异。一条记录可能同时命中多类，按报错最先触发的那一类处理。
- 用最小样本试迁移验证假设。构造三到五条记录，覆盖正常值、边界值和失败值，在测试环境执行迁移。若失败值复现报错、正常值通过，说明假设成立；若正常值也失败，说明问题可能出在映射配置或字段对应关系上，需要回到配置层检查。
- 记录结论与证据。把源值、目标字段定义、试迁移结果和最终判断写在一起，作为后续批量处置的依据。
排查中有两类常见误判。第一类是把含义不同当成类型问题：两个字段都是文本类型，但一个存的是客户名称、另一个存的是客户编号，写入不会报错，数据却失去了业务含义。这类问题靠类型检查发现不了，需要核对字段语义和取值样例。第二类是把流程问题当成映射问题：记录写入失败是因为目标状态在当前工作流中不可达，与字段值无关。遇到这类情况，先确认记录是否已成功创建、失败发生在写入阶段还是后续流转阶段。
按差异类别处置：转换、映射表、默认值与截断
确认差异类别后，处置方式按类别分开执行。批量操作前先备份源数据与目标环境，并在小批量验证通过后设定停止点，确认无误再扩大范围。
| 差异类别 | 处置方式 | 适用条件 | 风险提示 |
|---|---|---|---|
| 数值格式不一致 | 清洗源值：去除千分位、单位符号和空格，统一小数点；必要时按汇率或单位换算规则转换 | 源值为带格式文本，目标字段为数值型 | 换算规则需业务确认，四舍五入可能改变金额或工时口径 |
| 日期格式不一致 | 统一为 ISO 格式或目标要求的格式；明确时区并统一换算 | 源系统与目标系统日期格式或时区不同 | 跨时区换算可能使日期偏移一天，需用边界日期验证 |
| 枚举值不匹配 | 建立源选项到目标选项的映射表；未匹配值单独列出，人工确认后再补充映射 | 源选项与目标选项名称或数量不一致 | 未匹配值若直接置空，会丢失原状态信息；映射表需版本化管理 |
| 必填字段为空 | 从其他源字段补齐，或设置明确的默认值；无法补齐的记录单独标记 | 源字段允许为空而目标字段必填 | 默认值会掩盖数据缺失，需在迁移报告中列出被填充的记录 |
| 超长文本 | 按目标长度截断并保留原文备份，或拆分到扩展字段、附件 | 源文本长度超过目标字段上限 | 截断可能丢失关键信息，拆分后需保证可追溯 |
| 数值精度超限 | 按目标精度四舍五入或截位，并记录调整前后的值 | 源数值小数位多于目标字段允许位数 | 精度调整影响统计口径，需与数据使用方确认 |
枚举映射表是处置中最需要业务参与的部分。建议把映射表做成三列：源值、目标值、备注，未匹配的源值保留空目标值并标注待确认。这样既能让已确认的值先迁移，也能让未匹配项在迁移报告中集中暴露，避免被静默丢弃。
必填字段的默认值要谨慎使用。默认值适合那些业务上确实存在兜底含义的字段，例如优先级默认为“中”；对于负责人、截止日期这类字段，默认值可能让后续统计失真，更合适的做法是把缺失记录单独导出，补齐后再迁移。
在研发数据迁移场景中，ONES 的 Jira 迁移方案覆盖项目、工作项、状态、字段、附件和历史记录，并迁移问题数据中的属性和属性值。字段配置迁移与属性值迁移是两件事，源字段与目标字段的类型差异仍需在迁移配置和试迁移中逐项核对。排查阶段可以把失败记录、字段对照关系和处置结论记录在工作项或迁移记录文档中，让每条差异都有对应的处理状态和负责人，便于批量处置时按状态推进。
验证恢复与复发预防
处置完成后，先确认数据已经正确写入，再确认同类问题不会在下一批迁移中重复出现。验证分两层：数据层比对和规则层固化。
数据层验证建议包含以下动作：
- 比对迁移前后的记录总数，确认没有记录在批量处置中丢失或重复创建。
- 按字段抽样比对关键值，覆盖数值、日期、枚举、必填和长文本各至少若干条，重点检查边界值，如最大长度、最小日期、精度末位。
- 对截断和默认值填充的记录单独抽查，确认原文备份可查、填充值有业务依据。
- 检查枚举字段的分布，确认未匹配值没有以空值形式混入正常数据。
规则层验证是把这次排查中形成的判断固化为可重复执行的检查。可以为每类差异建立校验规则，例如数值字段不允许非数字字符、日期字段必须符合指定格式、枚举字段取值必须落在目标选项列表内、必填字段不允许为空、文本长度不超过上限。把这些规则写成预检脚本或迁移前的检查清单，在下一批数据导入前先跑一遍，能在写入前暴露大部分类型不一致问题。
映射配置需要文档化并保留变更记录。文档至少包含源字段、目标字段、数据类型、转换规则、枚举映射表版本和负责人。每次调整映射关系时记录变更原因和影响范围，避免多人维护时规则相互覆盖。
下次迁移前可以按以下清单核对字段定义：
- 源字段与目标字段的数据类型是否逐一对应，是否存在文本与数值、文本与日期的跨类型映射。
- 目标字段的必填要求是否已确认，源数据中对应字段的空值比例是否可接受。
- 枚举字段的选项列表是否已比对，映射表是否覆盖全部源选项。
- 文本长度和数值精度上限是否已核对，超限数据的处置方式是否确定。
- 日期格式与时区规则是否统一，边界日期是否已试迁移验证。
- 预检规则是否已更新，试迁移样本是否覆盖本次新增的差异类别。
把这套核对清单和预检规则纳入迁移流程的固定环节，类型不一致问题会从“迁移后救火”转为“迁移前拦截”，排查成本也会随着映射配置的积累而下降。
常见问题
源字段和目标字段都是文本类型，迁移没有报错，还需要排查吗？
需要。两个字段同为文本类型时，写入通常不会触发类型错误，但字段含义可能不同，例如一个存客户名称、另一个存客户编号。这类问题靠类型检查发现不了，排查时要核对字段语义和取值样例，抽取若干条记录比对源值与目标值是否表达同一业务含义。若含义不一致，应按字段映射关系重新配置，而不是当作类型问题处理。
试迁移时正常值也失败了，说明什么？
正常值失败通常说明问题不在单个值的格式，而在映射配置或字段对应关系上。此时应回到配置层检查：源字段是否映射到了正确的目标字段、目标字段是否必填但未提供来源、转换规则是否被错误应用。建议先固定一条已知正常的记录反复试迁移，确认配置修正后再扩大样本。
枚举值未匹配时直接置空可以吗？
直接置空会丢失原状态信息，迁移后难以区分“原本为空”和“因未匹配被置空”两种情况。更稳妥的做法是建立源值到目标值的映射表，未匹配的源值保留空目标值并标注待确认，在迁移报告中集中列出，由业务确认后再补充映射。映射表建议版本化管理，便于追溯每次调整。
必填字段用默认值填充有什么风险？
默认值适合业务上确实存在兜底含义的字段，例如优先级默认为“中”。对于负责人、截止日期这类字段，默认值会让后续统计失真，更合适的做法是把缺失记录单独导出，补齐后再迁移。无论采用哪种方式，都应在迁移报告中列出被填充的记录，便于事后核查。
ONES 迁移时字段类型差异会自动转换吗？
ONES 的 Jira 迁移方案覆盖项目、工作项、状态、字段、附件和历史记录，并迁移问题数据中的属性和属性值；字段配置迁移与属性值迁移是两件事。源字段与目标字段的类型差异仍需在迁移配置和试迁移中逐项核对，具体转换规则以实际迁移工具配置为准。
