# 側邊欄選單分組 — 詳細白話需求

| 欄位 | 內容 |
|------|------|
| 草稿來源 | `docs/draft_requirement_spec/menu-group/requirement.md`（原始草稿）|
| 撰寫日期 | 2026-05-26 |
| 撰寫者 | Claude（由 raymond 提出需求 + 釐清）|
| 狀態 | 白話需求討論中（Phase 0），尚未進入 Phase 1 設計階段 |

---

## 1. 為什麼要做這件事

目前系統側邊欄選單**全部攤平成一層**（DB `public.ui_routes` 共 39 個項目，全部 `pid=0`），即使有些功能項目已經 `enable=0` 不顯示，仍然顯示在使用者眼前的選單長到「太冗長」、不容易找到對應功能。

使用者希望按照業務領域把選單分成 **7 個分組**，每個分組是一個可展開的父節點，下面掛上對應功能入口，讓側邊欄一眼就能看出「我要找的東西在哪一類」。

---

## 2. 期望的最終結果（使用者看到的）

側邊欄從上到下依序變成這 7 個分組，每個分組是可展開/收合的父節點：

```
1. 專案與任務        ▼
2. 合規與稽核        ▼
3. 溝通與互動        ▼
4. 租戶與組織        ▼
5. 系統管理          ▼
6. 系統設定          ▼
7. AI 與分析         ▼
```

各分組底下包含的功能入口（按目前使用者實際看到的中文標題列示，括號內是內部對應的 `ui_routes.name`）：

### Group 1：專案與任務（icon: `pi pi-briefcase`）
- 專案儀表板（`project-dashboard`）— ⚠ 目前 AppMenu.vue 寫死，需搬進 DB
- 待辦任務（`my-tasks`）— ⚠ 目前 AppMenu.vue 寫死，需搬進 DB
- 專案管理（`project-list`）
- 我的稽核（`audit-manage`）
- 專案調查結果（`report-manage`）

### Group 2：合規與稽核（icon: `pi pi-shield`）
- 合規資源庫（`module-frame`）
- 合規框架管理（`compliance-framework-manage`）
- 檢測工具管理（`tool-plugin-manage`）
- 流程範本管理（`flow-template-manage`）

### Group 3：溝通與互動（icon: `pi pi-comments`）
- 公告（`bulletin-list`）
- 公告管理（`bulletin-manage`）
- 問卷管理（`survey-manage`）
- 回饋（`system-feedback-manage`）
- 系統回饋管理（`system-feedback-view`）
- 回饋整合設定（`issue-integrate-config`）

### Group 4：租戶與組織（icon: `pi pi-building`）
- 租戶管理（`tenant-manage`）
- 機關（構）單位管理（`department-manage`）
- 帳號管理（`user-manage`）
- 權限管理（`role-manage`）

### Group 5：系統管理（icon: `pi pi-cog`）
- 選單管理（`system-menu-manage`）
- 資訊系統管理（`information-system-manage`）
- 設備管理（`device-manage`）
- 儲存設備設定（`storage-config`）
- 雲端空間整合（`cloud-integrations`）

### Group 6：系統設定（icon: `pi pi-sliders-h`）
- 郵件伺服器設定（`smtp-config`）
- LDAP伺服器設定（`ldap-config`）
- 通知設定（`notify-config`）
- 操作日誌（`user-log`）

### Group 7：AI 與分析（icon: `pi pi-chart-line`）
- AI動態儀表板（`ai-dashboard`）

---

## 3. 行為規則（使用者體驗層面）

### 3.1 權限對應規則

| 對象 | 是否做權限控制 | 行為 |
|------|--------------|------|
| **葉節點（功能入口）** | 維持現狀 | 沿用 `ui_routes ↔ route_capabilities ↔ role_capabilities` 既有 RBAC 機制，使用者沒對應 capability 就看不到 |
| **分組節點（7 個分組標題）** | 不掛 capability | 由「底下是否還有可見子節點」決定要不要顯示 |
| **「專案儀表板」「待辦任務」這 2 個搬進 DB 的項目** | 不掛 capability | 每個 user 都看得到（含新進 user，不需另外設權限）|

