数据、状态与 API
- Asset
- ADP-PLN-DOC-DOC-0002
- Feature
- milestones
- 领域
- plane-core
- 文档状态
- draft
- 文档 Owner
- DOC
- 事实源
- canonical-docs
- 更新
- 2026/10/14
原生对象与人工验收
db.ProjectMilestone 保留身份、标题、日期、外部身份及 version。Work Item、Cycle、Module assignment API、
有效归属与冲突规则由原生 milestone domain 持有。没有 ProjectPlan、VersionIssueLink 或版本派生范围的活动模型。
automation.MilestoneDelivery 是现有里程碑的一对一人工验收记录，保存 revision、contract、evidence、
cancelled 和 accepted_digest；不承载路线图或版本流程。contract 仅包含 exit_criteria、depends_on、
owner_id、reviewer_id 和 references；不保存 objective/scope/non_goals 的第二份规划正文。
MilestoneDeliveryReview 保存不可变的决定、actor、note、revision 和当时 snapshot。
API
项目业务前缀为 /api/workspaces/{slug}/projects/{project_id}/：
| 路径与操作 | 合同 |
|---|---|
milestone-acceptance/ GET | 读取原生里程碑验收汇总及有效人类成员 |
milestones/{id}/acceptance/ GET | 读取当前验收条件、证据、digest、阻塞和决定 |
milestones/{id}/acceptance/preview/ POST | 校验候选条件，返回 before/after、原生 scope 和 digest |
milestones/{id}/acceptance/configure/ POST | Admin 提交 expected_revision、preview_digest、contract 和 note |
milestones/{id}/acceptance/set_evidence/ POST | 人类成员提交 expected_revision、逐项 criteria 观察/URL、summary 和 note |
milestones/{id}/acceptance/accept/ POST | 指定 reviewer 提交 expected_revision、当前 snapshot digest 和 note |
milestones/{id}/acceptance/request_changes/ POST | 指定 reviewer 退回并保留决定 |
milestones/{id}/acceptance/cancel/ POST | Admin 取消；原生范围必须无未完成工作 |
history-archive/ GET | 读取项目历史规划、批准及一次性迁移摘要 |
写入要求独立 Idempotency-Key、精确 payload、expected_revision、项目身份和人类成员校验。
锁沿 Workspace hierarchy、Project 和 milestone domain 取得；预览与验收摘要在事务中重算。
回执使用 milestone.acceptance scope，响应丢失重放同一结果，不重复审计。
旧 /planning/ 及其所有子路径删除，不保留 alias、fallback 或旧字段映射。
文档引用
references 最多 50 个；包含 repo_key、完整 40 位 commit、相对 path、64 位 sha256 和 purpose。 路径不能绝对、回退或包含空段。Plane 保存固定来源身份和验收记录；正文由指定仓库持有。 实际人类审阅必须核对来源和证据；URL 或格式正确不代表内容通过验收。
一次性归档与范围迁移
migration 0099 在同一事务内归档最终计划、产物、审核、版本成员映射及 project.planning 命令回执，
然后删除 live planning tables。PlanningRetirement: namespace 保留最终修订，早期 Run/Epic 快照不覆盖。
活动版本成员及活动子项改为直接原生里程碑归属，写 native activity；直接/Cycle/Module 冲突导致整个迁移中止。
Issue ID、名称、正文、parent 和业务状态保留。软删除和退役映射只保留历史，不重新启用。
旧里程碑合同和审核也归档。当前合同移除规划正文，保留来源、标准、责任、依赖和证据；清空验收指纹并增加 scope_migrated 审计。已有决定不会自动变成新范围验收。按项目归档 Summary 保存实际归档数量和转换数量。 迁移不可逆，只能通过 protected TEST-to-PRODUCTION release 执行，不使用本地数据库补丁。