186 lines
6.6 KiB
Markdown
186 lines
6.6 KiB
Markdown
# 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`|
|