HarborForge/docs/state-machine-overview.md

HarborForge — 状态机总览

更新时间：2026-03-18 本文档描述 milestone、task、propose 三大实体的状态枚举、流转规则及关键约束。

---

1. Milestone 状态机

1.1 状态枚举

状态	含义	终态
open	新建，可接纳 feature	✗
freeze	范围冻结，准备执行	✗
undergoing	正在执行	✗
completed	正常完成（自动触发）	✓
closed	废弃 / 取消	✓

1.2 状态流转

open ──freeze──▶ freeze ──start──▶ undergoing ──(auto)──▶ completed
  │                │                    │
  └──close──▶ closed ◀──close──┘ ◀──close──┘

• open → freeze：需有且仅有 1 个 maintenance/release task
• freeze → undergoing：所有前置依赖（milestone + task）必须已 completed；自动记录 started_at
• undergoing → completed：唯一的 release maintenance task 完成时自动触发
• open/freeze/undergoing → closed：需 milestone.close 权限

1.3 编辑限制

状态	基本信息编辑	新增 feature story	新增其他 task	删除 milestone
open	✓	✓	✓	✓
freeze	范围字段锁定	✗	✓	✓
undergoing	范围字段锁定	✗	✗	✗
completed	✗	✗	✗	✗
closed	✗	✗	✗	✗

范围字段 = title, description, due_date, planned_release_date, depend_on_milestones, depend_on_tasks

---

2. Task 状态机

2.1 状态枚举

状态	含义	终态
pending	等待（被 milestone 或依赖锁住）	✗
open	可开始，尚未开工	✗
undergoing	正在处理	✗
completed	正常完成	✓*
closed	废弃 / 取消	✓*

*支持受控 reopen

2.2 状态流转

pending ──open──▶ open ──start──▶ undergoing ──finish──▶ completed
  │                │                   │                    │
  └──close──▶ closed ◀──close──┘ ◀──close──┘               │
       │                                                    │
       └◀────────────── reopen ──────────────────────────────┘
                          ▲
                          └──────────── reopen ──── completed

2.3 流转条件

流转	条件
pending → open	milestone 为 undergoing + task depend_on 全部 completed
open → undergoing	assignee 非空 + 操作者是 assignee
undergoing → completed	操作者是 assignee + 必须提交 completion comment
any → closed	需 task.close 权限
closed → open	需 task.reopen_closed 权限；清除 finished_on
completed → open	需 task.reopen_completed 权限；清除 finished_on

2.4 编辑限制

状态	主体编辑
pending	✓
open (无 assignee)	✓ (任何项目成员)
open (有 assignee)	仅 assignee + admin
undergoing	✗
completed	✗
closed	✗

Feature story task 在 milestone 非 open 时，body 字段额外锁定。

2.5 与 Milestone 联动

• milestone open/freeze → task 只能停留在 pending 或 closed
• milestone undergoing → task 才允许从 pending 往后推进
• milestone completed/closed → task 不再继续推进

---

3. Propose 状态机

3.1 状态枚举

状态	含义	终态
open	新建/待审	✗
accepted	已接受	✓
rejected	已拒绝	✓*

*支持 reopen

3.2 状态流转

open ──accept──▶ accepted
  │
  └──reject──▶ rejected ──reopen──▶ open

3.3 流转条件

流转	条件
open → accepted	需 propose.accept 权限 + 选择 open 状态的目标 milestone
open → rejected	需 propose.reject 权限；建议填写 reason
rejected → open	需 propose.reopen 权限；复用原 propose

3.4 Accept 副作用

• 自动创建 story/feature task（继承 title/description/created_by）
• 新 task 默认状态 pending
• 自动填写 feat_task_id（只读）

3.5 编辑限制

状态	主体编辑
open	✓ (creator / admin / mgr)
accepted	✗
rejected	✗

---

4. 创建限制

以下 task 类型不能通过通用 create task 页面创建：

类型	正确创建入口
story/feature	propose → accept
maintenance/release	milestone endpoint

---

5. 旧枚举映射（DB 迁移）

Milestone

旧值	新值
open	open
pending	open
deferred	closed
progressing	undergoing
closed	closed

Task

旧值	新值
open	open
pending	pending
progressing	undergoing
closed	closed

Task Type

旧值	新值
task	issue