# web-admin 门户化布局改造 — 设计文档 > **日期**: 2026-06-20 > **状态**: 已实现(2026-06-20) > **范围**: `web-admin` 管理端框架(布局 + 菜单展示 + 权限联动) > **UI 规范**: `docs/web-admin-ui-spec-fresh-mint.md`(主色 `#10b981`、Fresh Mint Token) ## 目标 将 web-admin 从「左侧全量菜单 + 顶栏工具条」改为 **一体化门户布局**: 1. 顶栏展示 Logo、「一体化门户」、6 个一级模块卡片(icon 上 / 名称下),选中态绿底白字。 2. 下方分左右:左侧为当前模块的二/三级菜单;右侧为 WorkTab + 内容区。 3. 移除顶栏的菜单折叠、面包屑、刷新按钮;移除【控制台】一级菜单。 4. 一级 / 二级 / 三级菜单仍按角色与 `menuCode` 权限过滤显示。 --- ## 已确认决策 | # | 决策 | 说明 | |---|------|------| | D1 | **实现方式** | 新增 `MenuTypeEnum.PORTAL` 专用布局模式(方案 A),不魔改 TOP_LEFT / DUAL_MENU | | D2 | **权限边界(0/1 模块)** | **始终保留顶栏卡片区域**:0 个可见模块时展示「暂无可用模块」空态;1 个模块时仍展示 1 张卡片 | | D3 | **一级菜单清单** | CRM 管理、报销管理、地磅管理、运输管理、工作流管理、系统管理(共 6 个,不含控制台) | | D4 | **一级展示顺序** | CRM → 报销 → 地磅 → 运输 → 工作流 → 系统(前端常量排序,不依赖路由文件注册顺序) | | D5 | **控制台** | 从侧栏与顶栏卡片中移除;默认首页改为第一个有权限模块的首个可访问叶子页 | | D6 | **顶栏右侧** | 保留用户菜单;全屏按钮保留;折叠 / 面包屑 / 刷新移除 | | D7 | **侧栏** | 去掉 Logo 与「一体化门户」品牌区;去掉顶栏式折叠 icon;侧栏本身不新增折叠按钮(固定展开,宽度沿用 `menuOpenWidth` 默认 230px) | | D8 | **OpenSpec 侧栏 icon** | 一级卡片有 icon;左侧二/三级菜单仍遵守「仅一级有 icon、更深层仅文字」(`SidebarSubmenu` 现有 `level === 0` 规则) | --- ## 非目标(本期不做) - 设置面板中保留/切换 Left、Top、Mixed、Dual 等旧布局(PORTAL 为唯一产品布局,设置项可隐藏或锁定) - 小程序端布局改造 - 权限后端 API 改造(沿用 `MenuProcessor` + `fetchGetMenuCodes`) - 移动端完整适配(本期仅保证 `<800px` 不严重错位;横滑卡片 + 抽屉侧栏可作为 follow-up) - Demo 菜单独立提升为一级模块 --- ## 一、目标布局 ``` ┌────────────────────────────────────────────────────────────────────────┐ │ [Logo] 一体化门户 [CRM] [报销] [地磅] [运输] [工作流] [系统] [用户] │ ← ArtPortalHeader(全宽) │ ↑ 卡片:icon 上 / 名称下;选中 #10b981 底 + 白字 │ ├──────────────┬─────────────────────────────────────────────────────────┤ │ 二级 / 三级 │ ArtWorkTab(标签页) │ │ 菜单树 ├─────────────────────────────────────────────────────────┤ │ ArtPortal │ ArtPageContent(业务页面) │ │ Sidebar │ │ └──────────────┴─────────────────────────────────────────────────────────┘ ``` **DOM 结构(`views/index/index.vue`)** ``` .app-layout-portal ├── #app-portal-header → ArtPortalHeader └── #app-portal-body → flex row ├── #app-sidebar → ArtPortalSidebar(改造 art-sidebar-menu) └── #app-workspace → flex column ├── #app-worktab → ArtWorkTab(从 art-header-bar 迁出) └── #app-content → ArtPageContent ``` --- ## 二、一级模块卡片(ArtPortalTopNav) ### 2.1 数据来源 - 输入:`menuStore.menuList` 经 **门户一级过滤器** 处理后的列表。 - 过滤器职责: 1. 排除控制台(`path === '/dashboard'` 或 `meta.title === '控制台'`)。 2. 排除 `meta.isHide === true` 的项。 3. 按 D4 常量顺序排序。 4. 若项无可见子节点且自身不可导航 → 不渲染卡片(与 `MenuProcessor.filterEmptyMenus` 结果一致)。 ### 2.2 卡片 UI | 属性 | 值 | |------|-----| | 布局 | 纵向 flex,居中;icon 在上(20–24px),标题在下(12–13px) | | 间距 | 卡片之间 `gap: 8–12px`;卡片内 padding 约 `8px 12px` | | 圆角 | `8px`(与规范按钮/输入圆角一致) | | 默认 | 透明底;icon/文字 `--text` / `--text-muted` | | 选中 | `background: var(--primary)`;icon 与文字 `#fff` | | 激活判定 | 复用 `ArtMixedMenu.isMenuItemActive`:当前路由(或 `meta.activePath`)落在该模块子树内 | ### 2.3 交互 - 点击卡片:`router.push(module.redirect || firstAccessibleChildPath(module))`。 - 若当前路由已属于该模块:仅更新选中态,不强制跳转。 - **0 个可见模块**:顶栏卡片区展示 muted 文案「暂无可用模块」(不隐藏顶栏)。 - **1 个可见模块**:仍展示 1 张卡片(D2)。 ### 2.4 一级模块与路由前缀映射 | 卡片名称 | 路由 path 前缀 | 路由模块 | |----------|----------------|----------| | CRM 管理 | `/crm` | `sqxp.ts` | | 报销管理 | `/bx` | `sqxp.ts` | | 地磅管理 | `/db` | `sqxp.ts` | | 运输管理 | `/pl` | `pl.ts` | | 工作流管理 | `/workflow` | `sqxp.ts` | | 系统管理 | `/system` | `sqxp.ts` | --- ## 三、左侧菜单(ArtPortalSidebar) ### 3.1 渲染范围 - 仅渲染 **当前激活一级模块** 的 `children`(二/三级)。 - 激活模块解析:`const top = '/' + route.path.split('/')[1]`,在过滤后的一级列表中匹配。 - iframe 路由:沿用 `art-sidebar-menu` 现有 `findIframeMenuList` 逻辑。 ### 3.2 移除内容 - 侧栏 header 区(Logo + 系统名)。 - 双列菜单 / 折叠按钮 / `menu-model` 遮罩(PORTAL 模式不启用 `DUAL_MENU` / `LEFT` 分支)。 - 顶栏菜单折叠联动(`visibleMenu` / `menuOpen` 切换对 PORTAL 无 UI 入口;`menuOpen` 保持 `true`)。 ### 3.3 子菜单组件 - 继续复用 `SidebarSubmenu` + `filterSidebarRoutes`。 - `ElMenu` 默认展开:保留现有 `syncExpandedMenus` / `defaultOpenedMenus` 逻辑。 --- ## 四、顶栏(ArtPortalHeader) ### 4.1 左侧 - `ArtLogo`(点击跳转默认首页,见 §五)。 - 文案「一体化门户」(`AppConfig.systemInfo.name`,已为该值)。 ### 4.2 中间 - `ArtPortalTopNav`(flex-1,卡片可横向滚动;模块多时可加 `ElScrollbar`)。 ### 4.3 右侧 - 全屏按钮(可选保留)。 - `ArtUserMenu`。 - **不渲染**:折叠、刷新、面包屑、快速入口、通知、语言、主题切换(与现 header 隐藏项一致)。 ### 4.4 WorkTab 迁移 - 从 `art-header-bar/index.vue` 移除 ``。 - 挂载到 `#app-workspace` 顶部(`ArtWorkTab` 组件本身不改业务逻辑)。 - 样式:`worktab-strip` 的 `mb-3` 与 workspace padding 对齐 Fresh Mint 内容区 rhythm。 --- ## 五、菜单数据与权限 ### 5.1 现有链路(保持不变) ``` beforeEach → MenuProcessor.getMenuList() → filterMenuByRoles / filterMenuByCodes → filterEmptyMenus → menuStore.setMenuList → RouteRegistry.register ``` ### 5.2 前端增强 | 位置 | 增强 | |------|------| | `MenuProcessor.processFrontendMenu` | 过滤掉 Dashboard / 控制台节点 | | 新建 `utils/router/portal-menu.ts` | `PORTAL_TOP_MODULE_ORDER`、`filterPortalTopModules()`、`resolveActivePortalModule()`、`getFirstAccessiblePath()` | | `menuStore.setMenuList` | 设置 `homePath` 时跳过 `/dashboard`,使用 `getFirstSecondLevelMenuPath`(已有) | ### 5.3 三级权限行为 | 层级 | 机制 | |------|------| | 一级卡片 | `MenuProcessor` 输出 + `filterPortalTopModules`;`filterMenuByCodes` level=1 保留「有可见子节点」的父级 | | 二级 | `filterSidebarRoutes` | | 三级 | `SidebarSubmenu` 递归 + `filterSidebarRoutes` | ### 5.4 后端菜单(backend 模式) - SQL 隐藏或删除 Dashboard 对应 `sys_menu` 记录(与前端路由同步)。 - 确认 6 个一级菜单在 `sys_menu` 中 `parent_id` 指向门户 Web 根节点;运输管理已更名见 `docs/sql/20260620_pl_menu_rename_hide.sql`。 - 新增迁移脚本:`docs/sql/20260620_portal_hide_dashboard.sql`(建议)。 --- ## 六、配置与枚举 | 文件 | 变更 | |------|------| | `enums/appEnum.ts` | 新增 `MenuTypeEnum.PORTAL = 'portal'` | | `config/setting.ts` | 默认 `menuType: MenuTypeEnum.PORTAL`;`showMenuButton/showRefreshButton/showCrumbs: false` | | `config/modules/headerBar.ts` | `menuButton/refreshButton/breadcrumb.enabled: false` | | `store/modules/setting.ts` | 支持 PORTAL 分支(若 layout 判断分散在各组件,统一用 `isPortalLayout` computed) | | `views/index/index.vue` | PORTAL 时使用新 DOM 结构;旧 LEFT 结构可保留供模板升级对比或后续删除 | --- ## 七、路由与首页 ### 7.1 控制台处理 - `sqxp.ts`:Dashboard 路由设 `meta.isHide: true` 或整段注释/删除(与 SQL 同步)。 - 登录后默认跳转:第一个有权限模块的首个叶子页(如 `/crm/...`)。 ### 7.2 路由顺序 - `routeModules` 合并顺序不影响 UI(由 `PORTAL_TOP_MODULE_ORDER` 控制)。 - 文档注释更新:`sqxp.ts` 头部说明去掉「控制台」。 --- ## 八、样式要点 - 顶栏高度:建议 `64–72px`(略高于现 `h-15` 以容纳卡片)。 - 顶栏背景:`var(--default-bg-color)` / 白底 + 底部分割线 `var(--art-card-border)`。 - 一级卡片选中色:`var(--primary)` `#10b981`,**勿**使用小程序色 `#0a9f6d`。 - 下方 body:`height: calc(100vh - 顶栏高度)`;workspace 内容区 padding 沿用 `--mint-content-padding`。 - 侧栏宽度:230px(`menuOpenWidth` 默认值)。 --- ## 九、测试计划 | 场景 | 预期 | |------|------| | super_admin | 6 张卡片 + 对应侧栏全量 | | admin 仅有 bx 权限 | 顶栏仅 1 张「报销管理」卡片;侧栏仅 bx 子菜单 | | admin 无任何业务 menuCode | 顶栏卡片区显示「暂无可用模块」 | | 点击 CRM 卡片 | 路由进入 CRM 首个可访问页;卡片选中;侧栏切换为 CRM 树 | | 从 CRM 页内跳转 bx 页 | 顶栏选中态自动切到报销 | | 直接 URL 访问 `/pl/plan` | 运输卡片选中;侧栏为 pl 子树 | | 控制台 `/dashboard` | 不可从菜单进入;直接访问按路由守卫处理(404 或重定向首页) | | WorkTab | 开/关/切换标签正常;位置在内容区上方 | | 侧栏二/三级 | 无 icon,仅文字(OpenSpec) | --- ## 十、影响文件清单 **新建** - `components/core/layouts/art-portal-header/index.vue` - `components/core/layouts/art-portal-top-nav/index.vue` - `utils/router/portal-menu.ts` - `docs/sql/20260620_portal_hide_dashboard.sql`(建议) **修改** - `views/index/index.vue`、`views/index/style.scss` - `components/core/layouts/art-menus/art-sidebar-menu/index.vue`(PORTAL 分支) - `components/core/layouts/art-header-bar/index.vue`(移除 WorkTab;或 PORTAL 下不再使用此组件) - `enums/appEnum.ts`、`config/setting.ts`、`config/modules/headerBar.ts` - `router/core/MenuProcessor.ts` - `router/modules/sqxp.ts` **可选** - `components/core/layouts/art-settings-panel`:隐藏菜单布局切换或锁定 PORTAL --- ## 十一、风险 1. **WorkTab 样式错位**:迁移后需目视检查 tab-card / tab-google 两种 `tabStyle`。 2. **跨模块 deep link**:书签直达子页时,顶栏选中态依赖 `isMenuItemActive`,需覆盖 `meta.activePath`。 3. **模板升级**:Art Design Pro 上游更新 layout 时,PORTAL 为独立分支,合并冲突集中在 `index.vue`。 4. **窄屏**:6 卡片可能溢出,顶栏需横向滚动;侧栏 `<800px` 现有 fixed 策略待 follow-up。 --- ## 十二、后续(非本期) - 移动端:顶栏卡片横滑 + 侧栏抽屉。 - 设置面板清理旧 layout 选项。 - OpenSpec `ui-conventions` 补充「门户布局」章节(若需长期规范)。