**為什麼這樣可行**：BE `jedi-auth` 套件 `ui_route_repo_impl.py:103-107` 已實作「若路由無任何 `route_capabilities` 關聯設定 → 視為可見」的 fallback 邏輯。所以**不掛 capability 等同於「對所有人開放」**，免去額外建 capability 的繁瑣。

### 3.2 空分組自動隱藏規則

當某個使用者的角色 / capability 配置下，某個分組底下**所有**葉節點都被權限過濾掉時，**該分組標題也不要顯示**。

例如：某個 user 沒有「租戶管理 / 機關單位管理 / 帳號管理 / 權限管理」中任何一項權限，那「4. 租戶與組織」這個分組標題就**完全不出現**在他的選單上（而不是顯示一個點開來什麼都沒有的空殼）。

### 3.3 分組順序

依上面 1~7 的編號順序，由上而下顯示。**不可更動**這個順序（已是使用者明確指定的最終順序）。

### 3.4 分組內項目順序

每個分組內的功能入口，依上面列示的順序顯示（不再依照舊版 `ui_routes.sort` 的全域排序，而是改成「分組內局部排序」）。

---

## 4. 範圍邊界（in scope / out of scope）

### 4.1 In Scope（本期要做）

- 在 `public.ui_routes` 新增 7 個分組節點（pid=null/0，icon 如上述）
- 把 27 個現有 ui_routes 葉節點的 `pid` 指向對應分組節點
- 新增 2 個 ui_routes（`project-dashboard` / `my-tasks`），對應「Group 1」底下的「專案儀表板」「待辦任務」
- 修改 FE `AppMenu.vue` 移除寫死的 `grcItems` 陣列（讓兩個項目改從 `/user/web-menu` API 取得）
- BE `get_user_web_ui_routes`（在 `jedi-auth` 套件內）加上「空分組自動隱藏」邏輯
- 設定每個分組節點與對應 sort 值，確保 1~7 順序固定

### 4.2 Out of Scope（本期不做）

- **不處理 enable=0 的「附加頁面」**：DB 內已 enable=0 的 12 個項目（`workflow-setup` / `workflow-view` / `textbook-*` / `resource-version-manage` / `resource-manage` / `cruise-project-manage` / `cruise-feedback-view` / `report-view` / `customer-dashboard-editor` / `user-guide`）**保持原狀不動**（不設 pid、不改 enable），它們本來就被 BE 過濾掉，不會出現在新版選單上。
- **不做 3 層深的樹狀結構**：所有功能入口都是分組底下「直接掛」的葉節點，不再做更深的子選單。
- **不重新評估或整併現有功能**：例如「`workflow-*` 跟 `flow-template-manage` 是否功能重疊」這類議題本期不討論。
- **不改 i18n 翻譯內容**：分組名稱（「專案與任務」「合規與稽核」⋯）的中文直接寫進 `ui_routes.name`，**FE 顯示時優先用 i18n key 對照，找不到對照就直接顯示 name 原文**（這部分行為視 AppMenuItem.vue 的實作而定，需在 Phase 1 確認）。

---

## 5. 預估的改動範圍（給後續評估設計用）

> **這只是初估，正式的拆解、檔案清單、影響面盤點等留到 Phase 3「實作計畫」階段再做。**

