迁移字段映射时，字段名相同并不代表可以直接对应。判断依据是业务含义、取值域和必填约束，字段名称只作线索。本文按“界定源与目标—备齐输入—建立三列映射表—处理四类冲突—抽样回放核验—设定停止与回退条件”的顺序，说明这一阶段具体怎么做、需要留下哪些证据。
要点总览（TL;DR）
- 字段映射的判断依据是业务含义、取值域和必填约束，字段名只作线索；先建“源字段—业务含义—目标字段”三列对照表，再逐字段确认。
- 同名字段含义不同时，比对取值域、示例值和使用场景，以业务含义为准重新指派目标字段，必要时改名或新建自定义字段。
- 一拆多、多合一和枚举值不一致要分别定规则与兜底：拆分依据可复现，合并定冲突优先级，枚举建取值对照表，无法映射的字段保留在备注或迁移清单中。
- 映射表写完后用样例数据在目标端测试环境做抽样回放，覆盖每个对象、每种枚举值、空值记录和边界记录，差异逐条记录并闭环。
- 映射阶段预设停止与回退条件：关键字段含义未确认、必填无兜底、枚举对照缺失时暂停；回放差异率超阈值或关联大面积断裂时退回上一版映射表。
迁移字段映射的范围：先界定源、目标与对象
字段映射开工前，先把范围写清楚，否则后续讨论“这个字段该不该迁”会反复拉扯。范围清单至少包含四项：源系统与目标系统及各自版本、纳入映射的数据对象、各对象的记录量级、明确排除的内容。
数据对象按业务实体逐项列出，例如需求、缺陷、任务、用例、迭代。每个对象标注记录量级，便于估算抽样规模和回放工作量。记录量级用导出时的实际条数，不用“大约几千条”这类模糊口径。
排除项要单独成行。工作流状态机、插件行为、权限配置通常与字段映射分开处理：状态机涉及流转规则，插件行为涉及定制逻辑，权限配置涉及角色与可见范围，它们和“某个字段的值迁到哪里”不是同一件事。把这些内容排除在本次映射之外，不等于它们不需要迁移，而是由相邻阶段单独负责。
迁移方向不可颠倒。源字段是输入，目标字段是输出，映射表按“源→目标”单向填写。反向填写容易在回放时把目标端的默认值误当成源端数据，造成核验结论失真。
| 范围项 | 填写内容 | 示例 |
|---|---|---|
| 源系统与版本 | 产品名、版本号、部署方式 | 源系统 A，版本待查证 |
| 目标系统与版本 | 产品名、版本号、部署方式 | 目标系统 B，版本待查证 |
| 纳入对象 | 实体名称、记录量级 | 需求 1.2 万条、缺陷 3.4 万条 |
| 排除项 | 内容与负责阶段 | 工作流状态机、插件行为、权限配置 |
范围清单定稿后由业务方与迁移负责人共同确认，作为后续映射表的第一页附件。
映射前要拿到哪些输入
字段映射最常见的返工原因是边迁边补：映射做到一半才发现源端某个字段的历史空值比例很高，或者目标端没有对应的自定义字段。开工前把输入凑齐，可以把这类问题前置。
需要齐备的输入包括：
- 源端字段清单：字段名、数据类型、是否必填、枚举取值全集、历史空值比例。空值比例决定该字段是否需要默认值兜底。
- 目标端字段清单与自定义字段能力：目标系统现有字段、可新建的自定义字段类型、字段是否必填、枚举值是否可扩展。
- 关键字段含义的口径确认人：每个业务含义有争议的字段，指定一名能拍板的人，避免多人各说各话。
- 样例数据导出与脱敏方式：从每个对象抽取样本，敏感信息按约定规则脱敏后再用于比对。
- 映射表的维护责任人与版本记录方式：谁改、改了什么、为什么改，都要能追溯。
把这些输入做成一张检查表，逐项标注“已具备、待补、责任人”，待补项清零后再进入映射表填写。输入齐备度检查表本身就是映射阶段的第一份证据。
建立三列映射表：字段名、业务含义、目标字段
映射表的基础结构是三列：源字段、业务含义、目标字段。实际使用时再加两列——转换规则和默认值，前者记录取值如何变化，后者记录源值为空时填什么。
| 源字段 | 业务含义 | 目标字段 | 转换规则 | 默认值 |
|---|---|---|---|---|
| 源字段名 | 该字段在业务上代表什么，谁在用 | 目标端承接该含义的字段 | 直接复制、拆分、合并、枚举对照等 | 源值为空时填入的值，无则留空 |
填写顺序建议先写“业务含义”，再找目标字段。按业务含义匹配，可以避免被字段名误导：源端的“优先级”可能表示业务紧急度，目标端的“优先级”可能表示处理顺序，两者同名但取值域和使用场景不同。
识别同名字段含义不同，用三个动作比对：一看取值域，源端是“高/中/低”，目标端是“P0–P3”，取值结构就不一致；二看示例值，抽几条真实记录对照；三看使用场景，谁在什么环节填这个字段、用来驱动什么动作。三项比对下来，含义是否一致基本能判断。
映射表还要区分必填与选填。目标端必填而源端选填的字段，必须在默认值列给出兜底；目标端选填而源端必填的字段，确认信息不丢失即可。每行标注维护人和最后修改日期，版本号写在表头。
四类典型映射情形的处理规则
映射表填到具体字段时，冲突集中在四类情形。每类都应有判断条件、处理动作和兜底方案，写进规则表后由团队统一执行。
| 情形 | 判断条件 | 处理动作 | 兜底方案 |
|---|---|---|---|
| 同名字段含义不同 | 字段名相同，取值域、示例值或使用场景不一致 | 以业务含义为准重新指派目标字段；必要时在目标端改名或新建自定义字段承接 | 暂无合适目标字段时，先落入备注字段并登记待建字段 |
| 一拆多 | 源端一个字段承载了目标端多个字段的信息 | 按取值规则拆分，拆分依据写入转换规则列 | 无法可靠拆分时整体保留在原字段，拆出的目标字段留空并记录 |
| 多合一 | 源端多个字段对应目标端一个字段 | 明确合并规则与冲突取值优先级，例如按来源字段顺序取第一个非空值 | 合并后丢失的信息逐条记入迁移清单，附原值 |
| 枚举值不一致 | 源端枚举取值在目标端不存在，或含义有偏移 | 建立取值对照表，逐值指定目标值 | 目标端不存在的枚举值，映射到最接近的合法值并在备注中保留原值 |
同名字段含义不同的处理要点是“改指向，不改数据”。例如源端“严重程度”实际用于标记客户影响范围，目标端“严重程度”用于缺陷修复排序，就应把源字段指向目标端的“客户影响”类字段，而不是硬塞进同名但含义不同的字段。
一拆多的拆分依据必须可复现。比如源端一个“环境信息”文本字段，按约定分隔符拆成“测试环境”和“生产环境”两个字段，分隔符规则、异常格式的处理方式都要写清楚。拆分结果无法保证时，宁可整体保留，也不要用猜测值填充。
多合一要提前定优先级。两个源字段都可能有值时，谁覆盖谁必须有明文规则，否则不同批次导入会得到不同结果。合并造成的信息丢失，逐条记录源值和处理结论，便于业务方事后追溯。
枚举对照表单独维护，一行一个源值，列出目标值和备注。目标端不存在的枚举值，选择最接近的合法值并在备注保留原值，不静默丢弃。无法映射的字段统一处置：保留在备注、附件或迁移清单中，清单注明字段名、原值、无法映射的原因。
用抽样回放核验映射结果
映射表写完不等于映射正确。用样例数据在目标端测试环境做一次回放，逐条比对源值与目标值，是发现规则漏洞最直接的方式。
抽样要覆盖四类记录：每个数据对象至少抽一批；每种枚举值至少出现一次；空值记录单独抽；边界记录包括超长文本、特殊字符、多值字段。样本量按对象记录量级确定，记录量大的对象适当增加样本。
回放方式是在目标端测试环境导入样例数据，按映射表逐字段比对。核验清单包括：字段值一致、必填字段不为空、枚举值落在合法取值内、关联关系未断。关联关系指记录之间的父子、关联、归属关系，断裂通常表现为子记录找不到父记录或归属对象为空。
| 源值 | 目标值 | 差异类型 | 处理结论 |
|---|---|---|---|
| 样例原值 | 回放后的值 | 值不一致、枚举越界、必填为空、关联断裂 | 修正映射规则、补默认值、调整对照表或确认可接受 |
差异记录表逐条填写，每条差异都要有处理结论，不能只记录不闭环。核验通过标准在回放前约定，例如关键字段零差异、非关键字段差异率低于约定阈值、关联关系无断裂。通过后由业务方确认人和迁移负责人签字，回放记录与差异清单随映射表一并归档。
映射表、差异记录和核验结论需要在团队内可查、可追溯版本。ONES 的文档与工作项协作能力可以承载这类过程材料：映射表作为文档留存版本，差异项作为工作项指派给责任人跟踪闭环，核验结论附在迁移记录中，便于切换前复核。具体字段级映射规则与兼容版本仍需在项目中逐项确认。
映射阶段的回退与停止条件
映射阶段需要预设暂停和退回的判断标准，避免带着未确认的规则进入导入环节。
停止条件指当前不能继续推进：关键字段的业务含义未确认、目标端必填字段没有兜底值、枚举对照表缺失或存在未处理的取值。出现任一项，映射工作暂停，由口径确认人给出结论后再继续。
回退条件指映射结果不可接受，需要退回上一版映射表：抽样回放差异率超出约定阈值、关联关系大面积断裂、多个对象出现同类错误。回退动作是回到上一版映射表，记录变更原因、变更人和影响范围，再重新回放。
切换前保留的证据包括：各版本映射表、枚举对照表、抽样回放记录、差异处理清单、停止与回退的判断记录。这些材料按版本归档，确保任何一次字段取值都能追溯到当时的映射规则。映射阶段结束的标志是核验通过并完成签字确认，此后进入试迁移或切换阶段，由相应流程接手。
常见问题
源端和目标端字段名完全一样，还需要逐字段核对吗？
需要。字段名相同只说明命名接近，不能证明业务含义一致。核对时至少比对三项：取值域结构是否相同，例如一端是“高/中/低”、另一端是“P0–P3”；抽几条真实记录看示例值；确认这个字段在什么环节由谁填写、用来驱动什么动作。三项中有一项对不上，就按同名字段含义不同处理，以业务含义为准重新指派目标字段。
源端一个字段的信息在目标端需要拆成多个字段，拆不准怎么办？
拆分规则必须可复现，分隔符、取值格式和异常情况的处理方式都要写进转换规则列。如果源数据格式混乱、无法可靠拆分，宁可整体保留在原字段或备注中，拆出的目标字段留空并记录原因，不要用猜测值填充。拆不准的部分进入迁移清单，由业务方决定后续人工补录还是接受信息保留在原位。
目标端不存在的枚举值，迁移时怎么处理才不算丢数据？
建立枚举对照表，一行一个源值，逐值指定目标值。目标端没有对应取值的，映射到最接近的合法值，同时在备注字段保留原值，并在对照表里注明“原值保留”。这样目标端字段值始终落在合法取值内，原始信息也能追溯。对照表随映射表一起归档，切换前可复核。
抽样回放要抽多少条、抽哪些记录才算够？
样本量按对象记录量级确定，记录量大的对象适当增加。覆盖面上，每个数据对象至少抽一批，每种枚举值至少出现一次，空值记录单独抽，边界记录包括超长文本、特殊字符和多值字段。回放时逐字段比对源值与目标值，同时检查必填字段不为空、枚举值合法、关联关系未断。核验通过标准在回放前约定，例如关键字段零差异、非关键字段差异率低于约定阈值。
映射做到一半发现关键字段含义有争议，应该继续还是暂停？
暂停。关键字段的业务含义未确认属于停止条件，继续推进只会把争议带进导入环节。由事先指定的口径确认人给出结论，更新映射表并记录变更原因和影响范围，再恢复回放。如果已经完成回放且差异率超出约定阈值，或关联关系大面积断裂，则退回上一版映射表重新处理，而不是在错误版本上继续修补。
