状态

Asset

ADP-PLN-FEAT-DOC-0035

Feature

project-states

领域

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查看关联资产

Issue 唯一进度

所有保留 Issue 类型使用原生 Issue.state，State.progress_role 是状态定义的语义元数据，不在 Issue 再增加进度字段。状态展示名可本地化，不能按名称或颜色推导动作目标。

保留非 Epic 业务按钮，由服务端检查责任、证据、版本和幂等后更新唯一状态。列表、详情、分组、排序与筛选使用同一原生状态；删除旧类型状态和隐藏阶段进度。Epic 专用类型与审批流程退役，历史记录只读归档。

功能目标

让每个 Project 定义可供工作项使用的状态集合，并以固定状态分组表达业务进度、默认入口、排序与可删除边界。

功能结论

主题	当前结论
用户	Project Admin 配置状态；Project Member 当前可进入状态设置页查看。
入口	/{workspaceSlug}/settings/projects/{projectId}/states。
可见结果	按 Backlog、Unstarted、Started、Completed、Cancelled 分组查看状态；Admin 可创建、编辑、排序、设默认或删除。
当前系统保证	状态强制属于一个 Project/Workspace；同一 Project 的 active 状态名唯一；默认和非空状态不能删除。
明确不做	Project 状态不等于 Issue 业务阶段；server-owned fixed-stage 的受控迁移由阶段工作流拥有，Project 不配置或激活该合同。
权威 owner	本页拥有 Project State identity、group、default、sequence 与配置约束。

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

• 当前落地状态：Project 创建时初始化 Backlog、Todo、In Progress、Done、Cancelled 和内部 Triage。Web 状态设置展示五个常规分组，Admin 可编辑；Triage 由 Intake 路径单独读取。
• 已批准合同：状态是独立项目级 Feature；Project 状态与 Issue 业务阶段是独立状态轴。
• 当前差距：Web 编辑能力仅授予 Project Admin，但 API partial_update 当前声明允许 Admin/Member/Guest；这是权限不一致，不能成为稳定合同。
• 当前差距：mark-default 操作会先清除其它 default，但模型层没有可见的单 default 数据库约束/并发保护；并发语义待补。
• 后续交付：收敛角色矩阵、默认状态唯一性和移动排序的并发合同，再补 fixed-stage guard 的跨页验收。

状态模型与分组

当前 State 字段包括 id、project/workspace、name、description、color、slug、sequence、group、is_triage、default 与审计字段。用户可见分组固定为：

group	业务含义	当前默认名称
backlog	尚未进入计划队列	Backlog
unstarted	已准备但未开始	Todo
started	处理中	In Progress
completed	已完成	Done
cancelled	已取消	Cancelled

triage 是 Intake 使用的内部状态分组，不出现在普通 Project State manager 中；是否将其作为公开可配置状态仍未批准。

状态 name 是展示事实，group 才是跨状态的进度分类。重命名状态不得改变历史工作项 identity；改变 group 会影响完成时间、归档资格和统计，应视为高影响更新。

用户、权限与流程

1. Project Admin 在某个 group 中创建状态，填写 name、description、color；服务端强制 Project 归属和 name 唯一。
2. Admin 编辑状态或调整 sequence；客户端只为 Admin 启用操作控件。
3. Admin 将状态设为 Project default；后续新工作项在无显式状态时使用 default，若不存在则回落到可用状态。
4. 删除前必须保证状态不是 default 且没有工作项；客户端还阻止删除分组中的最后一个状态。
5. 非 Admin 当前可查看的范围与 API 写权限声明必须在服务端收敛，不能依赖隐藏按钮。

数据、API 与一致性

当前 State API 支持 list/grouped list、create、partial update、mark-as-default、delete 和 Intake state 读取。目标稳定合同至少要求：

• state/project/workspace 同租户，group 在允许枚举内；
• active state name 在 Project 内唯一；
• 每个 Project 恰有一个可用 default state，切换为原子操作；
• sequence 移动处理并发和重复请求，不能丢失状态；
• 删除在服务端检查 default、非空和最后可用状态，而非只依赖 UI；
• group 变更对 completed_at、archive eligibility、分析和 fixed-stage workflow 的影响可预览。

跨层依赖

• 生命周期消费 state/group 并拥有工作项的业务状态变化。
• Issue 阶段工作流拥有 fixed-stage Issue 的允许迁移与受控状态写；普通 State API 不得绕过 guard。
• 分析消费 group 作为统计维度，不拥有状态配置。
• Issue 阶段工作流是独立业务阶段轴，不映射或代写 Project State。

异常与停止条件

• 跨 Project/Workspace state、重复 name、非法 group 或权限不足时 fail closed。
• default、非空状态或分组最后状态不得直接删除。
• 并发 default/sequence 写入无法证明唯一结果时停止并要求刷新。
• fixed-stage Issue 的状态被锁定时，普通 issue update 当前返回 409；不得通过其它 bulk/drag API 绕过。

验证与权威来源

• Web 路由与权限：apps/web/app/(all)/[workspaceSlug]/(settings)/settings/projects/[projectId]/states/page.tsx
• Web 操作：apps/web/core/components/project-states/
• API：apps/api/plane/app/views/state/base.py
• 模型与常量：apps/api/plane/db/models/state.py、packages/constants/src/state.ts、packages/types/src/state.ts
• fixed-stage guard：apps/api/plane/issue_workflow/guards.py

需要用服务端权限负向、默认状态并发、删除 blocker 和 fixed-stage transition E2E 证明最终合同。

待决策问题

1. 状态配置是否严格只允许 Project Admin，Member 是否只读，Guest 是否完全不可见设置页？
2. 是否允许修改现有状态的 group；若允许，完成时间、归档和统计如何重算？
3. Triage 是否保持 Intake 私有，还是成为可配置的第六组？

部门边界

部门审批不再参与通用状态转换。Issue.state/progress_role、现有权限、类型业务动作与专业/测试验收是唯一有效业务合同；移除审批拦截不允许越权或绕过验收。部门分析读取原生状态及事件时责任快照。