# 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`|