HarborForge/docs/permissions-overview.md

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 分组展示。