工具链状态映射表要解决的是同一个工作项在多个系统里状态叫法不同、流转节奏不一致的问题。设计时先把各系统状态收敛成一套统一状态集，再逐条记录来源系统、来源状态、目标状态、触发事件、同步方向与异常处理方式，最后用真实工单走一遍双向同步验证。下文给出字段结构、填写步骤、角色分工与上线检查清单，可直接作为设计模板使用。
要点总览（TL;DR）
- 先按工作项从创建到结束的实际处理阶段定一套统一状态集，每个状态写清含义与进入条件，作为映射表目标侧的唯一取值来源。
- 映射表按定位规则、触发条件、同步行为、维护信息四组字段组织，来源状态照抄系统枚举值，目标状态只从统一状态集取值。
- 填写顺序是先导出各系统状态枚举去重，再逐条指定目标状态与触发事件，然后处理一对多、多对一与无对应状态，最后标注同步方向与冲突取舍。
- 双向同步要显式定义回写条件，重开、驳回等回退场景建议转人工确认，无法映射的状态给出兜底动作并通知维护人补规则。
- 上线前用真实工单走完整生命周期，核对状态覆盖完整性、循环触发、回退与异常兜底，变更后按同一路径做回归验证。
先定统一状态集：映射表的骨架
映射表的第一层设计是统一状态集。它决定目标侧用哪些状态承接各来源系统的原始状态，也决定后续字段怎么填。做法是先抛开各系统的既有命名，按工作项从创建到结束的实际处理阶段划分状态，再为每个状态写清含义与进入条件。
常见划分粒度可以控制在五到七个状态：待处理、进行中、待验证、已完成、已关闭，必要时增加已取消与已阻塞。粒度太细会让多个来源状态挤向同一目标状态时难以取舍，粒度太粗则丢失“是否已验证”“是否已交付”这类关键区分。判断标准是：每个状态能否对应一个明确的负责人动作和可观察的完成标志。
统一状态集需要与工作项类型对应。需求、缺陷、任务的流转路径不同，缺陷通常需要“待验证”和“重开”，需求更关注“已交付”与“已关闭”的区分。建议按工作项类型分别维护状态集，共用同一套状态命名，避免同一名称在不同类型下含义漂移。
边界情况要在这一层就写进状态集清单，包括取消、驳回、重开与阻塞。取消表示工作项不再推进；驳回表示评审或验证未通过、退回上一环节；重开表示已关闭的工作项重新进入处理；阻塞表示因外部依赖暂停但未终止。这四类情况如果留到填写映射行时再处理，很容易出现某个来源状态无处安放。
| 统一状态 | 含义 | 进入条件 |
|---|---|---|
| 待处理 | 已创建、尚未开始处理 | 工作项创建完成并分配负责人 |
| 进行中 | 负责人正在处理 | 负责人开始处理并更新进展 |
| 待验证 | 处理完成、等待验证 | 提交验证并指定验证人 |
| 已完成 | 验证通过、交付完成 | 验证人确认通过 |
| 已关闭 | 流程终结、归档 | 完成归档或超过关闭条件 |
| 已取消 | 不再推进 | 业务方确认取消并记录原因 |
| 已阻塞 | 暂停但未终止 | 存在外部依赖并登记阻塞原因 |
这份清单是映射表的目标侧字典，后续每一行的“目标状态”都只能从中取值，从而保证映射结果可统计、可核对。
映射表要写哪些字段
字段结构决定映射表能否被机器读取、被人复核。建议按“定位一条规则—描述触发条件—约束同步行为—留出维护信息”四组组织字段，并明确必填与选填。
| 字段 | 作用 | 填写要求 | 必填 |
|---|---|---|---|
| 映射ID | 唯一标识一条规则，便于日志与问题定位 | 按“系统-对象-序号”编号 | 是 |
| 来源系统 | 状态变化的发起方 | 写系统正式名称 | 是 |
| 来源对象类型 | 区分需求、缺陷、任务等 | 与统一状态集的工作项类型一致 | 是 |
| 来源状态 | 来源系统中的原始状态值 | 照抄系统枚举值，不改写 | 是 |
| 目标系统 | 状态写入的接收方 | 写系统正式名称 | 是 |
| 目标状态 | 统一状态集中的取值 | 只能取自统一状态集 | 是 |
| 触发事件 | 什么动作引发同步 | 如状态变更、字段更新、定时扫描 | 是 |
| 同步方向 | 单向或双向 | 标明发起方与接收方 | 是 |
| 是否双向 | 是否允许回写 | 双向时须同时填写回写条件 | 是 |
| 优先级 | 多条规则命中同一状态时的取舍 | 数值越小优先级越高 | 否 |
| 冲突处理 | 双方状态不一致时的处理方式 | 如以来源为准、以最新时间为准、转人工 | 否 |
| 生效条件 | 规则适用的项目、环境或时间范围 | 如仅限某项目空间 | 否 |
| 负责人 | 该条规则的确认与维护人 | 写到角色或具体人 | 否 |
| 备注 | 特殊说明与已知限制 | 简短描述 | 否 |
| 变更记录 | 版本、修改人、修改时间与原因 | 每次修改追加一行 | 是 |
必填字段构成一条规则的最小可执行信息，缺任何一项都无法判断同步是否应该发生。选填字段用于处理例外：优先级与冲突处理在单向同步中可以不填，一旦出现双向或一对多映射就必须补齐。变更记录虽然放在最后，但它是映射表可维护的前提，建议与映射表同表维护，避免规则改了却查不到原因。
逐条填写映射规则的操作步骤
字段定好后，填写顺序影响效率。建议按“先枚举、再对齐、后处理例外”的顺序推进，每一步都有明确输入和输出。
第一步，导出各系统状态枚举并去重。输入是各系统的状态配置或接口返回的状态列表，动作是按系统、按对象类型整理成清单，去掉重复值与历史废弃值，输出是一份原始状态全集。完成标志是每个系统的每个对象类型都有对应清单，且清单中的值与系统当前配置一致。
第二步，为每个原始状态指定目标状态与触发事件。逐条对照统一状态集，为每个来源状态选择最接近的目标状态，并写明由什么事件触发同步。多数状态可以一对一直接对应，例如来源系统的“新建”对应“待处理”。这一步的完成标志是原始状态全集中没有空白项。
第三步，处理一对多、多对一与无对应状态。一对多指一个来源状态可能落到多个目标状态，需要补充判断条件，例如按处理结果字段区分“已完成”与“已取消”。多对一指多个来源状态收敛到同一目标状态，通常可以接受，但要在备注中说明收敛后丢失了哪些区分。无对应状态必须给出兜底动作，例如映射到“待处理”并标记待人工确认，不能留空。
第四步，标注同步方向与冲突取舍规则。明确每条规则由谁发起、是否回写。双向同步的规则要写清回写条件，例如仅当目标侧状态由人工修改时才回写，由自动同步产生的变更不再触发反向同步。冲突处理优先选择可预期的规则，如以最近更新时间为准，无法自动判断时转人工处理。
四步完成后形成映射规则表初稿。初稿应能回答三个问题：任一来源状态变化后目标侧变成什么、双向场景下谁说了算、遇到无法映射的值怎么办。
角色分工与交付物
映射表跨越多个系统，单靠一个人梳理容易遗漏语义差异。建议设置三类角色，各自有明确产出。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 集成负责人 | 统筹统一状态集设计、组织评审、指定映射表唯一维护人 | 统一状态集清单、评审记录 |
| 各系统管理员 | 提供本系统状态枚举、流转规则与接口能力说明 | 原始状态清单及流转说明 |
| 业务代表 | 确认状态语义与业务含义，判断收敛后是否丢失关键区分 | 状态语义确认意见 |
评审环节的产出应包含三部分：统一状态集是否被业务方认可、映射规则是否覆盖全部原始状态、双向与冲突规则是否可执行。评审记录要留下参与人、结论与待办，作为后续变更的依据。
映射表需要指定唯一维护人，负责接收变更申请、更新映射行并追加变更记录。版本维护建议与集成配置的发布节奏对齐，每次同步规则调整都对应一个映射表版本号，便于出问题时回退到上一版本比对。
示例：一条缺陷状态的双向映射
下面以缺陷在两个系统间的双向同步为例，展示映射行如何填写。假设来源系统为缺陷跟踪工具，目标系统为项目管理平台，统一状态集采用前文的七状态划分。
| 映射ID | 来源状态 | 目标状态 | 触发事件 | 同步方向 | 是否双向 | 冲突处理 |
|---|---|---|---|---|---|---|
| BUG-01 | 新建 | 待处理 | 状态变更 | 来源→目标 | 是 | 以最近更新为准 |
| BUG-02 | 处理中 | 进行中 | 状态变更 | 来源→目标 | 是 | 以最近更新为准 |
| BUG-03 | 已修复 | 待验证 | 状态变更 | 来源→目标 | 是 | 以最近更新为准 |
| BUG-04 | 已验证 | 已完成 | 状态变更 | 来源→目标 | 是 | 以最近更新为准 |
| BUG-05 | 已关闭 | 已关闭 | 状态变更 | 双向 | 是 | 以最近更新为准 |
| BUG-06 | 重新打开 | 进行中 | 状态变更 | 双向 | 是 | 转人工确认 |
双向同步的关键在回写规则。以 BUG-05 为例，目标侧人工关闭缺陷时回写来源系统为“已关闭”；由自动同步产生的关闭不再触发反向同步，避免两边来回写入。BUG-06 的重开涉及状态回退，建议设置为转人工确认，由负责人判断是回到“进行中”还是新建关联缺陷，防止自动回退造成状态抖动。
无法映射的兜底做法同样要写进表里。例如来源系统出现一个未登记的新状态值，同步任务应将其映射到“待处理”并打上待确认标记，同时通知映射表维护人补充规则，而不是静默丢弃或反复重试。
在工具承载层面，ONES 可承载工作项状态与流转配置，并通过 API 与第三方应用集成打通数据；集成 Jenkins、GitLab CI 等流水线工具后，ONES 会同步流水线执行状态与日志。具体接口清单、状态同步的冲突处理与回写机制需以开发者文档和实际环境为准，映射表中的冲突规则仍应按本文方法逐条定义。
上线前的完成检查
映射表投入运行前，用真实工单走完整生命周期，按以下清单逐项核对，并保留验证记录。
- 状态覆盖完整性：对照原始状态全集逐项检查，确认每个来源状态都有对应映射行，无对应状态已配置兜底动作。检查方式是导出映射表与状态清单做差集，差集为空才算通过。
- 循环触发检查：对每条双向规则连续触发两次同步，观察是否出现 A 写入 B、B 又回写 A 的循环。验证记录中应写明触发次数与最终稳定状态。
- 回退检查：模拟重开、驳回等回退场景，确认目标侧状态按预期回退，且不会把已关闭的工作项误置为进行中。
- 异常与冲突验证：构造双方状态不一致、来源状态未知、同步接口超时三类场景，确认冲突处理规则生效、兜底动作可执行、失败有记录可查。
- 变更后回归：映射表每次修改后，按同一路径重跑上述检查，重点回归被修改的映射行及其相邻规则，确认没有引入新的循环或丢失映射。
检查全部通过后，将验证记录与映射表版本号一并归档。上线后若出现状态不一致，先比对映射表版本与同步日志，再判断是规则缺失还是执行异常，避免直接改配置掩盖问题。
常见问题
统一状态集应该划几个状态，粒度怎么把握？
常见做法控制在五到七个状态，例如待处理、进行中、待验证、已完成、已关闭，必要时增加已取消与已阻塞。判断粒度是否合适的标准是：每个状态能否对应一个明确的负责人动作和可观察的完成标志。粒度太细会让多个来源状态挤向同一目标状态时难以取舍，粒度太粗则容易丢失“是否已验证”“是否已交付”这类关键区分。
需求、缺陷、任务的流转路径不同，建议按工作项类型分别维护状态集，共用同一套状态命名，避免同一名称在不同类型下含义漂移。
来源系统出现映射表里没有的新状态值，同步任务应该怎么处理？
不要静默丢弃，也不要反复重试。建议在映射表中预设兜底规则：将未知状态映射到“待处理”并打上待确认标记，同时通知映射表维护人补充规则。兜底动作要写进表里，并在上线检查时用构造的未知状态值验证一次，确认标记和通知都能正常产生。
兜底规则只是临时承接，维护人补充正式映射行后，应回归验证该状态值是否已按新规则同步。
双向同步时，怎么避免两边来回写入造成状态抖动？
关键是显式定义回写条件。常见做法是仅当目标侧状态由人工修改时才回写，由自动同步产生的变更不再触发反向同步。重开、驳回这类状态回退场景，建议设置为转人工确认，由负责人判断回到哪个状态，避免自动回退造成抖动。
上线前对每条双向规则连续触发两次同步，观察是否出现 A 写入 B、B 又回写 A 的循环，并在验证记录中写明触发次数与最终稳定状态。
映射表由谁维护，规则改了怎么追溯？
建议由集成负责人统筹统一状态集设计并指定映射表唯一维护人，各系统管理员提供本系统的状态枚举与流转说明，业务代表确认状态语义。映射表本身要维护变更记录字段，每次修改追加版本、修改人、时间与原因，并与集成配置的发布节奏对齐，出问题时可以回退到上一版本比对。
如果多人都有修改权限，容易出现规则改了却查不到原因的情况，唯一维护人加变更记录是成本较低的做法。
映射表上线后出现状态不一致，先查什么？
先比对映射表版本与同步日志，判断是规则缺失还是执行异常，再决定是否改配置。规则缺失表现为某个来源状态没有对应映射行或兜底未生效；执行异常表现为规则存在但同步失败、超时或重复触发。直接改配置容易掩盖问题，建议保留日志证据后再调整，并按变更后回归的方式重跑相关映射行。
