docs(P12.2-P12.3): add state machine overview, permissions overview, and propose flow documentation
This commit is contained in:
163
docs/propose-flow.md
Normal file
163
docs/propose-flow.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 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 命令
|
||||
|
||||
```bash
|
||||
# 列出 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>
|
||||
```
|
||||
Reference in New Issue
Block a user