| 層面 | 預估改動 |
|------|---------|
| **DB migration** | 1 份 SQL：新增 9 筆 ui_routes（7 個分組 + 2 個寫死搬遷項）、更新 27 筆既有 ui_routes 的 `pid` |
| **i18n（FE）** | `zh-tw/menu.json` / `zh-cn/menu.json` 新增 7 個分組節點的 i18n key（若採用 i18n key 方案；若直接用 ui_routes.name 顯示中文就不用改 i18n）|
| **BE `jedi-auth` 套件** | `ui_route_repo_impl.py` 或 `user_service.get_user_web_ui_routes` 加「組樹完成後剪枝：分組節點若 items 為空就移除」邏輯 |
| **FE `AppMenu.vue`** | 移除寫死的 `grcItems` 陣列，全部走 `permissions.value`（即 `/user/web-menu` 回傳結果）|
| **權限初始化** | 不需新增 capability / role_capabilities（分組節點與寫死搬遷項都不掛 capability）|

---

## 6. 已釐清的關鍵決策（決策紀錄）

| # | 議題 | 決策 | 決策日期 |
|---|------|------|--------|
| 1 | 未在 7 組草稿內的舊選單怎處理？ | 全部 enable=0、保持原狀不動。BE 自動過濾，不會出現在新版選單上。 | 2026-05-26 |
| 2 | AppMenu.vue 寫死的「專案儀表板 / 待辦任務」怎處理？ | 搬到 DB 統一管理，但**不掛 capability**（讓所有 user 都看得到），免去額外建 capability。 | 2026-05-26 |
| 3 | 分組標題本身要不要做權限控制？ | 不掛 capability。底下無可見子節點時自動隱藏分組（BE 端剪枝）。 | 2026-05-26 |
| 4 | 「回饋」對應的是哪個 ui_routes？ | `system-feedback-manage`（i18n: "回饋"）。`system-feedback-view`（i18n: "系統回饋管理"）是另一項目，兩者都保留並歸到 Group 3。`cruise-feedback-view` 是 enable=0 的未列項目，保持原狀不動。 | 2026-05-26 |
| 5 | `module-frame` 對應的中文是什麼？ | FE i18n 翻譯為「**合規資源庫**」（不是 `resource-manage`）。`resource-manage` 在 i18n 是「資源上下架」、enable=0，屬於本期不動的未列項目。 | 2026-05-26 |
| 6 | 1~7 編號就是顯示順序？ | 是，1 在最上、7 在最下，不可變更。 | 2026-05-26 |
| 7 | 分組 icon 怎決定？ | 由 Claude 任意提案使用者 review；本份文件已採用第一版提案（見第 2 段）。 | 2026-05-26 |

---

## 7. 還需要再確認的細節（移交 Phase 1 設計階段時要釐清）

1. **i18n 設計選擇**：分組標題的中文是 (a) 直接寫進 `ui_routes.name` 由 FE 原樣顯示，還是 (b) 在 `ui_routes.name` 寫 i18n key、FE 透過 `menu.json` 對照後顯示？兩種做法都可行，差別在英文版 / 簡體版怎麼處理。Phase 1 設計時決定。
2. **i18n key 的命名**（若採方案 b）：例如 `menu.group.project-task` 等。
3. **BE「空分組剪枝」邏輯放哪一層**：放在 `jedi-auth` 套件的 `user_service.get_user_web_ui_routes` 內（影響其他 consumer），還是主專案在 route 層 wrap？外部套件異動規範參考 CLAUDE.md。
4. **DB migration 的 `uid` 怎產生**：分組節點與兩個搬遷項的 `uid` 規則（既有 ui_routes 都有手動指派的 uid，需要保持一致風格）。
5. **新版 sort 值的安排**：是要全部重新編號（例如分組 sort=10/20/30...，組內葉節點 sort=10/11/12...），還是只動分組節點 sort、葉節點 sort 維持現狀靠 pid 自動分組？

---

## 8. 後續流程指引

依專案 `docs/claude/feature-development-workflow.md` 流程：

