Releases 产品需求文档（PRD）
1. 文档信息
| 项目 | 内容 |
|---|---|
| 文档版本 | V0.1 |
| 文档状态 | 草案（Draft） |
| 产品负责人 | Producer（范围、状态语义、权限粒度和发布边界决策） |
| 文档负责人 | DOC |
| 评审人 | PLN、设计、QA、安全与数据 owner |
| 目标版本 | Releases v1；发布日期待 Producer 确认 |
| 适用范围 | Project 内的 Release 条目、发布范围、Milestone 关联和发布沟通事实 |
| 核验来源修订 | PLN · 75c4f1c80ac12f1322fe7bac2132d49a875f3291 |
本 PRD 定义 Release 的产品问题、范围、用户行为、权限、状态与验收结果。数据/API 细节由 数据、状态与 API 拥有，界面与交互由 用户入口与交互 拥有，验证计划由 验收与测试规格 拥有，对象边界与权限矩阵由 产品与数据合同 拥有。
本文的全部实现级事实按 PLN · 75c4f1c80ac12f1322fe7bac2132d49a875f3291 固定修订核验；该修订是本文档仓
catalog/asset-sources.lock.json 中 PLN 的来源锁定值，与本 run 记录的 PLN materialization
141fd051ebaed9146e7ea8fcaa091032c0b3c500 在本文引用的全部路径上内容一致。
1.1 变更记录
| 版本 | 日期 | 修改人 | 变更说明 |
|---|---|---|---|
| V0.1 | 2026-09-16 | DOC | 将 planned stub 收敛为经固定 source revision、真实 UI/路由、API schema 与现有契约测试交叉核验的产品合同与验收基线（ADP-504）；未核验项保留 unknown |
2. 背景与目标
2.1 背景
当前 AutoDev Plane fork 已存在 Project 级 Release 对象：条目本身承载名称、发布状态、标签、目标/实际发布日期、 变更日志、负责人、发布范围（Work Item）和 Milestone 关联，并提供 Project 导航入口、列表与详情页面、受管 API 与契约测试。此前的 canonical 入口只有 inventory stub，只批准了“Releases 是独立 Feature”，没有批准任何 稳定行为合同，因此用户、权限、状态、数据/API 与失败语义长期处于未定义状态。
Release 同时处在容易被误读的位置：它是发布沟通对象，而不是制品、候选或环境事实。若把 Release 条目读成 Harbor sealed release artifact 或 TEST/PRODUCTION 部署 evidence，工程结论会被文档代签。
2.2 用户问题
| 用户问题 | 用户影响 | 产品需要提供的结果 |
|---|---|---|
| 发布沟通只存在于聊天或台账，Project 内没有权威条目 | 成员无法从工作项回溯到所属发布 | Project 内可创建、可维护、可发现的 Release 条目 |
| 发布范围靠人工描述 | 无法判断某个发布覆盖了哪些工作项 | Release 条目拥有显式 Work Item 范围，且只允许同 Project 对象 |
| 发布状态没有稳定语义 | 同一状态在不同人手里含义不同 | 三个稳定状态值及其用户可见含义固定，且不驱动部署 |
| 发布与交付检查点关系不清 | Milestone 状态被发布动作意外改写 | Milestone 与 Release 显式关联，两者状态互相独立 |
| 重复提交或网络重试造成重复条目 | 出现重复 Release 或重复关联 | 每个写请求必须携带幂等键，重放返回首次结果 |
| 并发编辑互相覆盖 | 后写方静默覆盖先写方 | 以 version 作乐观并发令牌，陈旧写入被拒绝 |
2.3 产品目标
- Project Admin 可以按 Project 启用 Releases，并在 Project 内创建和维护 Release 条目。
- Release 条目具备稳定身份、稳定状态值、显式发布范围和显式 Milestone 关联。
- 发布状态与日期是发布沟通事实，用它判断工作项归属与沟通进度，而不是判断制品或环境是否就绪。
- 所有写入在服务端校验 Workspace、Project、成员角色、
version和幂等键，失败不产生部分写入。 - Release 条目、Harbor sealed release artifact 与部署 evidence 在文档和数据模型上保持可区分。
2.4 成功指标
以下为草案测量框架。观察窗口、环境、负载与有效/无效样本边界尚未冻结，不能据此宣称已达到发布门。
| 指标 | 计算口径 | 草案目标 |
|---|---|---|
| 有效创建闭环率 | 成功创建的 Release 条目数 / 去重后的有效创建请求数 | 100%；未知结果必须可解释 |
| 幂等重放一致率 | 与首次记录完全一致的重放响应数 / 重放请求数 | 100% |
| 越权写入事件数 | 非 Project Admin 成功创建、修改、删除或改关联的事件数 | 0 |
| 跨 Project 关联写入数 | 持久化的跨 Project Work Item 或 Milestone 关联数 | 0 |
| 陈旧写入覆盖数 | 以陈旧 version 成功覆盖他人写入的事件数 | 0 |
| 详情页可见反馈时延 | 从用户提交到显示成功、失败或冲突结果的耗时 | P95 目标与浏览器矩阵待 Producer 与 QA owner 确认 |
指标事实来自 Plane 持久化表、服务端权限检查和写入 receipt 记录；目标环境、统计窗口和无效样本边界由 Producer、PLN 与 QA owner 在进入批准评审前确定。
3. 用户与使用场景
3.1 目标用户
| 用户 | 核心任务 | 权限边界 |
|---|---|---|
| Project Admin | 启用 Releases、创建与维护条目、维护范围与 Milestone 关联、删除条目 | 必须同时是当前 Workspace 与当前 Project 的 active 成员；写权限由服务端校验 |
| Project Member | 浏览 Release 列表与详情、读取范围与变更日志 | 只读；只能看到自己有权访问的 Project |
| Milestone 使用者 | 从 Milestone 侧读取关联 Release | 只读；不具备 Release 写权限 |
| 发布沟通读者（Producer 等） | 依据 Release 条目对齐范围与沟通状态 | 只读；不得把条目读成制品或环境 evidence |
3.2 用户故事
- 作为 Project Admin，我希望按 Project 启用 Releases，以便只在需要发布沟通的项目中出现该入口。
- 作为 Project Admin，我希望创建 Release 条目并维护状态、标签、日期与变更日志，以便团队有唯一发布沟通事实。
- 作为 Project Admin，我希望把工作项纳入或移出某个发布，以便范围可见且可调整。
- 作为 Project Admin，我希望把 Release 与 Milestone 显式关联或解除，以便交付检查点与发布沟通可以对照而不互相改写。
- 作为 Project Admin，我希望删除错误条目后关联自动收敛，并且重复提交不会产生重复条目。
- 作为 Project Member，我希望看到有权访问的 Release 与范围，以便理解当前工作属于哪个发布。
3.3 核心场景
- 在 Project Settings 启用 Releases，Project 导航出现发布入口。
- 创建 Release 条目，填写名称、状态、标签、目标日期与变更日志。
- 把一个或多个同 Project 工作项加入发布范围，随后移出其中一个。
- 关联一个 Milestone，在 Release 详情与 Milestone 详情两侧看到同一关联。
- 把状态从
unreleased更新为released并填写实际发布日期。 - 删除条目，列表与两侧关联同步收敛。
4. 产品范围
4.1 本期范围
| 编号 | 功能 | 用户结果 | 优先级 | 目标版本 |
|---|---|---|---|---|
| FR-001 | 按 Project 启用与发现 Releases | Admin 启用后 Project 导航与列表可用；未启用时入口与写入均不可用 | P0 | Releases v1 |
| FR-002 | 创建与维护 Release 条目 | 可创建条目并维护名称、状态、标签、目标/实际发布日期、变更日志和负责人 | P0 | Releases v1 |
| FR-003 | 维护发布范围 | 可把同 Project 工作项加入或移出发布范围，范围可读 | P0 | Releases v1 |
| FR-004 | 关联 Milestone | 可在 Release 与 Milestone 两侧建立或解除同一关联，且不改写 Milestone 状态 | P0 | Releases v1 |
| FR-005 | 删除条目与关联收敛 | 删除后条目与关联不再出现在列表中，重复删除重放首次结果 | P0 | Releases v1 |
| FR-006 | 权限、租户、幂等与并发保护 | 越权、跨 Project、陈旧版本和重复请求都被服务端稳定拒绝或重放 | P0 | Releases v1 |
4.2 明确不做
- 不把 Release 条目解释为 Harbor sealed release artifact、制品、镜像摘要或 TEST/PRODUCTION 部署 evidence。
- 不驱动部署、发布流水线、合并闸门、Runner、环境激活或生产操作，也不作为这些动作的前置条件。
- 不拥有 SemVer、
CHANGELOG.md或 release package 元数据事实源（由 代码托管与独立发布 与 发布流程 拥有）。 - 不改变 Milestone 的交付状态、进度或完成口径，也不让发布动作触发 Milestone 状态变化。
- 不拥有工作项业务状态、生命周期、归档或完成时间（由 生命周期 拥有）。
- 不在本期提供 Release 导出或导入；当前 Plane source 未注册 Release 导出 API 或 UI 入口，导出能力的 owner 是 Workspace 导出，其可用性在本文保持 unknown。
- 不提供跨 Project Release、Release 模板或自动生成、附件与制品存储、通知渠道投递本身。
- 不替代 Plane Automation 的执行事实、控制面状态或运行证据。
- 不把 release 表或 receipt 表当作不可篡改审计或发布证据。
5. 功能需求
5.1 FR-001 按 Project 启用与发现 Releases
用户故事：作为 Project Admin，我希望按 Project 启用 Releases，以便只在需要发布沟通的项目中出现该入口。
前置条件：用户是当前 Workspace 与 Project 的 active 成员，且具备 Project Admin 权限时才可修改启用开关。
主流程：
- Admin 在 Project Settings 的功能列表中启用 Releases。
- 系统把启用状态持久化到 Project 级布尔开关（默认关闭）。
- 启用后 Project 导航出现发布入口，列表页可读取该 Project 的发布条目。
异常与边界：未启用时服务端拒绝创建、修改、删除和关联写入并返回稳定错误，而不只是隐藏按钮；既有 Project 不因本文档自动启用；启用状态本身不产生任何发布条目。
验收标准：
- Given 某 Project 未启用 Releases，When 任何用户提交发布写入，Then 服务端返回稳定“功能未启用”错误且不写入数据。
- Given Admin 启用 Releases，When 成员打开 Project 导航，Then 出现发布入口且列表页可读取当前 Project 的条目。
- Given 另一个 Project 未启用，When 用户访问其发布路由，Then 不展示其它 Project 的条目。
5.2 FR-002 创建与维护 Release 条目
用户故事：作为 Project Admin，我希望创建并维护 Release 条目，以便团队有唯一的发布沟通事实。
前置条件：Releases 已启用；用户具备 Project Admin 权限；写请求携带幂等键，更新与删除请求携带当前 version。
主流程：
- Admin 创建条目，填写名称，并可选填状态、标签、目标日期、实际发布日期、变更日志和负责人。
- 系统在服务端校验名称非空、负责人是当前 Project 的 active 成员，并把条目绑定到当前 Workspace 与 Project。
- Admin 编辑条目时提交当前
version，系统成功后把条目版本加一。 - 列表按状态、目标日期和稳定 ID 排序展示。
异常与边界：名称为 blank 时不得入库；负责人不属于当前 Project 时拒绝；version 缺失或陈旧时拒绝且不覆盖
他人写入；未知枚举状态不得写入；发布描述与变更日志是自由文本，不得用于存放凭据、密钥或内网地址。
验收标准：
- Given Releases 已启用，When Admin 提交带名称与幂等键的创建请求，Then 返回条目与其初始
version，且同一 Project 内只产生一条记录。 - Given 条目当前
version为 n，When Admin 以 n 提交合法更新，Then 更新成功且返回version为 n+1。 - Given 条目已被他人更新，When 用户以陈旧
version提交，Then 服务端拒绝且现有内容保持不变。 - Given 负责字段指向非本项目成员，When 提交更新，Then 服务端拒绝且负责人字段不变。
5.3 FR-003 维护发布范围
用户故事：作为 Project Admin，我希望把工作项加入或移出发布范围，以便范围可见且可调整。
前置条件：Releases 已启用；用户具备 Project Admin 权限；请求携带幂等键、当前 version 和非空的 ID 列表。
主流程：
- Admin 在发布详情提交一个或多个工作项 ID。
- 系统校验每个 ID 属于当前 Project 与 Workspace 且未被删除。
- 系统建立或恢复关联，并把条目
version加一；范围列表按稳定顺序返回。
异常与边界：任一 ID 越界、已删除或属于其它 Project 时整批拒绝且不产生部分关联；重复加入同一工作项不得 产生第二条有效关联；移出未关联的工作项不得报错或制造新版本副作用。
验收标准：
- Given 一个同 Project 工作项，When Admin 提交加入请求两次且幂等键不同但内容相同，Then 只存在一条有效关联且第二次不产生重复。
- Given 请求包含其它 Project 的工作项 ID，When 提交加入请求，Then 服务端拒绝且不写入任何关联。
- Given 已关联的工作项，When Admin 提交移出请求，Then 该工作项不再出现在范围内，且条目
version增加。 - Given 条目被并发更新导致
version陈旧，When 提交范围变更，Then 服务端拒绝且范围不变。
5.4 FR-004 关联 Milestone
用户故事：作为 Project Admin，我希望显式关联 Milestone，以便交付检查点与发布沟通可对照而不互相改写。
前置条件：Releases 已启用；Milestones 可用；用户具备 Project Admin 权限；请求携带幂等键、当前 version 和 Milestone ID。
主流程：
- Admin 在 Release 详情关联一个同 Project Milestone。
- 系统建立关联并把条目
version加一。 - Release 详情展示已关联 Milestone；Milestone 侧读取时返回同一关联。
- Admin 可解除关联，解除后两侧都不再显示该关联。
异常与边界：Milestone 属于其它 Project、已删除或不存在时拒绝；关联与解除都不得改变 Milestone 的状态、 进度或完成口径；从 Milestone 路由提交时必须使用与 URL 一致的 ID 集合。
验收标准：
- Given 一个同 Project Milestone，When Admin 建立关联，Then Release 侧与 Milestone 侧都能读到该关联。
- Given 关联已存在，When Admin 解除关联，Then 两侧都不再返回该关联，且 Release 状态不变。
- Given Milestone 属于其它 Project，When 提交关联请求，Then 服务端拒绝且不写入关联。
- Given 关联变更成功，When 读取 Milestone 详情，Then 其状态与进度与关联前一致。
5.5 FR-005 删除条目与关联收敛
用户故事：作为 Project Admin，我希望删除错误条目且关联自动收敛，以便数据不残留悬空引用。
前置条件：Releases 已启用；用户具备 Project Admin 权限；删除请求携带幂等键与当前 version。
主流程：
- Admin 提交删除请求及当前
version。 - 系统在同一事务内把条目与有效关联置为删除状态，并把条目
version加一。 - 列表与两侧读取不再返回该条目或关联。
异常与边界：version 陈旧时拒绝；重复删除请求按幂等键重放首次结果，不产生第二次副作用；删除后重新提交
同一关联写入必须被拒绝或重放，不得因条目已删除而复活条目。
验收标准：
- Given 条目及其关联存在，When Admin 以当前
version提交删除，Then 条目与关联都不再可读。 - Given 同一次删除请求重复提交，When 使用同一幂等键与相同内容，Then 返回与首次一致的结果且不产生额外写入。
- Given 条目已删除，When 以陈旧
version提交新的写入，Then 服务端拒绝。
5.6 FR-006 权限、租户、幂等与并发保护
用户故事：作为 Project 成员，我希望系统始终按 Workspace、Project、角色和请求版本保护写入，以便发布事实可信。
业务规则：
- 读取要求请求者是当前 Workspace 与 Project 的 active 成员；写入额外要求 Project Admin 角色。
- 所有写入必须绑定当前 Workspace slug 与 Project；跨 Project 或跨 Workspace 引用一律拒绝。
- 每个写请求必须携带非空幂等键；同一 actor、同一 Project、同一幂等键且内容相同返回首次结果，内容不同则拒绝。
- 更新、删除与关联变更必须携带当前
version；陈旧版本拒绝，不允许静默覆盖。 - 拒绝必须以稳定错误码表达，且不得产生部分写入；服务端校验不得只依赖前端隐藏控件。
验收标准：
- Given 一个非 Project Admin 的 active 成员，When 提交创建、更新、删除或关联请求，Then 服务端以权限错误拒绝且不写入。
- Given 同一幂等键先用于内容 A 再用于内容 B，When 提交第二次请求，Then 服务端以幂等冲突拒绝且不修改数据。
- Given 请求中的 Project 与 Workspace 上下文不一致，When 提交写入，Then 服务端以范围错误拒绝。
- Given 同名 Milestone 与 Release 同时存在，When 读取两者，Then 两者身份与状态互不影响。
6. 权限与业务规则
完整矩阵与对象边界由 产品与数据合同 拥有， 本节只固定跨 FR 结论：
| 能力 | Project Admin（role 20） | Project Member（其它 active 角色） | 非成员 / 其它 Workspace |
|---|---|---|---|
| 读取列表与详情 | 允许 | 允许 | 拒绝 |
| 创建、编辑、删除条目 | 允许 | 拒绝 | 拒绝 |
| 维护发布范围与 Milestone 关联 | 允许 | 拒绝 | 拒绝 |
| 启用/停用 Project Releases | 允许 | 拒绝 | 拒绝 |
| 导出 | 当前无导出面（unknown，见 4.2） | 不适用 | 不适用 |
跨 FR 规则：
- Release 身份是稳定 ID，名称、状态、日期与关联变化都不改变身份。
- Release 状态是发布沟通状态，不是工作项状态、Milestone 状态、部署状态或验收结论。
- 发布范围与 Milestone 关联都要求同 Project；同名对象之间没有隐式关系。
- 停用 Releases 只影响功能可用性，不删除既有数据。
7. 非功能需求
| 维度 | 要求 |
|---|---|
| 安全 | 写权限在服务端校验；跨 Project / 跨 Workspace 引用 fail closed；条目自由文本字段不得存放凭据或内网地址 |
| 租户一致 | 所有读写绑定 Workspace slug 与 Project ID；跨租户请求不返回其它 Project 的业务数据 |
| 幂等 | 每个写请求必须带幂等键；重放返回首次记录结果且不产生第二次副作用 |
| 并发 | 以 version 乐观并发控制配合行锁；陈旧写入拒绝，不允许静默覆盖 |
| 失败收敛 | 校验与写入同事务；失败不得留下部分关联、部分范围或半更新条目 |
| 审计 | 记录创建/更新/删除操作者与写入 receipt；receipt 当前不是 append-only，不得当作不可篡改审计或发布证据 |
| 性能 | 列表读取使用服务端分页；条目规模与反馈时延目标待 Producer 与 QA owner 冻结 |
| 兼容 | release_view 默认关闭，既有 Project 不受影响；停用不得删除数据 |
| 可用性 | 未启用、无权限、条目已删除和并发冲突都必须有可判定的用户可见结果 |
8. 数据与埋点
- 数据 owner：Plane 拥有 Release 条目、发布范围、Milestone 关联与写入 receipt 的持久化事实；本文档只保存 稳定语义与边界，不复制字段实现正文。
- 不新增采集结论：本期不新增客户端埋点或第三方分析事件；成功指标取自服务端持久化表与写入 receipt。 若后续需要客户端埋点，事件名、属性、触发时机、观察窗口和看板 owner 由 Producer 与数据 owner 在进入批准 评审前确定。
9. 整体验收标准
- 未启用 Releases 的 Project 无法通过 API 写入发布数据，启用后 Admin 可完成“创建条目、维护范围、关联 Milestone、更新状态与日期、删除条目”的完整闭环。
- 所有负向路径（越权、跨 Project、未启用、陈旧版本、幂等冲突、无效载荷）都返回稳定错误码且不产生部分写入。
- 重复提交同一幂等键与相同内容时返回与首次一致的结果，不产生重复条目或重复关联。
- Release 与 Milestone 状态的独立性、Release 条目与 Harbor sealed release artifact / 部署 evidence 的边界，在 文档、权限矩阵和数据模型中保持可区分。
- 上述结论必须由 owning Plane revision 与正式测试 locator 的受保护运行证据支持；文档构建成功不作为功能验收。
10. 发布计划
- 本文档交付只提升 canonical 文档：fresh-base branch、commit、push、MR，由外部 CI 执行 catalog、navigation、 contract、deployment、build 与 experience 验证，最终由 Producer 审核。
- 本文档不启用任何 Project 功能开关、不写 Plane 业务数据、不注册 Runner、不改凭据或权限、不执行 TEST 或 PRODUCTION 操作。
- Development / Verification / Release Ready 由文档仓 catalog 依据固定资产与关系派生；本文不手工声明绿色，
当前
PLN资产清单未登记 Release 实现定位，因此相关 gate 由派生结果表达缺口。 - 需要服务端行为收敛的后续切片（状态转换约束、权限粒度、receipt 不可篡改性、跨 Project 探测响应一致性）由 PLN owner 在独立 implementation MR 中完成并另行验证。
11. 依赖与风险
| 类型 | 风险或依赖 | 产品影响 | 处理原则 |
|---|---|---|---|
| 依赖 | Plane Project 级 release_view 开关与 Project 权限模型 | 决定入口可见性与写入权限 | 以固定 PLN revision 的实现为准，收敛前不得扩大权限 |
| 依赖 | Milestone 对象与 Milestone 双向关联读模型 | 决定发布与交付检查点对照能力 | 关联不改写 Milestone 状态；Milestone 合同由其 canonical 入口拥有 |
| 风险 | 把 Release 条目读成部署或制品证据 | 发布结论被文档代签 | 本文与关联页面显式声明边界；部署证据只来自 owning release surface |
| 风险 | 自由文本字段写入敏感信息 | 凭据或内网信息进入业务数据 | 文档明示禁止；安全评审补充检查点 |
| 风险 | 状态语义漂移 | 同名状态被不同团队解释 | 只有三个稳定状态值；变更语义必须走版本化文档变更 |
| 风险 | 跨 Project 探测可区分对象存在性 | 轻微信息泄露 | 列为待确认事项，由 PLN owner 收敛为一致响应 |
12. 待确认事项
| 待确认事项 | 决策人 | 最迟完成时间与影响 |
|---|---|---|
是否收窄状态转换为 unreleased 只能进入 released 或 cancelled | Producer / PLN owner | Development Ready 前；阻塞状态合同冻结 |
| Release 写权限是否保持 Project Admin 独占，是否引入只读 Guest 例外 | Producer / PLN owner | Development Ready 前；阻塞权限矩阵冻结 |
| 是否提供 Release 导出或报表能力及其 owner | Producer / 数据 owner | 后续规划评审；不影响本期只读与写入闭环 |
| 成功指标的观察窗口、环境、负载与无效样本边界 | Producer / QA owner | Verification 计划冻结前；阻塞指标验收 |
| 写入 receipt 是否需要 append-only 或不可篡改保证 | Producer / 安全 owner | 进入审计合同前；阻塞“审计证据”措辞升级 |
| 跨 Project 请求是否统一为不可区分响应 | 安全 owner / PLN owner | Development Ready 前；阻塞安全 NFR 冻结 |
| 是否允许 Release 关联多个 Milestone 的稳定顺序与上限 | Producer | 后续版本评审；不影响单关联闭环 |