工作流

Asset

ADP-PLN-FEAT-DOC-0048

Feature

workflows

领域

plane-core

作用域

application-level

文档状态

draft

产品生命周期

active

文档 Owner

DOC

事实源

canonical-docs

工程 Owner

PLN

Development Ready

not-ready

更新

2026/10/14

FEATURE DEVELOPMENT PACKAGE

工程就绪状态

工程 Owner：PLN · 仓库：PLN

BLOCKED

development · not ready

• ×原子需求与验收
• ×设计与工程合同
• ×代码与仓库定位
• ×里程碑与工作包
• ×验证计划
• ✓无阻断决策

verification · not ready

• ×Development Ready 已通过
• ×验收标准已覆盖
• ×正式测试已登记
• ×Fixture 与环境已定义
• ×测试规格已物化到正式测试

release · not ready

• ×Verification Ready 已通过
• ×实现修订可定位
• ×发布证据已登记
• ×兼容与迁移已定义
• ×Runbook 与回滚已定义

查看阻断项（5）

• Development Ready 缺少：原子需求与验收
• Development Ready 缺少：设计与工程合同
• Development Ready 缺少：代码与仓库定位
• Development Ready 缺少：里程碑与工作包
• Development Ready 缺少：验证计划

查看完整 readiness查看关联资产

功能目标

对齐官方 Plane 的 Workflows 产品语义：Project 至少拥有一个 default workflow，Enterprise Grid 可按 Work Item Type 绑定 type-specific workflow；启用 Workspace Governance 后，workflow 改由 workspace catalog 和 governance mode 管理。工作流决定业务状态迁移和审批门槛；Work Item Type 只提供匹配上下文，不直接推进状态。

功能结论

主题	结论
Producer 入口	Project Admin 在 project-managed 模式管理 Project default workflow 和可选 type-specific workflow；Workspace Admin 在 Workspace Governance 模式管理 workflow catalog、default、type allowlist、required policy 与 project/type pin。
可见结果	创建、详情、看板拖拽、bulk state change 与导入都按当前 Work Item Type 解析 effective workflow；不匹配的迁移显示明确 blocker。
系统保证	effective workflow 由服务端按 Project、type、workspace policy 和 active relation 解析；workflow 变更影响现有 Work Item 时必须提供 preview/remap 或阻塞，不得静默改写状态。
明确不做	不替代 Automation execution、Git review、QA、release、production confirmation 或 fixed-stage managed workflow；不让 Formula、comment、label 或外部 callback 触发 workflow mutation。
事实源 / owner	本页拥有 Project default workflow、type-specific workflow assignment、workspace governance、effective workflow resolution 与状态迁移 guard；Issue 阶段工作流只拥有 AutoDev 固定阶段 managed workflow。
当前成熟度	目标合同已确定；当前实现成熟度为 partial，本页不声明 Plane revision 已完成 TEST 或 production acceptance。

当前落地状态、已批准合同与差距

• 当前落地状态：Plane source 已有 project-managed workflow definition、Project default、type-specific assignment、workflow states、Transition/Approval flow metadata、版本化整体配置 API、mutation audit 和服务端 effective resolver；新 Project 会同步 provision permissive default workflow，既有 Project 由 migration backfill。普通 Work Item create 会校验 allow_new_work_items，app/public state write 会校验唯一 active source→target Transition，并以 updated_at 做 CAS；Web state write 会携带该版本。bug.close 可消费 Transition flow，也可创建、批准或打回 workflow-native Approval request。fixed-stage managed workflow 仍是独立实现，不作为 fallback。
• 已批准合同：Product semantics 对齐官方 Plane：project-managed 模式下 Project default workflow 是基础 fallback， type-specific workflow 在有效 Work Item Type context 中覆盖 fallback；Workspace Governance 模式下 workspace default workflow 是 fallback，并可通过 Any、Constrained、Required 和 pin 约束 Project 对 type 的选择。
• 当前差距：Work Item read API 的 effective workflow/available transitions/blocker 投影、Project settings workflow builder UI、Transition flow 的 by 成员授权、Runner conditions、Workspace Governance、外部 importer guard 以及 migration preview/remap 尚未交付。普通 raw state write 命中 Approval 或 server-owned semantic intent 时当前明确 fail closed；workflow-native Approval 仍只由 bug.close typed action 消费，Task intent 只允许 Transition。
• 后续交付：先补 effective workflow/available transitions read projection 与 Project settings UI，再交付 Transition by 和普通 Approval request 入口，最后交付 Enterprise Grid governance 和 migration preview/remap。

Workflow model