- **Phase 0（白話需求）**：✅ 本文件已完成。
- **Phase 1（brainstorm 設計）**：把這份白話需求帶進 `superpowers:brainstorming` skill，產出 `docs/features/FR-029-2605-menu-group/design.md`，包含 DB schema 變動、API 行為、FE 改動、i18n 策略、邊界 case 處理等技術設計。
- **Phase 2（歸檔）**：本資料夾 `docs/draft_requirement_spec/menu-group/` 在 Phase 1 完成後搬到 `docs/features/FR-029-2605-menu-group/`，原資料夾刪除。
- **Phase 3（實作計畫）**：產出 `docs/features/FR-029-2605-menu-group/implementation-plan.md`。
- **Phase 4（測試計畫）**：必要時產出 `test-plan.md`（本需求屬 UI 重組，BE 邏輯改動小，可能不需要重型 test plan，由 Phase 3 評估）。
- **Phase 5（實作）**：按 plan 執行。
- **Phase 6（review）**：跨 BE / FE / 測試 repo review。

---

## 附錄 A：完整對照表（27 個歸組項目）

| Group | ui_routes.name | FE i18n 中文 | 來源 |
|-------|---------------|-------------|------|
| 1 | `project-dashboard` | 專案儀表板 | 本期新增到 DB |
| 1 | `my-tasks` | 待辦任務 | 本期新增到 DB |
| 1 | `project-list` | 專案管理 | 既有 |
| 1 | `audit-manage` | 我的稽核 | 既有 |
| 1 | `report-manage` | 專案調查結果 | 既有 |
| 2 | `module-frame` | 合規資源庫 | 既有 |
| 2 | `compliance-framework-manage` | 合規框架管理 | 既有 |
| 2 | `tool-plugin-manage` | 檢測工具管理 | 既有 |
| 2 | `flow-template-manage` | 流程範本管理 | 既有 |
| 3 | `bulletin-list` | 公告 | 既有 |
| 3 | `bulletin-manage` | 公告管理 | 既有 |
| 3 | `survey-manage` | 問卷管理 | 既有 |
| 3 | `system-feedback-manage` | 回饋 | 既有 |
| 3 | `system-feedback-view` | 系統回饋管理 | 既有 |
| 3 | `issue-integrate-config` | 回饋整合設定 | 既有 |
| 4 | `tenant-manage` | 租戶管理 | 既有 |
| 4 | `department-manage` | 機關（構）單位管理 | 既有 |
| 4 | `user-manage` | 帳號管理 | 既有 |
| 4 | `role-manage` | 權限管理 | 既有 |
| 5 | `system-menu-manage` | 選單管理 | 既有 |
| 5 | `information-system-manage` | 資訊系統管理 | 既有 |
| 5 | `device-manage` | 設備管理 | 既有 |
| 5 | `storage-config` | 儲存設備設定 | 既有 |
| 5 | `cloud-integrations` | 雲端空間整合 | 既有 |
| 6 | `smtp-config` | 郵件伺服器設定 | 既有 |
| 6 | `ldap-config` | LDAP伺服器設定 | 既有 |
| 6 | `notify-config` | 通知設定 | 既有 |
| 6 | `user-log` | 操作日誌 | 既有 |
| 7 | `ai-dashboard` | AI動態儀表板 | 既有 |

## 附錄 B：未列項目（12 個，全 enable=0，本期不動）

| ui_routes.name | enable | FE i18n 中文 |
|---------------|--------|-------------|
| `workflow-setup` | 0 | 工作流程設定 |
| `workflow-view` | 0 | 系統流程 |
| `textbook-execution` | 0 | 教材-執行端 |
| `textbook-tested` | 0 | 教材-受檢端 |
| `textbook-general` | 0 | 教材-一般性 |
| `resource-version-manage` | 0 | 資源版本維護 |
| `resource-manage` | 0 | 資源上下架 |
| `cruise-project-manage` | 0 | 專案管理（韌性巡航）|
| `cruise-feedback-view` | 0 | 韌性巡航回饋管理 |
| `report-view` | 0 | 查閱背景資料盤點問卷結果數據 |
| `customer-dashboard-editor` | 0 | 自定義儀表板 |
| `user-guide` | 0 | 操作說明 |