# Frontend Layout Guidelines

本项目后台页面默认遵循“单屏工作区”布局规范。目标不是让页面永远不溢出，而是确保在常见桌面视口下：

- 页面主结构能在一屏内看清
- 用户能同时看到页头、摘要区和主工作区
- 超出的内容在模块内部滚动，而不是把整页纵向撑爆

当前推荐参考实现：

- [frontend/src/pages/BGP/BGP.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/BGP/BGP.tsx)
- [frontend/src/index.css](/home/ray/dev/linkong/planet/frontend/src/index.css)

## 核心原则

### 1. 页面优先保证一屏工作区

管理页默认采用：

- 页头：标题、说明、主要操作
- 主工作区：统计卡、表格、图表、列表、标签页

推荐结构：

```tsx
<AppLayout>
  <div className="page-shell">
    <div className="page-shell__header">...</div>
    <div className="page-shell__body">...</div>
  </div>
</AppLayout>
```

页面总高度应被限制在 `AppLayout` 内容区内，而不是继续让整个页面自然向下增长。

### 2. 滚动优先发生在模块内部

如果表格、日志、长列表、图表明细超出空间：

- 让卡片内部滚动
- 让表格内部滚动
- 让标签页内容区内部滚动

不要默认依赖整个页面滚动去“解决”空间问题。

### 3. 主工作区必须拿到主要空间

页面里最重要的模块必须是视觉和空间上的主角。通常应保证：

- 页头始终可见
- 摘要区高度被控制
- 主表格 / 主图表 / 主分析区占据 50% 以上可视高度

如果一个页面有多个大模块，优先顺序是：

1. 先压缩说明区和摘要区
2. 再把次级模块收进标签页或切换视图
3. 最后才考虑继续增加整页滚动

### 4. 小屏幕和高缩放必须进入紧凑模式

在窗口高度较低、宽度较窄、或系统缩放较高时，应主动切换紧凑布局，例如：

- 缩小卡片 padding
- 缩小表头和单元格间距
- 将摘要区改为更紧凑的单行/横向滚动布局
- 将次级模块移入标签页、抽屉、折叠区

紧凑模式的目标是保持可用，不是单纯把文字和控件一股脑缩小。

### 5. overflow 责任必须明确

页面中的大块内容必须明确：

- 谁负责占满剩余高度
- 谁负责裁剪
- 谁负责滚动

常见要求：

- 父容器链路需要 `min-height: 0`
- 工作区容器通常需要 `display: flex`
- 真正的滚动节点要显式 `overflow: auto`

## 推荐实现模式

### 页面骨架

优先复用项目里已有的通用结构：

- `.dashboard-content-inner`
- `.page-shell`
- `.page-shell__header`
- `.page-shell__body`
- `.table-scroll-region`

不要每个页面都重新发明一套完全不同的高度和滚动语义。

### 表格工作区

推荐模式：

```tsx
<Card>
  <div className="table-scroll-region" ref={tableRegionRef}>
    <Table
      pagination={false}
      scroll={{ x: 1200, y: tableHeight }}
    />
  </div>
</Card>
```

要求：

- 表格尽量在卡片内部滚动
- `scroll.y` 应来自实际可用高度估算，而不是完全静态的魔法数字
- 父容器链路要保证 header、body、content 的 overflow 都在表格内部闭合

### 多模块页面

如果一个页面同时有：

- 摘要卡
- 表格
- 异常明细
- 最近事件

不建议简单纵向堆叠全部模块。优先使用：

- 顶部摘要 + 底部单一主工作区
- 标签页切换多个次级数据视图
- 左右分栏，并保证每栏内部独立滚动

## 不推荐的做法

以下模式默认视为不符合本项目页面规范：

- 依赖整页纵向滚动来显示主要工作区
- 一个页面纵向堆 3 到 4 个大卡片，每个都想完整展示
- 表格没有内部滚动，导致缩放后只能看到 1 到 2 行数据
- 父容器缺少 `min-height: 0`，导致内部滚动失效
- 只做视觉缩小，不处理真正的空间分配

## 页面验收检查清单

提交前至少检查：

- 页头、摘要区、主工作区能否同时出现
- 主工作区是否拿到了页面中最多的高度
- 表格或明细溢出时，滚动条是否出现在模块内部
- 浏览器缩放到 `125%` / `150%` 时是否仍可用
- 低高度窗口下是否还保有合理的可见内容行数
- Tabs、Card、Table 在 overflow 时是否仍可操作

## 落地顺序

后续新增或重构后台页时，优先按这个顺序设计：

1. 先定义主工作区
2. 再确定哪些模块必须常驻可见
3. 最后再做样式和视觉层次

简单说：

- 先保证空间分配正确
- 再处理滚动边界
- 最后再做美化