Workflow definition 是 Project 或 Workspace catalog 可引用的状态迁移合同，至少包含 stable ID、名称、active 状态、允许的状态集合、初始状态、迁移规则、可选审批策略、版本和审计。需要被 server-owned 业务 action 消费的 transition 还必须声明稳定的 semantic intent；展示名、状态名和 state group 不能代替该 intent。Project default workflow 必须始终存在；启用 Workflows 后，未匹配 type-specific workflow 的 Work Item 使用 Project default workflow。启用 Workspace Governance 后， workspace 必须有唯一 default workflow，Project default 退化为消费 workspace default 或被允许的 type-specific selection。

Type-specific assignment 绑定到 Project 中 active 的 Work Item Type relation，而不是可变 type name。Project Admin 在 project-managed 模式可为本 Project 的 active type 选择 active workflow；Workspace Admin 可在 Enterprise Grid Governance 下对 workspace library type 配置 Any、Constrained allowlist、Required workflow 或 project/type pin。

Effective workflow resolution

服务端在 Work Item create、state update、board drag、bulk state change、import 和 API write 中统一解析：

1. type 的 governance mode 为 Required 时指定的 required workflow；
2. Workspace Admin 在 Any 或 Constrained mode 下对 project/type 设置的 active pin；
3. Project Admin 针对 active project/type relation 设置的 own choice，且必须满足 Any 或 Constrained allowlist；
4. Workspace Governance 的 workspace default workflow，或 project-managed 模式下的 Project default workflow。

任一候选 workflow、type relation、Project 或 Workspace 不可见、inactive、跨租户、版本过期或不满足 governance 时 fail closed。客户端只展示服务端返回的 effective workflow、可用 state、可用 transition 和 blocker，不自行推导授权。

状态变更、审批与变更影响

workflow 决定 Work Item 可创建的初始 state、后续 state transition、需要的审批门槛和 transition blocker。普通 属性更新、评论、标签、Formula 计算、Automation event、GitLab/TeamCity evidence 或通知投递都不能绕过 workflow guard 或代写状态。

当 Work Item Type 由 server-owned 业务 action 状态机管理时，effective workflow 的 transition 只能由对应 typed action 消费；普通 state selector、board drag、bulk/import 或 raw state PATCH 不再是授权入口。Issue.state 仍作为跨类型 生命周期投影返回并显示。哪些类型属于受管类型以及 action 与投影的提交时序由生命周期拥有。

workflow assignment、required policy 或 pin 的变更若会使现有 Work Item 的 current state 不再属于新 workflow，必须先返回 impact preview。Producer/Admin 只能选择明确 remap、保留现状并标记 blocked，或取消变更；不得自动迁移、删除状态或把 Work Item 静默移入默认状态。

受管业务动作消费 transition

server-owned 业务 action 不得直接选择 Project State，也不得根据状态展示名或 completed group 猜测目标。V1 为 Bug 关闭保留唯一 semantic intent bug.close：Bug 当前 effective workflow 必须从当前 state 暴露恰好一个 active、可用的 bug.close transition，且 target state 必须属于同一 Project、同一 effective workflow，并且 group 为 completed。 intent 缺失、重复、当前 source 不匹配或 target group 不合法时，resolver 返回 blocker 并 fail closed。

resolver 的逻辑结果至少固定 effective workflow ID/version、transition ID/intent、source/target state、target group、Work Item version、审批要求和 blocker；这是服务端内部权威解析结果，不要求客户端或 Automation runtime 复制 workflow definition。业务 action 必须复用普通 state write 的权限、审批、fixed-stage guard、审计和 CAS，不能因已有业务证据而绕过。

bug.close 只定义 Work Item 终态目标，不证明 Bug 已通过回归，也不等同于 Symphony 执行、MR、发布或 Producer acceptance。Bug 业务状态与 Work Item state 的提交时序由生命周期拥有。

所有保留 Issue 类型使用原生 Issue.state 作为唯一进度。State.progress_role 是状态语义元数据，服务端动作解析唯一当前/目标状态，并消费权限、证据和 CAS。专业验收、测试验收与阻塞必须由原生状态明确表达，不再把多个细粒度进度压到同一 started 投影。

Task 按钮、普通状态更新、看板、批量和 API 不能有不同的验收或权限规则；动作返回 state_transition，写入绑定 expected_issue_updated_at。删除旧类型状态 → state 同步；已有责任和审计仍独立保留。非 Epic 人工验收规则不放宽，Epic 专用流程删除。

跨类型终结 intent

生命周期的跨类型终结动作消费两个 server-owned semantic Transition intent：

• work_item.force_complete：从当前 source 解析唯一 active Transition，target group 必须是 completed；
• work_item.cancel：从当前 source 解析唯一 active Transition，target group 必须是 cancelled。

