属性

Asset

ADP-PLN-FEAT-DOC-0045

Feature

work-item-properties

领域

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

功能目标

让 Project 成员在 Work Item 详情和列表中维护标题、描述、优先级、日期、标签、类型与可选扩展属性，同时保证字段值、关联范围和权限在服务端复验。

功能结论

主题	当前结论
用户	Project Admin/Member 当前可编辑；Guest 以只读/creator 规则受限。
入口	canonical Work Item 详情正文与右侧“属性”区，以及列表/看板/表格的 inline editing。
可见结果	标题、富文本描述、优先级、开始/截止日期、创建人、标签、类型，以及按 Project 开关显示的估算、Cycle、Module、工时等。
当前系统保证	title 长度、日期顺序、HTML 安全、同 Project label/type/estimate/state/parent 等在 serializer 中校验；archived item 当前只读。
明确不做	state lifecycle、assignee、parent/relations、Cycle/Module、worklog、Automation 字段和 Formula 的定义/求值语义由各自 owner 持有，本页只定义属性区组合边界。
权威 owner	本页拥有基础字段编辑合同，以及 Formula 在属性区的只读消费边界；工作项类型拥有 Formula v1 的 workspace reusable definition、DSL、dependency graph、evaluation 与 API 合同。

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

• 当前落地状态：详情正文支持 title、rich description、type、description versions 与 reactions；侧栏支持 state、assignees、priority、created by、dates、estimate、module、cycle、parent、labels、worklog 和类型扩展字段。
• 已批准合同：属性变化不得绕过字段权限；Automation 属性是独立区块，不与 human assignment 或业务属性混为一谈；Work Item Type 可以引入专属属性分组，系统派生字段必须由服务端 read model 提供。
• 已批准合同：Task 的任务范围、依赖、交付物和验收说明保存在普通 description；业务状态、阻塞/打回原因、delivery evidence 与验收人/时间来自 Task business aggregate。详情可以组合展示两者，但不得创建同义 custom property 或在二者之间做反向解析/同步。
• 当前差距：现有 update API 没有对普通属性暴露明确的 optimistic revision/ETag；并发编辑可能依赖最后写入，目标冲突合同待补。
• 当前差距：Issue serializer 对部分无效关联采用过滤而非逐项错误，用户是否能识别被丢弃字段仍需统一。
• 后续交付：建立字段 owner/permission/validation matrix，固定并发与部分更新错误，再以真实 UI/API E2E 验收。

属性 owner 边界

属性	当前行为	Canonical owner
name/title	必填展示名，模型最大 255	本页
description	rich HTML/binary/json 形态；服务端校验/净化 HTML	本页
priority	urgent/high/medium/low/none	本页
start_date / target_date	nullable；start 不得晚于 target	本页
created_by / timestamps	只读审计	本页引用基础审计，不允许客户端改写
labels	只接受同 Project label	标签
type	只接受 Project 启用的 active type	工作项类型
estimate	只接受 Project estimate point	估算
state	只接受同 Project state	生命周期与状态
assignees	多值 human responsibility	分配与责任
parent / relations	同 Project parent 和关系	关系与子项
cycle / module / worklog	按 Feature 开关显示	各专项 Feature
Formula	Formula v1 only：workspace reusable definition 在有效 type context 中给出只读 computed value；不能经普通属性写入、设为 required/default，或存成普通 property value	工作项类型
Type 专属系统属性	例如阻塞/打回原因、交付证据、实际验收人/时间等；Issue.state 唯一表示进度，Epic 专用字段退役；它们不是 custom property，只读或受专属 action 更新	工作项类型 定义展示上下文，Automation · 产品级数据与接口 定义自动化结果应用边界

用户、权限与流程

1. Admin/Member 打开详情；页面按 Project Feature 开关和 Work Item Type 展示适用属性。
2. 用户编辑单个字段；客户端提交 partial update，服务端重新读取 Project 归属与权限。
3. 服务端校验 HTML、日期顺序和关联对象范围；不合法请求整体或逐字段返回明确错误。
4. 更新成功后 read model、activity 与列表投影最终显示同一值；异步 activity 不能让失败写入看起来成功。
5. archived item 的正文和侧栏当前禁用编辑；恢复后才重新允许常规属性写入。
6. fixed-stage Issue 的 state 字段受独立 workflow guard，不能借属性 API 绕过。
7. Type 专属属性按服务端返回的 effective context 和 read model 渲染；例如普通子项统计、阻塞原因与交付证据不通过普通 partial update 写入，也不从 Automation log、评论或 label 反向推断。

数据、API 与并发

基础字段保存在 Issue aggregate，label/assignee/module/cycle 等通过关系表或投影表示。目标公共合同至少要求：

• partial update 只修改显式字段，不把缺省字段清空；
• 客户端不可改写 workspace/project/sequence/created_by/audit identity；
• 关联 id 均按当前 Project 与 active status 复验；
• 无效列表项不得被静默丢弃，或必须在响应中返回 rejected items；
• description version 与主 description 更新有明确一致性；
• 并发写使用 issue revision/If-Match 或等价机制，冲突可由用户刷新并重试；
• API、activity 和 webhook 使用安全后的内容，不泄露内部二进制或敏感字段。

跨层依赖

• Project Feature controls 决定 estimate/module/cycle/type/worklog 控件是否出现，但不拥有 Issue 字段值。
• 评论、活动与附件拥有 activity 与附件，不把它们当 description。
• Issue 阶段工作流可限制 fixed-stage state mutation，不限制无关字段除非合同显式声明。
• Automation read model 与 human-facing properties 并列，不能覆盖基础字段或把 execution status 写进 business state。
• Phase4 Formula 只读消费同一 Work Item 的允许字段/property；它不拥有基础字段、不能成为 required/default value、不能计算 hierarchy rollup，也不能改写 Automation 或 workflow。

Formula v1 属性区集成边界

Formula v1 是 workspace reusable property type，不是 Project-local property。属性区只能消费服务端在当前 effective type context 中广告的 Formula value envelope；它不发送 expression、dependency、cache 或普通 value write。没有 active binding/import/type 的 Formula 不显示为当前属性，历史快照必须标为 historical，不能作为 当前值或可编辑 fallback。完整 DSL、dependency closure、null/error/query ordering、history、security 和 typed error contract 由工作项类型唯一持有。

异常与停止条件

• 跨 Project relation、非法 type/state/label/estimate、日期逆序、恶意 HTML 或权限不足时 fail closed。
• archived item、archived Project 或 fixed-stage state lock 下的禁止字段写入被拒绝。
• revision 冲突时不得 last-write-wins 静默覆盖；在该合同未落地前列为已知差距。
• bulk/inline update 的部分失败必须逐项可见，不能只显示通用 success toast。

验证与权威来源

• Web 正文与侧栏：apps/web/core/components/issues/issue-detail/main-content.tsx、apps/web/core/components/issues/issue-detail/sidebar.tsx
• Web edit permission：apps/web/core/components/issues/issue-detail/root.tsx
• Serializer：apps/api/plane/app/serializers/issue.py
• Model/API：apps/api/plane/db/models/issue.py、apps/api/plane/app/views/issue/base.py
• 前端 issue types：packages/types/src/issues/

验收需覆盖字段级正负向、跨 Project id、HTML 安全、日期、Feature 开关、archived read-only、并发和列表/详情一致性。

待决策问题

1. 普通属性更新采用哪种 issue revision/If-Match 合同，冲突如何呈现？
2. 无效 label/assignee 等列表项应整体拒绝还是逐项拒绝并返回结果？
3. 哪些字段允许 Guest creator 编辑，哪些必须始终只读？