Pages · 需求与数据合同
- Asset
- ADP-PLN-DOC-DOC-0008
- Feature
- pages
- 领域
- plane-core
- 文档状态
- draft
- 文档 Owner
- DOC
- 事实源
- canonical-docs
- 更新
- 2026/10/14
本文承载 Pages PRD 的数据、API 和受管 Automation target 细节，不复制
产品背景、范围或发布决策。原子 REQ / AC 与正式 TEST Asset 尚待 PLN、DOC 和 QA owner 登记，因此本页保持
draft。
PRD 追踪草案
| PRD 功能 | 本页合同 | 仍缺少 |
|---|---|---|
FR-001 Page Tree 与面包屑 | Page 关系、读取模型、稳定 URL | 原子 REQ / AC / TEST |
FR-002 创建根 Page 与子 Page | parent、Project 与权限校验 | 原子 REQ / AC / TEST |
FR-003 移动与同级排序 | move command、无环、同级排序和版本 | 原子 REQ / AC / TEST |
FR-004 身份、权限与关系保护 | 关系约束、原子失败和资源身份 | 原子 REQ / AC / TEST |
FR-005 受管 Spec Page | 冻结 target、typed result 与服务端 applicator | 首版范围决策、原子 REQ / AC / TEST |
Page 关系与身份
| 领域 | 产品合同 | Owner |
|---|---|---|
| Page 关系 | Page 保留 Project 归属和可选 parent；根 Page 的 parent 为空，一个 Page 最多一个直接父级 | Plane 产品数据模型与服务 |
| 同级排序 | 同一 parent 下以 sort_order 表示稳定顺序；未指定位置时追加到末尾 | Plane 读写 API / service |
| 关系校验 | 创建或移动校验 Project、权限、父级存在性、非自引用和无环性；失败不得部分写入 | Plane 读写 API / service |
| 资源身份 | Page 的直达 URL 使用 Page ID；名称、祖先和移动不改变身份 | Plane 路由与 UI |
Page 可同时承载文档内容和子 Page。Page.parent 是 Page 间关系，不建立第二套 Folder 资源、Folder table 或
document/folder 类型。
读取与移动合同
| API | 产品合同 |
|---|---|
GET /pages/ | 默认只返回当前 Project 中用户可见的根 Page；include_descendants=true 返回有权访问的完整 flat Page list，结果包含稳定 ID、parent 和 sort_order，由 UI 构建树与祖先链 |
POST /pages/{pageId}/move/ | 接收 { parent_id: uuid|null, before_id?: uuid|null, after_id?: uuid|null }；before_id 与 after_id 互斥，且定位 Page 必须与目标 parent 同级 |
- 创建和移动必须校验源、目标、Project、用户权限、当前资源版本和完整 parent graph。
- 并发版本冲突返回稳定错误，不覆盖更新后的 parent 或排序。
- API Schema 的最终错误结构和版本控制字段由 Plane owner 固化；等价实现不得破坏上述公共行为。
旧受管 Spec Page 退役
Epic 绑定的生成 Spec、冻结 Page target、Run Result applicator 和专用关联不再是活动合同。已有 Page 与历史产物保留普通只读/编辑权限；需求方案由 OpenSpec 管理，不建立 Plane Page 副本或 Epic 影子审批。通用 Page 树、权限和移动合同不变。
非目标
- 不生成或解析可读 slug/path URL。
- 不新增 Folder 或 wiki engine。
- 不规定缓存、前端组件拆分或批量加载的实现算法。
- 不通过 Page 层级推导 Project access。
- 不让 Automation 持有 Page 通用写凭据。