这两个 intent 对所有 Work Item Type 使用同一 identity，类型只决定 action label 和原子提交中的业务状态效果。客户端不得 提交 state/transition ID，resolver 也不得从 State name、group、default 或排序猜 target。每个动作必须在请求锁定后重新 确认 current source、effective workflow/Transition version 与唯一性；缺失、歧义、target group 非法或版本漂移时返回稳定 blocker 并 fail closed。

default workflow provisioning/backfill 只有在该 group 从每个适用 source 都有唯一、确定的 target 时才可 additive 建立这些 intent；任何歧义保持配置不变并禁用动作。自定义 workflow 必须由 Admin 显式配置 exact Transition，系统不得自动选择。 终结 intent 只允许 Transition flow；它们自身的强授权、必填 reason 和原子 audit 是 break-glass gate，不创建或代签普通 workflow Approval。Task/Bug 的正常 typed progression、delivery stage、department approval 与 bug.close approval 不能阻止 获准的终结动作，也不能把 bypass 扩展给其它入口；pending bug.close approval 的失效由生命周期事务处理。

当 bug.close 命中 Approval flow 时，关闭动作创建一个 pending request，Work Item 与 Bug 均保持原状态。request 冻结 Issue updated_at、Bug revision、workflow/flow ID 与版本、source/approve/reject state 和 requester；同一 Issue 同时只允许 一个 pending request。Approval flow 的 by 默认为 All，即任一 active Project Admin/Member；配置非空成员列表时仅这些仍为 active Project Admin/Member 的用户可决定。批准会在同一事务中把 Work Item 移到 approve target 并把 Bug 标为 closed；打回 必须填写原因，只把 Work Item 移到 rejection state，Bug 仍保持 regression_passed，不得伪造为 regression failure。之后是否 还能重新请求关闭，由 rejection state 上重新解析出的 bug.close flow 决定。request、Issue、Bug、workflow、flow 或成员资格 任一漂移都 fail closed，客户端不能提交目标 state。 失效 request 不在读取时静默改写；下一次基于当前 resolver snapshot 的关闭请求会在同一事务中把旧 request 标为 invalidated 并创建新 request，避免旧审批永久占用 Work Item。

API、UI 与审计

• Project APIs 提供 workflow definition list/read、Project default set、type-specific assignment set/clear 和 impact preview。
• Workspace APIs 提供 governance policy、type allowlist、required workflow、project/type pin 和 impact preview。
• Work Item read API 返回 effective workflow ID/version、当前 state 是否有效、available transitions 和 blocker。
• Work Item state write API 必须携带 expected Work Item version 或等价 CAS；冲突返回可刷新重试错误。
• server-owned 业务 action 请求必须同时绑定 action 自身 revision、expected Work Item version 和 resolver 使用的 effective workflow version；幂等重放只能返回同一 transition/approval 结果，不得在 workflow 改版后重新解释旧请求。
• 跨类型终结 action projection 返回稳定 action identity、类型感知 label、required reason、expected revisions、resolved source/target group 和 disabled_reason；target state/transition ID 仍只由服务端持有。
• UI 在 Project settings 管理 default 与 type-specific workflow；Workspace settings 管理 governance；Work Item create/detail/board/bulk/import 只消费 resolver 结果。
• 每个 definition、assignment、governance 和 state transition mutation 都记录 actor、before/after、reason、 request correlation 和版本。

跨层依赖

• 工作项类型提供 type identity、Project relation、workspace library/import 与 hierarchy context。
• 状态拥有 Project state identity、group 和基础 state lifecycle。
• 属性不能借属性 API 绕过 state/workflow guard。
• Issue 阶段工作流拥有 AutoDev 固定阶段 managed workflow；本页不重建该 run/stage/Finding 合同。
• Automation、Harbor release、QA 和 production confirmation 是独立事实轴，不能作为 workflow assignment 或 state transition 的替代证据。

异常、停止条件与验收

跨 Workspace/Project、inactive type relation、inactive workflow、governance 冲突、state 不可 remap、权限不足、 版本冲突、审批缺失或无法证明 effective workflow 时 fail closed。不得降级为 client-side filtering、last-write-wins、 默认状态静默重写或 fixed-stage managed workflow fallback。

验收至少覆盖 Project default workflow、type-specific assignment、Workspace governance allowlist/required/pin、 effective resolver priority、create initial state、state transition guard、board drag、bulk state change、import、 impact preview/remap、审计、task.start / task.reset / task.complete 与 bug.close 的唯一 intent/target 校验，以及 work_item.force_complete / work_item.cancel 在 default/custom workflow 中的唯一 exact Transition、缺失/歧义 fail closed、 CAS/幂等与 bypass 边界，以及 fixed-stage managed workflow 的正常边界不变。