# 01 后台前端壳层与路由

## 模块职责

提供所有后台页面共用的应用外壳，不承载业务列表和业务请求。负责侧边栏、顶栏、内容区、页面标题、全局错误展示、退出登录入口，以及 Vue Router 的页面容器。

## 依赖关系

上游：`02-session-menu-permission.md` 提供用户和菜单状态；`10-static-deployment-and-nginx.md` 提供 `/admin-vue/` 基准路径和 History fallback。

下游：所有业务页面挂载到 `AdminLayout` 的 `RouterView`；Pinia Session Store 提供菜单树和用户信息。

现有依赖：

- `backend/web_source/admin.html` 的 `.admin-layout`、`.admin-sidebar`、`.admin-topbar`、`.admin-content`。
- `backend/static/admin-interactions.js` 的 loading、toast、confirm 横切行为。
- 当前独立工程的 `admin-frontend-vue/src/layout/AdminLayout.vue`、`src/router/index.ts`、`src/styles/main.css`。

## 核心接口：原实现 → 目标实现

| 原实现 | 目标实现 |
|---|---|
| `admin.html` 内嵌完整布局 | `AdminLayout.vue` + 子组件 |
| `admin.js:activateAdminTab` 通过 DOM 隐藏/显示面板 | Vue Router 路由切换 |
| `admin.js:syncTabHash` 使用 `#tab` | History URL，如 `/admin-vue/account/users` |
| `admin-interactions.js:showToast` | Element Plus `ElMessage` |
| `admin-interactions.js:openConfirm` | Element Plus `ElMessageBox` |
| 页面标题写死并由 DOM 更新 | 路由 `meta.title` 驱动 |

## 内部结构

```text
AdminLayout
├── AdminSidebar
│   ├── 菜单分组
│   └── 菜单页面项
├── AdminTopbar
│   ├── 当前页面标题
│   ├── 当前用户名/角色
│   └── 退出登录
├── AdminContent
│   ├── 全局错误提示
│   └── RouterView
└── 全局 Element Plus 消息/确认能力
```

路由结构按业务域组织：

- `account/*`
- `asin-center/*`
- `shop-center/*`
- `tasks/*`
- `records/*`

路由 path 不承担权限标识，权限判断使用路由元数据中的 `menuKey` 与后端菜单节点 `key` 对比。

## 类型映射

| 旧概念 | 目标类型 |
|---|---|
| `data-tab` | Vue route path |
| `route_path` | 后端菜单 `route` |
| `adminPageTitle` | `RouteMeta.title` |
| `adminMenu` DOM | `AdminMenuNode[]` |
| `adminCurrentUsername` | `AdminUser.username` |
| `adminCurrentUserRole` | `AdminUser.role` |

`AdminMenuNode` 至少包含 `key`、`name`、可选 `route`、可选 `children`。

## 迁移/实现注意事项

1. `createWebHistory('/admin-vue/')` 的基准路径必须和 Vite `base`、Nginx location 完全一致。
2. 不实现旧 `#tab=xxx` 兼容；旧地址不属于目标契约。
3. 不能把所有业务页面静态 import 到壳层；页面必须按路由异步加载。
4. 侧边栏只渲染后端返回的菜单树，不根据角色在前端硬编码一份权限菜单。
5. 页面级无权限时跳转到当前用户第一个可见页面；没有任何页面时展示无菜单状态。
6. 视觉保持深色侧边栏、浅色内容区，但不得把旧 CSS 2.5 万行整体搬运进新工程。
7. 全局 loading 只用于请求生命周期提示；业务页面仍需拥有自己的表格 loading 和空状态。