HarborForge/docs/propose-flow.md

HarborForge — Propose → Feature Story → Milestone 流程

更新时间：2026-03-18 本文档描述 feature 进入 milestone 的完整流程。

---

1. 流程总览

用户创建 Propose          负责人审阅            系统自动生成
     │                      │                     │
     ▼                      ▼                     ▼
  Propose (open)  ──accept──▶  Propose (accepted)
                     │                │
                     │                ▼
                     │         Feature Story Task (pending)
                     │              归属选定 milestone
                     │
                  ──reject──▶  Propose (rejected)
                                    │
                               ──reopen──▶  Propose (open)  ── 重新审阅 ──▶ ...

---

2. 详细步骤

Step 1：创建 Propose

• 用户在 project 下创建 propose
• 填写 title + description
• 系统自动生成 propose_code（格式：{proj_code}:P{i:05x}）
• 初始状态：open

Step 2：审阅

• 负责人在 Propose 详情页查看内容
• open 状态下可选操作：
  • Accept — 接受并生成 feature task
  • Reject — 拒绝（建议填写 reason）
• Propose 创建者在 open 状态下可编辑 title/description

Step 3a：Accept

前置条件：

• 操作者拥有 propose.accept 权限
• 选择一个 open 状态的目标 milestone（同 project）

系统执行：

1. Propose status → accepted
2. 在目标 milestone 下自动创建 story/feature task
   • 继承 title、description、created_by
   • 默认状态 pending
3. 自动回填 feat_task_id（只读字段）
4. 写入 activity log

Accept 后：

• Propose 详情页显示 "View Generated Task" 跳转按钮
• Propose 主体不可再编辑

Step 3b：Reject

前置条件：

• 操作者拥有 propose.reject 权限

系统执行：

1. Propose status → rejected
2. 写入 reject reason（activity log）

Reject 后：

• Propose 详情页显示 "Reopen" 按钮
• Propose 主体不可编辑

Step 4：Reopen（可选）

前置条件：

• 操作者拥有 propose.reopen 权限
• Propose 当前状态为 rejected

系统执行：

1. Propose status → open（复用原 propose，不创建新记录）
2. 写入 reopen 记录

Reopen 后：

• 可再次编辑 title/description
• 可再次 accept 或 reject

---

3. Feature Task 生命周期

Accept 生成的 feature story task 遵循标准 task 状态机：

pending → open → undergoing → completed
                                 │
                          (触发 milestone auto-complete
                           仅当该 task 是 release task 时)

关键约束：

• Feature story task 不能通过通用 create task 页面创建
• Milestone 进入 freeze 后，不再接受新的 feature story
• Milestone 非 open 时，已有 feature story task 的 body 字段锁定

---

4. Milestone 完整生命周期（含 propose）

1. 创建 milestone (open)
2. 通过 propose → accept 添加 feature story tasks
3. 创建 release maintenance task（通过 milestone endpoint）
4. Freeze milestone（需有且仅有 1 个 release task）
5. 满足依赖后 Start milestone → undergoing
6. Tasks 开始执行（pending → open → undergoing → completed）
7. Release maintenance task 完成 → milestone 自动 completed

---

5. Propose 编码规则

• 格式：{proj_code}:P{i:05x}
• 示例：HF:P00001, HF:P00002, HF:P0000a
• 每个 project 独立递增
• 并发安全：数据库 unique 约束保底

---

6. API 端点

操作	方法	路径
创建	POST	/projects/{pid}/proposes
列表	GET	/projects/{pid}/proposes
详情	GET	/projects/{pid}/proposes/{id}
编辑	PATCH	/projects/{pid}/proposes/{id}
Accept	POST	/projects/{pid}/proposes/{id}/actions/accept
Reject	POST	/projects/{pid}/proposes/{id}/actions/reject
Reopen	POST	/projects/{pid}/proposes/{id}/actions/reopen

---

7. CLI 命令

# 列出 proposes
harborforge proposes --project <project_id>

# 创建 propose
harborforge propose-create "My Feature Idea" --project <project_id>

# Accept（需指定 milestone）
harborforge propose-accept <propose_id> --project <project_id> --milestone <milestone_id>

# Reject（可选 reason）
harborforge propose-reject <propose_id> --project <project_id> --reason "Not in scope"

# Reopen
harborforge propose-reopen <propose_id> --project <project_id>