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