Pages 产品需求文档（PRD）
1. 文档信息
| 项目 | 内容 |
|---|---|
| 文档版本 | V0.1 |
| 文档状态 | 草案（Draft） |
| 产品负责人 | Producer（范围、优先级和体验决策） |
| 文档负责人 | DOC |
| 评审人 | PLN、设计与 QA owner |
| 目标版本 | Pages v1；发布日期待确认 |
| 适用范围 | Project 内 Page 的树形组织、导航、创建、移动和受管 Spec Page |
1.1 变更记录
| 版本 | 日期 | 修改人 | 变更说明 |
|---|---|---|---|
| V0.1 | 2026-09-15 | DOC | 将既有 Pages 产品合同整理为标准 PRD 草案，并把交互、数据/API 和验证细节拆入关联文档 |
本文只定义 Pages 的产品问题、范围、用户行为和验收结果。数据/API 字段、详细交互与测试步骤由关联文档拥有。
2. 背景与目标
2.1 背景
Project 内的 Page 既承载协作文档，也需要按主题形成可导航层级。如果层级依赖 URL、额外 Folder 实体或外部 wiki 模型，用户会面对资源身份变化、文档与容器二选一以及权限边界不一致等问题。
Pages v1 以同一 Page 实体组成树：Page 可以同时拥有内容和子 Page，层级由 Page.parent 表示，资源身份始终
由 Page ID 保持稳定。
2.2 用户问题
| 用户问题 | 用户影响 | 产品需要提供的结果 |
|---|---|---|
| 内容缺少稳定层级 | 用户难以从 Project 入口定位相关 Page | 展示可展开的 Page Tree 和祖先面包屑 |
| 文档与容器被拆成不同对象 | 用户需要额外维护 Folder 或空目录页 | 同一个 Page 同时支持内容与子级 |
| 移动层级可能改变链接 | 已分享入口或业务关联失效 | 移动后继续使用不变的 Page ID URL |
| 非法移动可能形成跨 Project 引用或环 | 树无法遍历并可能越权泄露 | 所有移动在写入前校验 Project、权限和无环约束 |
| Automation 生成的 Spec 缺少受管目标 | 可能生成重复页面或写入错误对象 | Plane 预先绑定唯一 Page target 并在服务端校验结果 |
2.3 产品目标
- 用户可以在 Project 内浏览根 Page 与子 Page，并通过面包屑返回任一可见祖先。
- 有权用户可以创建根 Page、创建子 Page、移动 Page 和调整同级顺序。
- Page 移动只改变树关系和排序，不改变 Page 身份或直达 URL。
- 系统拒绝跨 Project、自引用、后代成环、越权和错误同级定位的移动请求。
- 受管 Automation Spec 始终写入 Plane 预先绑定的 Page，不允许执行端自行选择目标。
2.4 成功指标
以下为草案测量框架。涉及体验时延、树规模和观察窗口的目标尚未冻结，不能据此宣称已达到发布门。
| 指标 | 计算口径 | 草案目标 |
|---|---|---|
| 核心任务闭环率 | 无需修改 URL 或创建额外 Folder 即完成创建、导航或移动的有效任务数 / 同类任务数 | 目标待 Producer 确认 |
| 稳定链接保持率 | 移动后仍能通过原 Page ID URL 打开的 Page 数 / 成功移动 Page 数 | 100% |
| 非法关系写入数 | 被持久化的跨 Project、自引用或成环 parent 关系数 | 0 |
| 权限泄露数 | 树或面包屑向用户暴露无权访问 Page 身份或内容的事件数 | 0 |
| 受管 Spec 目标一致率 | 服务端校验通过且写入冻结 Page target 的 Spec 结果数 / 成功应用的 Spec 结果数 | 100% |
| 树操作反馈时延 | 页面提交创建或移动至显示成功、失败或冲突结果的时间 | P95 目标、负载和浏览器矩阵待确认 |
指标事实来自 Plane 持久化关系、权限检查、服务端审计事件和浏览器端到端观测。目标环境、树规模、统计窗口及 无效样本边界由 Producer、PLN 与 QA owner 在进入批准评审前确定。
3. 用户与使用场景
3.1 目标用户
| 用户 | 核心任务 | 权限边界 |
|---|---|---|
| Page 读者 | 浏览树、打开 Page、沿面包屑定位内容 | 只能看到有权访问的 Project 和 Page |
| Page 编辑者 | 创建、编辑、移动和排序 Page | 必须同时满足 Project 与目标位置的写权限 |
3.2 用户故事
- 作为 Page 读者，我希望沿树和面包屑定位内容，以便理解当前 Page 在 Project 中的位置。
- 作为 Page 编辑者，我希望创建根 Page 或子 Page，以便用一个既可写内容又可容纳子级的对象组织知识。
- 作为 Page 编辑者，我希望移动 Page 并调整顺序，同时保持分享链接不变。
3.3 核心场景
- 从 Project Pages 树打开一个根 Page 或子 Page。
- 在当前 Page 下创建子 Page，或在根级创建 Page。
- 把 Page 移到新的父级、根级或同级指定位置。
- 从面包屑返回某个可见祖先。
4. 产品范围
4.1 本期候选范围
| 编号 | 功能 | 用户结果 | 优先级 | 目标版本 |
|---|---|---|---|---|
| FR-001 | Page Tree 与面包屑 | 用户可以浏览有权访问的 Page 层级并返回祖先 | P0 | Pages v1 |
| FR-002 | 创建根 Page 与子 Page | 编辑者可以在合法位置创建 Page | P0 | Pages v1 |
| FR-003 | 移动与同级排序 | 编辑者可以调整 parent 和同级位置，且链接不变 | P0 | Pages v1 |
| FR-004 | 身份、权限与关系保护 | 非法或越权请求被拒绝且不产生部分写入 | P0 | Pages v1 |
| FR-005 | 受管 Spec Page | Epic 专用路径已退役，历史产物保留 | 退役 | 不再实施 |
4.2 明确不做
- 不提供可读 slug/path URL，不把面包屑解释为可解析资源路径。
- 不新增 Folder table，不建立 document/folder 双模型，也不引入 wiki engine。
- 不让树层级替代 Project 权限或成为权限继承机制。
- 不在本期定义删除或归档包含子级 Page 的最终策略。
- 不承诺跨 Project 复制或迁移 Page Tree。
- 不允许 Automation 执行端自行选择 Page、标题、URL 或扩大 Page 写权限。
5. 功能需求
5.1 FR-001 Page Tree 与面包屑
用户故事：作为 Page 读者，我希望看到当前 Project 的 Page Tree 和当前 Page 的祖先链，以便快速定位内容。
前置条件：用户可以访问当前 Project 及相应 Page。
主流程：
- 用户进入 Project Pages，页面展示其有权访问的根 Page 与后代。
- 用户展开树或打开 Page，页面显示从 Project Pages 根到当前 Page 的面包屑。
- 用户选择可见祖先，系统通过该祖先的 Page ID URL 打开页面。
异常与边界：树和面包屑不得通过祖先名称、数量或占位节点泄露无权访问的 Page；折叠和展开不改变树关系。
验收标准：
- Given Project 中存在多层 Page，When 有权用户打开子 Page，Then 页面展示可见祖先链并允许返回任一可见祖先。
- Given 用户无权访问某个 Page，When 系统构建树和面包屑，Then 不展示该 Page 的身份或内容。
5.2 FR-002 创建根 Page 与子 Page
用户故事：作为 Page 编辑者，我希望在根级或现有 Page 下创建 Page，以便组织协作文档。
前置条件：用户拥有当前 Project 和目标父级所需的写权限。
主流程：
- 用户选择根级或一个当前 Page 作为创建位置。
- 系统校验 Project、权限和父级有效性。
- 系统创建 Page，并在树与面包屑中展示新位置。
异常与边界：父级不存在、属于另一 Project 或用户无权访问时不创建 Page；已有子级的 Page 仍可承载内容。
验收标准：
- Given 用户有权编辑 Project，When 在根级创建 Page，Then 新 Page 作为根节点出现并可写入内容。
- Given 用户选择同 Project 的可写 Page，When 创建子 Page，Then 新 Page 的 parent 指向该 Page，父 Page 仍可显示自身内容。
- Given 目标父级无效或越权，When 用户提交创建，Then 系统拒绝请求且不产生 Page。
5.3 FR-003 移动与同级排序
用户故事：作为 Page 编辑者，我希望移动 Page 或调整同级顺序，以便维护清晰的内容结构。
前置条件：用户有权修改 Page，并可访问目标父级和定位 Page。
主流程：
- 用户选择新的父级、根级或同级 before/after 位置。
- 系统校验目标属于同一 Project、不会形成环且定位 Page 与目标同级。
- 系统原子更新 parent 和同级顺序，刷新树与面包屑。
异常与边界：不得移动到自身或后代之下；before 与 after 互斥；并发版本冲突不得覆盖更新后的关系。
验收标准：
- Given 合法目标位置，When 用户移动 Page，Then 树、排序和面包屑更新，原 Page ID URL 仍可打开同一 Page。
- Given 目标是自身、后代、另一 Project 或错误同级定位，When 用户提交移动，Then 系统拒绝且原关系保持不变。
5.4 FR-004 身份、权限与关系保护
用户故事：作为 Project 成员，我希望系统始终保持正确的 Page 身份和权限边界，以便可信地分享和浏览内容。
业务规则：
- 一个 Page 最多有一个直接 parent，根 Page 的 parent 为空。
- parent 与 child 必须属于同一 Project，关系必须无环。
- Page ID 是资源身份；名称和祖先变化不改变直达 URL。
- 创建或移动必须在同一操作中完成校验与写入，失败不得留下部分关系或部分排序。
- Page Tree 不授予或扩大 Project 访问权限。
验收标准：
- Given 任一 Project、权限、父级或版本校验失败，When 系统处理创建或移动，Then 请求 fail closed 且不产生部分写入。
- Given Page 已被移动或重命名，When 用户访问原 Page ID URL，Then 打开同一 Page。
5.5 FR-005 受管 Spec Page（退役）
Epic 专用生成与绑定流程删除。旧产物保留历史引用，需求方案转由 OpenSpec 管理；本 FR 不作为当前实现或验收要求。通用 Page 功能不受影响。
6. 权限与业务规则
| 操作 | 权限要求 | 附加规则 |
|---|---|---|
| 浏览树与面包屑 | 可访问当前 Project 与 Page | 只返回可见节点和祖先信息 |
| 创建 Page | Project 与目标位置写权限 | 父级必须属于同一 Project |
| 移动或排序 | 源 Page 和目标位置写权限 | 无环、版本和同级定位校验 |
Page Tree 只负责组织和导航，不创建新的成员、角色或权限继承关系。
7. 非功能需求
- 一致性：创建与移动的关系、排序和审计必须原子提交；冲突不得静默覆盖。
- 安全：Project 隔离和 Page 权限 fail closed；页面及 API 不泄露不可见祖先。
- 可访问性：树、移动入口和面包屑需要支持键盘操作及明确焦点；具体矩阵由设计和 QA owner 确认。
- 性能：树加载和移动反馈必须具备可测目标；最大树规模、P95 目标和分页/增量策略尚待确认。
- 兼容性：移动与重命名不得改变 Page ID URL；不新增 path URL 兼容层。
8. 数据与埋点
产品指标至少需要区分树加载、Page 创建、移动成功、移动拒绝、面包屑跳转和受管 Spec 应用结果。事件名称、 字段、保留周期和数据看板 owner 尚待确认；埋点不得记录无权访问的祖先名称或 Page 内容。
权威产品事实仍是 Plane 的 Page、parent、sort order、权限检查和服务端审计，前端埋点不能替代关系真相。
9. 整体验收标准
- 用户可以完成“进入树 → 打开子 Page → 沿面包屑返回祖先”的可访问闭环。
- 编辑者可以完成“创建 → 移动 → 调整同级顺序”，且 Page ID URL 始终不变。
- 跨 Project、自引用、后代成环、越权、错误同级和并发版本冲突均被拒绝且零部分写入。
- Page 可以同时显示内容和子级，不产生 Folder 或 document/folder 双模型。
- 受管 Spec 启用时，只能更新 Plane 冻结并校验的同一 Project Page target。
10. 发布计划
| 项目 | 草案计划 |
|---|---|
| 首个切片 | FR-001 至 FR-004；FR-005 是否随首版交付待 Producer 确认 |
| 灰度 | 先在受控 Project 验证多层树、移动冲突和权限负向场景，再扩大范围 |
| 上线条件 | 本期 FR 验收通过；树规模和体验指标锁定；设计、权限和测试证据齐备 |
| 产品回退 | 关闭新增移动/树入口不得删除 Page、关系、内容或审计；技术回滚由实施文档定义 |
| 日期 | 待排期，不改变已冻结的产品边界 |
11. 依赖与风险
| 类型 | 风险或依赖 | 产品影响 | 处理原则 |
|---|---|---|---|
| Plane 数据模型 | parent、排序和版本能力尚需实现证据 | 树可能不一致或移动被覆盖 | 以数据库约束、事务与正式测试证明 |
| 权限 | 不可见祖先参与树构建 | 泄露 Page 身份或内容 | 服务端按当前用户过滤并 fail closed |
| 并发 | 多用户同时移动同一或相邻 Page | 排序丢失或形成错误关系 | 使用版本冲突和原子关系更新 |
| 大树体验 | 未锁定规模与加载策略 | 页面延迟或操作困难 | 在发布前确定目标规模、时延和体验方案 |
| Automation | target 或结果合同不一致 | 写入错误 Page 或产生重复 Spec | 由 Plane 预绑定并在服务端 exact 校验 |
12. 待确认事项
| 待确认事项 | 决策人 | 最迟完成时间与影响 |
|---|---|---|
| FR-005 是否进入 Pages v1 首个发布切片 | Producer | 范围评审前；影响首版范围，不影响 FR-001 至 FR-004 合同 |
| 删除或归档包含子级 Page 的策略 | Producer / PLN owner | 相应功能进入开发前；当前不在本期范围 |
| 最大树规模、加载策略和创建/移动反馈 P95 | Producer / PLN / QA owner | Development Ready 前；阻塞性能验收 |
| 浏览器、桌面/移动端及键盘验收矩阵 | 设计 / QA owner | Verification 计划冻结前；阻塞体验验收 |
| 埋点名称、字段、观察窗口与看板 owner | Producer / 数据 owner | 开发完成前；阻塞成功指标验收 |
| 跨 Project 复制或迁移是否进入后续版本 | Producer | 后续规划评审；不影响 Pages v1 |