# HarborForge — 权限总览

> 更新时间：2026-03-18
> 本文档列出 milestone-propose 功能新增的所有权限，以及默认角色分配。

---

## 1. 新增权限一览

| 权限名                   | Category   | 含义                          |
|--------------------------|------------|-------------------------------|
| `milestone.freeze`       | milestone  | 将 milestone 从 open 冻结为 freeze |
| `milestone.start`        | milestone  | 将 milestone 从 freeze 启动为 undergoing |
| `milestone.close`        | milestone  | 将 milestone 废弃（close）      |
| `task.close`             | task       | 将 task 废弃（close）            |
| `task.reopen_closed`     | task       | 重新打开已废弃的 task             |
| `task.reopen_completed`  | task       | 重新打开已完成的 task             |
| `propose.accept`         | propose    | 接受 propose 并生成 feature task  |
| `propose.reject`         | propose    | 拒绝 propose                    |
| `propose.reopen`         | propose    | 重新打开已拒绝的 propose          |

---

## 2. 默认角色权限分配

### admin（管理员）

拥有**所有权限**，包括上述 9 个新权限。通过 `init_admin_role()` 自动同步。

### mgr（经理）

| 权限             | 有 |
|-----------------|----|
| milestone.freeze | ✓ |
| milestone.start  | ✓ |
| milestone.close  | ✓ |
| task.close       | ✓ |
| task.reopen_closed | ✓ |
| task.reopen_completed | ✓ |
| propose.accept   | ✓ |
| propose.reject   | ✓ |
| propose.reopen   | ✓ |

另含：project.read/write/manage_members, task.create/read/write, milestone.create/read/write, monitor.read

### dev（开发者）

| 权限             | 有 |
|-----------------|----|
| milestone.freeze | ✗ |
| milestone.start  | ✗ |
| milestone.close  | ✗ |
| task.close       | ✓ |
| task.reopen_closed | ✓ |
| task.reopen_completed | ✓ |
| propose.accept   | ✗ |
| propose.reject   | ✗ |
| propose.reopen   | ✗ |

另含：project.read, task.create/read/write, milestone.read, monitor.read

### guest（访客）

仅 `*.read` 权限，无新增权限。

---

## 3. 权限设计原则

1. **独立不合并**：`reopen_closed` 和 `reopen_completed` 是两个独立权限，允许不同角色分别控制
2. **增量同步**：角色种子系统只做"加权限"，不删除手动配置的额外权限
3. **操作者校验**：部分动作除权限外还校验操作者身份
   - `open → undergoing`：操作者必须是 assignee
   - `undergoing → completed`：操作者必须是 assignee + 需提交 comment
   - `completed` 不走 role 权限控制，而是由 assignee 身份决定

---

## 4. 前端可见性（当前状态）

> ⚠ 前端按钮当前对所有项目成员可见，尚未根据用户权限做细粒度隐藏。
> 权限不足时由后端返回 403 阻止操作。

后续可通过前端 permission context 实现按钮可见性控制。

---

## 5. 自定义角色

除默认角色外，管理员可通过 Role Editor 页面自由创建角色并分配上述权限。新增的 9 个权限按 `milestone` / `task` / `propose` 三个 category 分组展示。