11 KiB
控制台前端结构
本文件描述当前控制台前端的真实结构，目标是帮助后续页面开发、表格改造、布局治理和状态收口时快速找到正确入口。
相关规则建议一起参考：
当前目标
控制台前端承担的是后台工作台，而不是展示型大屏。当前约束是：
- 页面默认遵循单屏工作区
- 主交互在内部模块滚动，而不是依赖整页无限变长
- 列表、表格、分析页优先保证主工作区可见
- 通用布局、滚动条、表格滚动行为尽量复用，不要每页各写一套
当前路由入口
主入口在：
当前后台相关路由包括：
/admin/users/datasources/data/alerts/system/alerts/bgp/alerts/situational/bgp/ai/settings
/earth 是独立展示页，不属于控制台骨架。
当前页面骨架
控制台公共壳层在：
职责：
- 左侧导航
- 折叠与展开
- 当前账号/版本信息
- 内容区高度闭合
- 全站统一侧边栏滚动条
当前结构是：
<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
文件：
用途：
- 控制台侧边栏这类普通内容容器
- 组件内部管理可见性、thumb 尺寸、拖拽和双轴 overflow 判定
当前约束：
- 滚动条必须是浮层，不参与布局
- 无 overflow 时不应留下可见痕迹
- 真实滚动仍交给原生容器，只替换可见层和交互层
2. ScrollbarOverlay
文件：
用途：
- Ant Table 这类内部已有滚动容器的区域
- 不接管滚动语义，只叠加新的滚动条可见层
当前使用场景：
- 数据源
- 采集数据
- 用户管理
- 设置页
- 告警页
- BGP 页面
3. TableScrollRegion
文件：
用途：
- 为表格滚动区提供统一包裹层
- 后续新表格页优先复用，不要重复写“表格区域 + overlay scrollbar”样板
4. SegmentedControl
文件：
用途：
- 语言切换、主题切换、模式切换这类 2 到 3 项的分段控制器
- 需要保留滑块动画、激活态和紧凑按钮布局的设置项
- 当前
/docs页底部语言切换与主题切换已经复用它
接口语义：
options：每个选项包含value、label，可选icon、titlevalue：当前激活值onChange：切换选项时回调ariaLabel：控制器可访问名称className：业务页面用于覆盖尺寸或局部样式
当前约束：
- 组件自身负责滑块数量、位置和弹性动画
- 业务页面只传选项和状态，不要重复写私有 slider DOM
- 颜色优先通过 CSS 变量覆盖，避免在业务组件里硬编码主题色
- 适合少量互斥选项，不适合用作长列表、导航菜单或表单下拉
5. MarkdownRenderer
文件：
用途：
- 渲染
/docs的 Markdown 正文 - 支持标题、列表、引用、代码块、表格和基础行内格式
- 代码块和表格内部复用
Scrollbar，避免横向内容撑爆文档页 - Docs 正文由后端
/api/v1/docs/...按 Gatekeeper 权限返回；前端只渲染当前用户可见内容
当前约束：
- 它不是完整 GitHub Markdown 引擎，只覆盖项目文档当前需要的语法
- 文档内部链接应通过
transformLink转成/docs/:slug - 标题锚点由
getHeadingId注入，避免渲染器自己理解路由状态
6. TableActions
文件：
用途：
- 表格操作列的统一操作入口
- 展开状态下直接展示按钮
- 收起状态下用更多菜单承载操作
配套导出：
actionCellProps：用于操作列onCell，防止操作按钮被省略号截断或换行
当前状态来源
1. 认证状态
文件：
职责：
- token
- 当前用户
- Gatekeeper 权限组
- 登录/退出
App.tsx 用它判断是否进入登录页。/docs 仍是公开路由，但目录和正文由后端按 token 决定；未登录时只返回公开文档。
2. AI
文件：
职责：
/ai独立承载 LLM Provider、AI Tool 配置和测试台，不再放在/settings的系统配置 tabs 中模型供应商tab 管理默认 provider、模型、base URL、provider key、本地aiprovider代理和连接测试工具tab 管理 WebSearch provider、搜索 key、base URL、超时、结果数和高级 provider 参数测试台tab 嵌入原 Playground 的真实会话、预设请求和 AI Provider 状态调试- 页面复用 Settings 的单屏 tabs、panel card 和内部滚动样式
旧的 /settings?tab=ai 应跳转到 /ai?tab=providers。
旧的 /playground 应跳转到 /ai?tab=playground。
3. 业务数据网关
目前 AI / 态势感知相关服务集中在：
约束：
- 页面不要直接散落拼 URL
- 先通过 port/types 定义边界
- 再由 http/mock gateway 实现
当前页面分层
1. 仪表盘和摘要型页面
例如：
优先目标：
- 页头稳定
- 摘要卡片先紧凑化
- 主工作区占据主要高度
2. 表格型页面
例如：
约束：
- 优先内部滚动
- 不要让表格撑爆整页
- 新表格区域优先复用
TableScrollRegion/ScrollbarOverlay
数据源目录页
DataSources.tsx 当前不再承担配置编辑职责，而是数据源目录和采集操作页。
当前页面边界：
- 内置数据源和自定义数据源合并为
UnifiedDataSource。 - 列表展示类型、状态、最近运行、采集进度和操作。
- 点击名称打开只读抽屉。
- 抽屉中明确显示“内置数据源”或“自定义数据源”。
- endpoint、headers、config 只展示，不在这里编辑。
- 需要凭证的采集器提示用户到“设置 -> 采集器设置”维护。
这个边界很重要：后续不要把自定义数据源编辑、内置 endpoint 覆盖或凭证表单再塞回 /datasources。这些配置入口统一放在 /settings?tab=collector_credentials。
页面顶部的总进度区域新增 采集中 N 标签：
- 仅在存在运行中采集任务时显示。
- 样式定义在 index.css 的
data-source-bulk-toolbar__running-pill。 - 点击后打开
采集中任务Modal。 - Modal 内展示每个运行任务的阶段、进度、已处理/总数。
这个标签和其他状态标签同排，但通过 hover、蓝色描边和箭头表示可交互，不应改成普通 Tag。
采集器设置页
Settings.tsx 中的 collector_credentials tab 当前显示为“采集器设置”。
当前页面边界：
- 下拉框选择所有内置采集器。
- 下拉框右侧只有一个插头图标按钮，用于健康检查。
- 状态标签在选择器下方展示
未检查/可用/不可用。 - 需要凭证的采集器将凭证卡片放在基础配置上方。
- 不需要凭证的采集器只显示基础配置：endpoint、默认 endpoint、请求头、timeout、retry。
BarentsWatch AIS使用专用凭证表单。
连接图标使用内联 PlugConnectIcon，视觉语义来自 Tabler plug-connected。后续如果控制台重写图标体系，应迁移到 Tabler Icons，而不是继续使用 Ant Design 刷新图标表达连接。
Client Secret 的表单语义：
- 已配置时，输入框显示脱敏 preview。
- 聚焦且当前值等于 preview 时清空，方便输入新 secret。
- 保存时如果值仍等于 preview，提交空值表示保留原 secret。
- 不再提供单独的“清除当前 secret”复选框。
凭证教程 Modal：
GET /api/v1/settings/credential-guides/{provider}读取教程。POST /generate调用 AI Provider 重新生成教程。POST /reset恢复默认教程。- Modal 使用
MarkdownRenderer渲染教程正文。
相关后端设计见：
3. 复杂工作区页面
例如：
约束：
- Tabs 里的内容不能套同一套高度逻辑
- 表格 tab、Markdown tab、配置 tab 要各自定义滚动责任
- AI 结果区、长文本区优先保证最小可读高度
当前布局约束
这些原则已经在项目里反复验证过：
- 父容器高度链要闭合
min-height: 0不能漏- overflow 责任必须明确
- 不要用
overflow: hidden掩盖结构问题 - 不要为了摘要卡完整显示去压缩主工作区
- 自定义滚动条必须是浮层，不得挤压内容宽度
详细经验见：