diff --git a/docs/superpowers/plans/2026-10-02-web-admin-left-sidebar-layout.md b/docs/superpowers/plans/2026-10-02-web-admin-left-sidebar-layout.md new file mode 100644 index 000000000..d2076c028 --- /dev/null +++ b/docs/superpowers/plans/2026-10-02-web-admin-left-sidebar-layout.md @@ -0,0 +1,282 @@ +# web-admin 左侧树形壳层布局 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** 将 `web-admin` 默认壳层从门户顶栏改为「左侧 Logo+树菜单 / 右侧顶栏→多页签→内容」,并保持 Fresh Mint 色与现有菜单数字角标。 + +**Architecture:** 复用已有 `MenuTypeEnum.LEFT` 与 `ArtSidebarMenu`;在非门户布局分支挂载 `ArtWorkTab`;默认配置改为 LEFT + 开启多页签/面包屑;门户代码保留可选。角标数据链路不动,仅统一红色数字样式为 `#dc2626`。 + +**Tech Stack:** Vue 3 · Pinia · Element Plus · SCSS · Fresh Mint tokens + +**Spec:** `docs/superpowers/specs/2026-10-02-web-admin-left-sidebar-layout-design.md` + +--- + +## File map + +| File | Responsibility | +|------|----------------| +| `web-admin/src/config/setting.ts` | 默认 `menuType=LEFT`、`showWorkTab=true`、`showCrumbs=true`、侧栏宽度约 220 | +| `web-admin/src/views/index/index.vue` | 非门户分支装配 WorkTab;去掉强制 PORTAL;启动仍开多页签与首页固定 Tab | +| `web-admin/src/views/index/style.scss` | 非门户下 `#app-worktab` 样式(对齐门户条) | +| `web-admin/src/assets/styles/core/app.scss` | `.art-text-badge` 危险色改为 `#dc2626` | +| `docs/web-admin-ui-spec-fresh-mint.md` | §3 默认壳层说明更新 | + +**Note on `worktab.ts`:** `isPortalMultiTabMode()` 表示「门户 DOM 溢出淘汰」语义,应保持 `PORTAL && showWorkTab`。LEFT 多页签走既有 `showWorkTab` + 容量上限路径,**本计划不改**该函数。 + +--- + +### Task 1: 默认配置改为 LEFT + 多页签 + +**Files:** +- Modify: `web-admin/src/config/setting.ts` + +- [ ] **Step 1: 更新默认值** + +将下列字段改为: + +```ts +menuType: MenuTypeEnum.LEFT, +menuOpenWidth: 220, +showCrumbs: true, +showWorkTab: true, +``` + +其余字段保持不变。 + +- [ ] **Step 2: 自检** + +确认文件仍从 `@/enums/appEnum` 导入 `MenuTypeEnum`,且无语法错误。 + +- [ ] **Step 3: Commit** + +```bash +git add web-admin/src/config/setting.ts +git commit -m "$(cat <<'EOF' +feat(web-admin): default shell to left menu with work tabs + +Use LEFT layout as the product default and enable breadcrumbs and +multi-tabs so the classic sidebar shell matches the approved design. +EOF +)" +``` + +--- + +### Task 2: 布局装配 — 顶栏 → 多页签 → 内容 + +**Files:** +- Modify: `web-admin/src/views/index/index.vue` +- Modify: `web-admin/src/views/index/style.scss` + +- [ ] **Step 1: 更新非门户模板** + +将 `v-else` 分支的 `
` 改为: + +```vue +
+
+ +
+
+ +
+
+ +
+
+``` + +门户分支(`v-if="isPortalLayout"`)保持不动。 + +- [ ] **Step 2: 改写 `onMounted`** + +替换现有 `onMounted` 为: + +```ts +onMounted(() => { + const width = Number(settingStore.menuOpenWidth) + if (!Number.isFinite(width) || width < 220) { + settingStore.setMenuOpenWidth(220) + } else if (width === 270 || width === 290) { + // 收敛历史默认偏宽侧栏 + settingStore.setMenuOpenWidth(220) + } + + // 产品默认壳层:LEFT(不再强制 PORTAL;设置面板仍可切回门户) + if (menuType.value === MenuTypeEnum.PORTAL) { + settingStore.switchMenuLayouts(MenuTypeEnum.LEFT) + } + + settingStore.setWorkTab(true) + const home = homePath.value || HOME_PAGE_PATH || '/home' + if (home) { + worktabStore.openTab( + { + path: home, + title: '首页', + name: 'PortalHome', + fixedTab: true, + keepAlive: true + }, + { activate: false } + ) + } +}) +``` + +说明:将历史强制 PORTAL 改为「若仍是 PORTAL 则迁到 LEFT」,保证验收看到左树壳;用户之后可在设置切回门户(会持久化,下次进入保留门户——若产品希望每次强制 LEFT,再改为无条件 `switchMenuLayouts(LEFT)`)。 + +- [ ] **Step 3: 为非门户补 `#app-worktab` 样式** + +在 `web-admin/src/views/index/style.scss` 的 `#app-main` 内、`#app-header` 之后增加: + +```scss +#app-worktab { + flex-shrink: 0; + width: 100%; + background: #f1f5f9; + border-bottom: 1px solid var(--mint-border, #e2e8f0); +} +``` + +(可与 `style.portal.scss` 中 `#app-worktab` 视觉对齐;勿改门户文件除非两边需抽公共类——本任务优先最小改动复制必要样式。) + +- [ ] **Step 4: 手动冒烟(开发服)** + +Run: 在 `web-admin` 目录 `pnpm dev`,浏览器无痕或清站点数据后登录。 + +Expected: +- 左侧有 Logo + 系统名 + 树菜单 +- 右侧自上而下:顶栏、多页签、内容 +- 打开多个菜单后 Tab 可切换 + +- [ ] **Step 5: Commit** + +```bash +git add web-admin/src/views/index/index.vue web-admin/src/views/index/style.scss +git commit -m "$(cat <<'EOF' +feat(web-admin): mount work tabs under left-layout header + +Assemble header → worktab → content for the non-portal shell and migrate +legacy portal default so the classic sidebar layout is the entry experience. +EOF +)" +``` + +--- + +### Task 3: 菜单红色数字角标样式对齐 + +**Files:** +- Modify: `web-admin/src/assets/styles/core/app.scss`(`.art-text-badge` 段) + +- [ ] **Step 1: 统一角标危险色为 Fresh Mint danger** + +将 `.art-text-badge` 的 `background: #fd4e4e` 改为 `background: #dc2626`。 + +`--circle` 修饰符已具备圆角数字形态,保持结构不变。确认侧栏 `theme.scss` 中 `.menu-title-wrap .art-text-badge { margin-left: auto; position: static; }` 仍生效(无需改)。 + +- [ ] **Step 2: 冒烟** + +登录后进入有角标的菜单(如运输计划 / 购买证 / 报销等,视租户数据而定)。 + +Expected: 菜单项右侧红底白字圆角数字;色值为 `#dc2626`。 + +- [ ] **Step 3: Commit** + +```bash +git add web-admin/src/assets/styles/core/app.scss +git commit -m "$(cat <<'EOF' +style(web-admin): align menu text badge with Fresh Mint danger + +Use #dc2626 for sidebar numeric badges so they match the approved +case-style red counters without leaving the design token chain. +EOF +)" +``` + +--- + +### Task 4: 更新 UI 规范 §3 + +**Files:** +- Modify: `docs/web-admin-ui-spec-fresh-mint.md`(§3 全局与布局结构) + +- [ ] **Step 1: 在 §3.1 附近补充默认壳层说明** + +在 `### 3.1 根布局` 之后(或 §3 开头)增加一小节节,内容要点: + +```markdown +### 3.0 默认壳层(web-admin 运行时) + +- **默认布局**:左侧树菜单(`MenuTypeEnum.LEFT`),不再默认门户顶栏。 +- **左侧**:Logo + 系统名称 + 树形菜单;菜单数字角标为红底白字圆角(`#dc2626`)。 +- **右侧自上而下**:顶栏(面包屑/工具,高约 56px)→ 多页签 WorkTab → 内容区。 +- **侧栏宽度**:约 `220px`(与本节 `.sidebar` 宽度一致)。 +- **门户布局(PORTAL)**:保留为可选;设置面板可切换;业务页内容规范不变。 +- **色调**:Fresh Mint(`--primary #10b981` 链);不得使用案例 HTML 的 `#167c4a` 作为主色。 +``` + +同步检查 §3.2 侧栏宽度 `220px` 与实现一致(无需改数字时只加交叉引用)。 + +- [ ] **Step 2: Commit** + +```bash +git add docs/web-admin-ui-spec-fresh-mint.md +git commit -m "$(cat <<'EOF' +docs: document left-sidebar shell as web-admin default + +Update Fresh Mint layout section so the runtime shell matches the +approved left-tree + header/worktab/content structure. +EOF +)" +``` + +--- + +### Task 5: 验收清单 + +- [ ] **Step 1: 清缓存后登录** + +Expected: 默认左树 + 右顶栏→Tab→内容;无门户顶栏模块条。 + +- [ ] **Step 2: 多页签** + +打开 ≥2 个业务页;切换、关闭、首页固定 Tab 可用。 + +- [ ] **Step 3: 角标** + +有 badge 的菜单显示红色数字(`#dc2626`)。 + +- [ ] **Step 4: 色调** + +主色仍为 `#10b981` / `#059669`;无 `#167c4a`。 + +- [ ] **Step 5: 可选回归** + +设置面板切到 Portal,确认门户壳仍可用(不要求作为默认)。 + +- [ ] **Step 6: 图谱(若本会话改了代码)** + +```bash +./scripts/update-graph.sh frontend +``` + +--- + +## Spec coverage check + +| Spec 要求 | Task | +|-----------|------| +| 默认 LEFT,取消强制 PORTAL | Task 1–2 | +| 右:顶栏→多页签→内容 | Task 2 | +| Fresh Mint 色 | Task 1–4(不改主色) | +| 红色数字角标 | Task 3(数据复用现网) | +| 门户保留可选 | Task 2(不删门户分支)+ Task 5 | +| UI 规范 §3 | Task 4 | +| 侧栏宽度约 220 | Task 1–2 | + +## Placeholder scan + +无 TBD / 「类似 Task N」占位;步骤含具体代码与命令。