不同工具的状态机各自按本工具的流程设计，状态粒度、名称和中间态往往对不上，直接逐状态硬配容易在回退、重开和跨工具跳转时出错。处理状态映射表可以按“语义归并—映射规则—兜底状态—异常流转”四层推进：先把各工具状态归并成少量统一状态，再逐条写清目标状态与触发条件，无法对应的落到兜底状态并保留原值，最后单独定义异常路径并做双向核对。ONES 在工具链集成中承接工作项状态与流转管理，可作为映射落地的一侧参照。
要点总览（TL;DR）
- 先按业务语义把各工具状态归并成待处理、进行中、待验证、已完成、已关闭等少量统一状态，再逐条填写映射，避免按名称字面硬配。
- 映射表以源状态一行为单位，写清源工具、源状态、状态类别、目标状态、转换触发条件和是否兜底，一对多按触发条件拆行。
- 无法对应的状态落到语义最接近且不误导业务判断的兜底档，同时保留源状态原值，兜底行标注原因并设定复核周期。
- 回退、重开、跨工具跳转和同步冲突单独定义规则：正向同步可自动，回退默认人工确认，终态锁定、重开解冻并留痕。
- 上线前做源状态全覆盖核对、兜底复核检查和双向试运行，问题回写映射表后再确认可用。
先归并语义，再动手画映射表
状态机不一致通常来自三类差异。第一类是粒度不同：一侧把“开发中”拆成编码、自测、联调，另一侧只有一个“进行中”。第二类是名称相同、语义不同：两个工具都叫“已解决”，一个指开发完成待测试，另一个指测试通过待发布。第三类是一方有中间态、另一方没有，例如代码评审中、构建排队这类状态在需求管理工具里找不到对应位置。这些差异靠名称字面匹配解决不了，必须先回到业务含义。
归并的做法是按业务阶段划分统一状态集，常用五档：待处理、进行中、待验证、已完成、已关闭。归并时逐条回答“这个状态在业务上意味着工作项处于哪个阶段、下一步由谁接手”，把语义相同或相近的源状态收进同一档。例如 GitLab 合并请求的“已合并”、缺陷工具的“修复完成”、需求工具的“开发完成”，如果业务上都表示“等待测试验证”，就统一归入待验证。归并依据要写下来，形成统一状态集清单，作为映射表的基准列。后续所有映射行都指向这五档之一，映射表就不会随工具数量增加而失控。
归并结果需要业务侧确认，不能由集成实施方单方面决定。确认的完成标志是：每个源工具的每个状态都能在统一状态集中找到归属，找不到归属的状态被单独列出，进入兜底讨论。
状态映射表的字段与填写规则
映射表以“源状态一行”为基本单位，一行只描述一个源状态到目标状态的转换。建议的字段结构如下：
| 字段 | 填写规则 |
|---|---|
| 源工具 | 状态所在的工具名称，如 GitLab、SVN、缺陷管理工具、需求管理工具 |
| 源状态 | 工具中的原始状态值，照抄不改写 |
| 源状态类别 | 正常 / 终态 / 异常，用于区分常规流转与特殊处理 |
| 目标工具 | 接收状态同步的工具 |
| 目标状态 | 统一状态集中的一档，或目标工具的实际状态值 |
| 转换触发条件 | 写清由哪个事件或动作触发同步，如“合并请求合并后”“提交关联工作项时” |
| 是否兜底 | 是 / 否，兜底行需在备注中说明原因 |
| 备注 | 记录归并依据、保留的源状态原值、复核计划 |
填写时区分三种对应关系。一对一直接填目标状态；一对多表示一个源状态在目标侧可能落到不同状态，需要按触发条件拆成多行，每行写清分支条件；多对一表示多个源状态归入同一目标状态，每个源状态各占一行，目标状态相同。状态类别字段的作用是把正常流转与终态、异常态分开管理：终态行要标注是否锁定，异常行要关联异常流转规则，避免混在常规映射里被误改。
转换触发条件是最容易被写空的一列。只写“状态变化时同步”无法指导实施，应写到事件级别，例如“代码提交关联工作项且提交信息含修复关键字时，将工作项从进行中转为待验证”。条件写清楚，同步逻辑才有可配置的依据。
无法一一对应时怎么设兜底状态
归并后仍会有状态落不进统一状态集，典型如“构建排队中”“代码评审中”“已挂起”。兜底状态的选取原则是：选语义最接近且不会误导业务判断的一档。构建排队中更接近进行中而非待处理，就落到进行中；已挂起如果业务上表示暂停推进，可以落到进行中并在备注中标注挂起，避免被误读为已完成或已关闭。
兜底时必须保留源状态原值，写在备注或独立字段中。保留原值的用途有两个：一是回溯时能还原真实状态，二是人工修正时有依据。同步到目标侧的状态可以是归并后的档位，但源值不能丢。
兜底状态不宜过多。按工具和状态类别集中设置，同一工具内的多个中间态尽量共用一个兜底档，避免映射表膨胀成逐状态翻译。每一条兜底映射都要标注并设定复核周期，例如每季度复核一次，确认是否已有更精确的对应关系。长期不复核的兜底会沉淀为默认做法，掩盖真实的语义差异。
异常流转：回退、重开与跨工具跳转的处理
正常流转之外，回退、重开和跨工具跳转最容易造成状态回写错乱，需要单独定义规则。
| 异常场景 | 映射与同步规则 | 人工介入点 |
|---|---|---|
| 回退 | 目标侧从待验证退回进行中时，源侧是否同步回退需明确；默认只做正向同步、回退由人工确认，避免两侧反复拉锯 | 回退原因需记录，连续回退超过设定次数转人工核查 |
| 重开 | 已关闭工作项被重开，映射到进行中或待处理，并解除终态锁定；重开需保留原关闭时间与原状态 | 重开由责任人确认，防止误操作触发批量重开 |
| 跨工具跳转 | 源侧跳过中间态直接到终态时，目标侧按终态映射，中间态不补记；如需留痕，在备注中记录跳转路径 | 跳转涉及审批或质量门禁时，由对应角色补确认 |
| 同步失败或状态冲突 | 两侧状态不一致时以业务侧为准，冲突记录进入待处理队列，不自动覆盖 | 值班角色按队列处置，处置结果回写映射表备注 |
终态需要锁定与解冻规则。已完成、已关闭的工作项在目标侧锁定，禁止常规同步修改；只有重开动作能解冻，解冻需留下操作记录。跨工具跳转如果绕过了质量门禁，应在映射规则中要求补一次确认，而不是让状态直接落定。
角色分工与交付物
映射表从设计到运行涉及四类角色，职责和产出要分开写清，避免归并、配置和异常处置混在一个人身上。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 业务侧 | 状态语义归并、兜底判定、统一状态集确认 | 统一状态集清单及归并依据说明 |
| 集成实施方 | 映射表配置、同步规则落地、触发条件实现 | 已配置的状态映射表、同步规则说明 |
| 运维或值班角色 | 异常流转的发现、记录与处置 | 异常处置记录、冲突队列处理结果 |
| 映射表维护人 | 变更评审、版本记录、兜底复核组织 | 映射表版本记录、复核结论 |
映射表变更要走评审：新增或修改映射行由业务侧确认语义，实施方评估同步影响，维护人记录版本。版本记录至少包含变更行、变更原因、生效时间和确认人，便于出现状态错乱时定位到具体版本。
在工具链集成场景中，ONES 提供开放式的 DevOps 工具集成能力，可对接 GitLab、GitHub 等第三方应用，并通过 API 与企业系统打通数据；集成 Jenkins、GitLab CI 等流水线后，ONES 会同步流水线数据并更新执行状态和日志。这些能力承接的是状态与流转在管理侧的呈现，映射表本身仍需按上述四层方法设计，具体配置方式以实际产品为准。
一个跨工具状态映射的填写示例
以下示例仅作方法演示，不指向特定产品版本能力。假设需求类工作项在需求管理工具与代码平台之间同步，需求管理工具状态为：待评估、开发中、待测试、测试通过、已上线、已关闭；代码平台侧以合并请求和提交表达进度。
| 源工具 | 源状态 | 源状态类别 | 目标工具 | 目标状态 | 转换触发条件 | 是否兜底 | 备注 |
|---|---|---|---|---|---|---|---|
| 需求管理工具 | 待评估 | 正常 | 代码平台 | 待处理 | 工作项创建后同步 | 否 | — |
| 需求管理工具 | 开发中 | 正常 | 代码平台 | 进行中 | 拉取代码分支并关联工作项时 | 否 | — |
| 代码平台 | 合并请求已创建 | 正常 | 需求管理工具 | 开发中 | 合并请求创建并关联工作项时 | 否 | 多对一，与开发中共用目标状态 |
| 代码平台 | 合并请求已合并 | 正常 | 需求管理工具 | 待测试 | 合并请求合并后 | 否 | — |
| 代码平台 | 构建排队中 | 正常 | 需求管理工具 | 开发中 | 流水线任务进入队列时 | 是 | 保留原值“构建排队中”，语义最接近进行中 |
| 需求管理工具 | 测试通过 | 正常 | 代码平台 | 待发布 | 测试结论登记后 | 否 | 一对多：若存在灰度环境，另起一行映射到灰度中 |
| 需求管理工具 | 已上线 | 终态 | 代码平台 | 已完成 | 发布记录确认后 | 否 | 目标侧锁定 |
| 需求管理工具 | 已关闭 | 终态 | 代码平台 | 已关闭 | 关闭动作确认后 | 否 | 重开时解冻并映射到进行中 |
回退路径的写法单独列一行：目标侧从待测试退回开发中时，源侧合并请求状态不回写，由需求责任人手动确认后更新，备注中记录回退原因。这样正向同步自动执行，回退保留人工判断，避免两侧状态互相覆盖。
上线前的完成检查
映射表交付使用前，按以下清单逐项核对，每项都要有可查的记录。
- 源状态全覆盖：列出各工具全部状态，逐一核对映射表中是否有对应行，无遗漏、无重复行。
- 归并依据可追溯：统一状态集每一档都有归并说明，业务侧已确认。
- 兜底映射有标注：每条兜底行标明原因、保留的源状态原值和复核周期。
- 异常规则完整：回退、重开、跨工具跳转、同步冲突四类场景均有对应规则和人工介入点。
- 终态锁定明确：终态行的锁定与解冻条件已写入规则。
- 双向核对完成：从源到目标和从目标到源各做一次全量核对，确认无孤立状态。
- 试运行留档：选取若干真实工作项试运行，记录同步结果、异常处置和修正内容。
- 版本与责任人明确：映射表有版本号、维护人和变更评审记录。
试运行中发现的问题要回写到映射表并重新核对，直到源状态全覆盖、异常路径可处置、双向核对一致，映射表才具备上线条件。
常见问题
两个工具的状态名称完全一样，还需要做语义归并吗？
需要。名称相同不代表语义相同，例如两侧都叫“已解决”，一侧指开发完成待测试，另一侧指测试通过待发布。归并时逐条确认该状态在业务上处于哪个阶段、下一步由谁接手，再决定归入统一状态集的哪一档。名称只作为线索，业务含义才是归并依据。
兜底状态设得越多越安全吗？
兜底状态过多会让映射表变成逐状态翻译，维护成本上升，也容易掩盖真实的语义差异。建议按工具和状态类别集中设置，同一工具内语义相近的中间态共用一个兜底档，例如构建排队中、代码评审中都可落到进行中。每条兜底映射标注原因并设定复核周期，确认是否已有更精确的对应关系。
回退时两侧状态要不要自动双向同步？
默认只做正向同步，回退由人工确认后更新，可以避免两侧反复拉锯、互相覆盖。若业务要求回退也自动同步，需要先明确以哪一侧为准、连续回退几次转人工核查，并把规则写入异常流转表。无论是否自动，回退原因都应记录，便于后续定位状态错乱。
映射表上线后由谁维护，多久复核一次？
建议设一名映射表维护人，负责变更评审、版本记录和兜底复核组织；业务侧确认语义变更，集成实施方评估同步影响，运维或值班角色处置异常。复核周期按业务变化频率设定，例如每季度复核一次兜底映射，工具升级或流程调整后立即触发一次全量核对。
用 ONES 承接状态与流转管理时，映射表还需要自己设计吗？
需要。ONES 提供开放式的 DevOps 工具集成能力，可对接 GitLab、GitHub 等第三方应用，并通过 API 与企业系统打通数据；集成 Jenkins、GitLab CI 等流水线后，会同步流水线数据并更新执行状态和日志。这些能力承接状态在管理侧的呈现，映射表的归并、兜底和异常规则仍需按本文方法设计，具体配置方式以实际产品为准。
