docs(P12.2-P12.3): add state machine overview, permissions overview, and propose flow documentation

docs/permissions-overview.md

@@ -0,0 +1,90 @@
+# 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 分组展示。