planet/docs/technical/zh/frontend-admin-frontend-context.md

# 控制台前端结构

本文件描述当前控制台前端的真实结构，目标是帮助后续页面开发、表格改造、布局治理和状态收口时快速找到正确入口。

相关规则建议一起参考：

- [rules.md](/home/ray/dev/linkong/planet/rules.md)
- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)

## 当前目标

控制台前端承担的是后台工作台，而不是展示型大屏。当前约束是：

- 页面默认遵循单屏工作区
- 主交互在内部模块滚动，而不是依赖整页无限变长
- 列表、表格、分析页优先保证主工作区可见
- 通用布局、滚动条、表格滚动行为尽量复用，不要每页各写一套

## 当前路由入口

主入口在：

- [App.tsx](/home/ray/dev/linkong/planet/frontend/src/App.tsx)

当前后台相关路由包括：

- `/admin`
- `/users`
- `/datasources`
- `/data`
- `/alerts/system`
- `/alerts/bgp`
- `/alerts/situational`
- `/bgp`
- `/playground`
- `/settings`

`/earth` 是独立展示页，不属于控制台骨架。

## 当前页面骨架

控制台公共壳层在：

- [AppLayout.tsx](/home/ray/dev/linkong/planet/frontend/src/components/AppLayout/AppLayout.tsx)

职责：

- 左侧导航
- 折叠与展开
- 当前账号/版本信息
- 内容区高度闭合
- 全站统一侧边栏滚动条

当前结构是：

```tsx
<Layout className="dashboard-layout">
  <Sider className="dashboard-sider">...</Sider>
  <Layout>
    <Content className="dashboard-content">
      <div className="dashboard-content-inner">{children}</div>
    </Content>
  </Layout>
</Layout>
```

后续控制台页面应优先适配这套壳层，而不是重新定义全页高度语义。

## 当前共享组件

### 1. `Scrollbar`

文件：

- [Scrollbar.tsx](/home/ray/dev/linkong/planet/frontend/src/components/Scrollbar/Scrollbar.tsx)

用途：

- 控制台侧边栏这类普通内容容器
- 组件内部管理可见性、thumb 尺寸、拖拽和双轴 overflow 判定

当前约束：

- 滚动条必须是浮层，不参与布局
- 无 overflow 时不应留下可见痕迹
- 真实滚动仍交给原生容器，只替换可见层和交互层

### 2. `ScrollbarOverlay`

文件：

- [ScrollbarOverlay.tsx](/home/ray/dev/linkong/planet/frontend/src/components/Scrollbar/ScrollbarOverlay.tsx)

用途：

- Ant Table 这类内部已有滚动容器的区域
- 不接管滚动语义，只叠加新的滚动条可见层

当前使用场景：

- 数据源
- 采集数据
- 用户管理
- 设置页
- 告警页
- BGP 页面

### 3. `TableScrollRegion`

文件：

- [TableScrollRegion.tsx](/home/ray/dev/linkong/planet/frontend/src/components/Scrollbar/TableScrollRegion.tsx)

用途：

- 为表格滚动区提供统一包裹层
- 后续新表格页优先复用，不要重复写“表格区域 + overlay scrollbar”样板

### 4. `SegmentedControl`

文件：

- [SegmentedControl.tsx](/home/ray/dev/linkong/planet/frontend/src/components/SegmentedControl/SegmentedControl.tsx)
- [SegmentedControl.css](/home/ray/dev/linkong/planet/frontend/src/components/SegmentedControl/SegmentedControl.css)

用途：

- 语言切换、主题切换、模式切换这类 2 到 3 项的分段控制器
- 需要保留滑块动画、激活态和紧凑按钮布局的设置项
- 当前 `/docs` 页底部语言切换与主题切换已经复用它

接口语义：

- `options`：每个选项包含 `value`、`label`，可选 `icon`、`title`
- `value`：当前激活值
- `onChange`：切换选项时回调
- `ariaLabel`：控制器可访问名称
- `className`：业务页面用于覆盖尺寸或局部样式

当前约束：

