# Layout Specification

## Purpose

定义管理后台布局壳与主题系统的行为：可配置的布局/导航模式、主题色、暗黑模式、侧边栏折叠与宽度、固定顶栏/底栏，以及面包屑/多页签/全屏/手风琴等配套能力。

## Requirements

### Requirement: 布局与导航模式
系统 SHALL 支持 3 种布局（上下 / 纯上下 / 左右）与 MixBar 开关的组合，共 4 种呈现（MixBar 仅左右布局可用）；MixBar 始终固定在布局最左侧；所有布局均渲染顶栏，仅导航菜单位置不同。

#### Scenario: 切换布局即时生效
- **WHEN** 用户在布局设置中切换布局或开启/关闭 MixBar
- **THEN** 主框架立即按新布局重新排布顶栏、侧边栏与内容区

#### Scenario: 左右顶栏不含菜单
- **WHEN** 布局为「左右」
- **THEN** 顶栏仍显示折叠/面包屑/全屏/暗黑/设置/用户等工具，但不渲染导航菜单，菜单全部在左侧侧边栏

#### Scenario: 上下/纯上下顶栏含导航
- **WHEN** 布局为「上下」或「纯上下」
- **THEN** 顶栏含导航：「上下」顶部放一级导航、左侧放子菜单；「纯上下」仅顶部放全量导航

### Requirement: 侧边菜单折叠
左侧导航菜单 SHALL 支持 collapse（折叠为图标）与 expand（展开显示文字+图标）。

#### Scenario: 折叠与展开
- **WHEN** 用户点击折叠按钮
- **THEN** 侧边栏在折叠（仅图标）与展开（文字+图标）之间切换

### Requirement: 顶栏 Logo 区
顶栏左上角 Logo 区 SHALL 与左侧菜单（或 MixBar+菜单）同宽；侧栏折叠时仅显示 Logo，展开时显示 Logo 与标题。

#### Scenario: Logo 区对齐
- **WHEN** 布局含左侧菜单
- **THEN** 顶栏 Logo 区宽度与左侧菜单（含 MixBar 时与 MixBar+菜单）一致

#### Scenario: 折叠仅显 Logo
- **WHEN** 侧栏折叠
- **THEN** 顶栏 Logo 区仅显示 Logo；展开时显示 Logo 与标题

### Requirement: 主题色
系统 SHALL 支持通过颜色选择器自定义主题色，默认 `#2E7FA3`；选择后运行时更新 Element Plus 主色及其派生色阶。

#### Scenario: 选择主题色
- **WHEN** 用户在设置面板用颜色选择器选取新主题色
- **THEN** 全站 Element Plus 主色（按钮/链接/高亮等）即时变为所选颜色，刷新后仍保留

### Requirement: 暗黑模式
系统 SHALL 支持明亮/暗黑模式切换；暗黑模式下切换 Element Plus 深色主题与全局深色令牌。

#### Scenario: 切换暗黑模式
- **WHEN** 用户切换暗黑模式开关
- **THEN** 全站即时切换为深色配色，刷新后仍保留

### Requirement: 顶栏固定
顶栏 SHALL 支持固定（内容滚动时顶栏常驻顶部）与不固定，所有布局均适用。

#### Scenario: 顶栏固定开关
- **WHEN** 用户切换「固定顶栏」
- **THEN** 顶栏在固定/随内容滚动之间切换

### Requirement: 侧边菜单宽度
左侧菜单宽度 SHALL 可调，范围 200–340（单位 px）。

#### Scenario: 调整宽度
- **WHEN** 用户拖动或输入侧边栏宽度
- **THEN** 宽度在 200–340 之间变化并即时生效，超界被限制在边界值

### Requirement: 底部版权固定
系统 SHALL 在底部显示版权信息「云南投云科技有限公司」，并支持固定/不固定。

#### Scenario: 底部版权
- **WHEN** 用户开启「固定底部」
- **THEN** 版权条常驻视口底部；关闭时随内容滚动