- 组件自身负责滑块数量、位置和弹性动画
- 业务页面只传选项和状态，不要重复写私有 slider DOM
- 颜色优先通过 CSS 变量覆盖，避免在业务组件里硬编码主题色
- 适合少量互斥选项，不适合用作长列表、导航菜单或表单下拉

### 5. `MarkdownRenderer`

文件：

- [MarkdownRenderer.tsx](/home/ray/dev/linkong/planet/frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx)

用途：

- 渲染 `/docs` 的 Markdown 正文
- 支持标题、列表、引用、代码块、表格和基础行内格式
- 代码块和表格内部复用 `Scrollbar`，避免横向内容撑爆文档页

当前约束：

- 它不是完整 GitHub Markdown 引擎，只覆盖项目文档当前需要的语法
- 文档内部链接应通过 `transformLink` 转成 `/docs/:slug`
- 标题锚点由 `getHeadingId` 注入，避免渲染器自己理解路由状态

### 6. `TableActions`

文件：

- [TableActions.tsx](/home/ray/dev/linkong/planet/frontend/src/components/TableActions/TableActions.tsx)

用途：

- 表格操作列的统一操作入口
- 展开状态下直接展示按钮
- 收起状态下用更多菜单承载操作

配套导出：

- `actionCellProps`：用于操作列 `onCell`，防止操作按钮被省略号截断或换行

## 当前状态来源

### 1. 认证状态

文件：

- [auth.ts](/home/ray/dev/linkong/planet/frontend/src/stores/auth.ts)

职责：

- token
- 当前用户
- 登录/退出

`App.tsx` 用它判断是否进入登录页。

### 2. 业务数据网关

目前 AI / 态势感知相关服务集中在：

- [http-gateway.ts](/home/ray/dev/linkong/planet/frontend/src/services/situational-awareness/http-gateway.ts)
- [port.ts](/home/ray/dev/linkong/planet/frontend/src/services/situational-awareness/port.ts)
- [types.ts](/home/ray/dev/linkong/planet/frontend/src/services/situational-awareness/types.ts)

约束：

- 页面不要直接散落拼 URL
- 先通过 port/types 定义边界
- 再由 http/mock gateway 实现

## 当前页面分层建议

### 1. 仪表盘和摘要型页面

例如：

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

优先目标：

- 页头稳定
- 摘要卡片先紧凑化
- 主工作区占据主要高度

### 2. 表格型页面

例如：

- [DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx)
- [DataList.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataList/DataList.tsx)
- [Users.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Users/Users.tsx)
- [Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx)

约束：

- 优先内部滚动
- 不要让表格撑爆整页
- 新表格区域优先复用 `TableScrollRegion` / `ScrollbarOverlay`

### 3. 复杂工作区页面

例如：

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

约束：

- Tabs 里的内容不能套同一套高度逻辑
- 表格 tab、Markdown tab、配置 tab 要各自定义滚动责任
- AI 结果区、长文本区优先保证最小可读高度

## 当前布局约束

这些原则已经在项目里反复验证过：

1. 父容器高度链要闭合
2. `min-height: 0` 不能漏
3. overflow 责任必须明确
4. 不要用 `overflow: hidden` 掩盖结构问题
5. 不要为了摘要卡完整显示去压缩主工作区
6. 自定义滚动条必须是浮层，不得挤压内容宽度

详细经验见：

- [frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)

## 当前推荐改动方式

如果后续继续改后台页面，建议按这个顺序：

1. 先确认页面属于摘要页、表格页还是复杂工作区
2. 先接入现有壳层和滚动语义
3. 优先复用共享滚动组件
4. 最后再改视觉和细节交互

不要先写局部 CSS 补丁，再回头补结构。

## 当前明显边界

控制台前端和 Earth 前端不是一套系统：

- 控制台前端是 React + Ant Design 工作台
- Earth 前端是 `public/earth` 下的独立原生 HUD 系统

因此：

- 不要把 Earth 的 HUD/动画/状态机直接挪进控制台
- 不要把控制台表格/滚动策略硬套到 Earth HUD

Earth 相关结构见：

- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)