### Requirement: 租户品牌应用
前端 SHALL 在登录后拉取当前租户品牌，并应用：主色覆盖默认主题色、Logo/品牌名显示于顶栏、版权显示于底部；字段为空时回退默认。

#### Scenario: 应用租户品牌
- **WHEN** 用户登录某租户
- **THEN** 顶栏标题/Logo、主题色、底部版权按该租户品牌渲染

#### Scenario: 缺省回退
- **WHEN** 租户未配置某品牌字段
- **THEN** 该字段回退为默认值（标题回退 name、主题色回退默认主色）

### Requirement: 顶栏租户切换
前端 SHALL 在顶栏为平台超管提供「切换租户」入口：列出全部租户，切换后替换 token、重置菜单/字典/权限等缓存并刷新。

#### Scenario: 切换租户
- **WHEN** 平台超管选择某租户并切换
- **THEN** 前端更新 token、重置缓存，按目标租户渲染菜单与数据

### Requirement: 布局设置持久化
所有布局与主题设置 SHALL 持久化到 localStorage，刷新页面后保持。

#### Scenario: 刷新保留
- **WHEN** 用户调整布局/主题/宽度等后刷新页面
- **THEN** 所有设置恢复为用户上次的配置

### Requirement: 面包屑
系统 SHALL 在内容区顶部显示面包屑，随当前路由与菜单层级展示当前位置。

#### Scenario: 面包屑导航
- **WHEN** 用户进入某个菜单页面
- **THEN** 面包屑显示当前菜单的层级路径

### Requirement: 多页签
系统 SHALL 支持多页签（tabs）视图：打开的页面保留为页签，可切换与关闭；切换页签时保留各页面的组件状态（keep-alive），关闭页签时销毁其状态。页面 SHALL 默认缓存，可通过路由 meta `keepAlive: false` 关闭缓存。

#### Scenario: 页签切换与关闭
- **WHEN** 用户打开多个菜单页面
- **THEN** 各页面以页签形式保留，可切换、可关闭

#### Scenario: 切换页签保留状态
- **WHEN** 用户在多个页签间切换
- **THEN** 各页签页面的组件状态（滚动/筛选/表单）被保留，不因切换而重建

#### Scenario: 关闭页签销毁状态
- **WHEN** 用户关闭某页签
- **THEN** 该页面的组件状态被销毁，再次打开时重建

#### Scenario: 页面关闭缓存
- **WHEN** 某页面声明路由 meta `keepAlive: false`
- **THEN** 该页面切换页签时不保留状态，每次进入重新构建

### Requirement: 顶栏全屏
系统 SHALL 在顶栏提供全屏切换按钮，进入/退出浏览器全屏。

#### Scenario: 全屏切换
- **WHEN** 用户点击全屏按钮
- **THEN** 页面进入浏览器全屏，再次点击退出

### Requirement: 菜单手风琴
侧边菜单 SHALL 支持手风琴模式：同一级只展开一个子菜单。

#### Scenario: 手风琴展开
- **WHEN** 开启手风琴且用户展开某个子菜单
- **THEN** 同级的其他已展开子菜单自动收起

### Requirement: 默认值集中配置
布局与主题的默认值 SHALL 在代码中集中配置（单一配置模块），开发者改一处即可统一调整；用户在页面上的修改覆盖默认值并持久化。

#### Scenario: 改默认值生效
- **WHEN** 开发者修改配置模块中的默认主题色或默认布局
- **THEN** 未手动改过的用户首次进入时按新默认值渲染；已手动改过的用户仍按自己的持久化设置

### Requirement: 菜单数据结构对齐后端
占位菜单数据 SHALL 采用后端资源实体（`resource`）的字段结构（`id/code/name/parentCode/type/path/component/icon/sort`），不自造字段名。

#### Scenario: 字段对齐
- **WHEN** 占位菜单被替换为后端「当前用户菜单树」接口数据
- **THEN** 前端无需改动数据结构即可直接渲染