376 lines
13 KiB
Markdown
376 lines
13 KiB
Markdown
# 控制台前端结构
|
||
|
||
本文件描述当前控制台前端的真实结构，目标是帮助后续页面开发、表格改造、布局治理和状态收口时快速找到正确入口。
|
||
|
||
相关规则建议一起参考：
|
||
|
||
- [项目规则](/home/ray/dev/linkong/planet/rules.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`
|
||
- `/ai`
|
||
- `/earth-content`
|
||
- `/collection-management`
|
||
- `/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`，避免横向内容撑爆文档页
|
||
- Docs 正文由后端 `/api/v1/docs/...` 按 Gatekeeper 权限返回；前端只渲染当前用户可见内容
|
||
|
||
当前约束：
|
||
|
||
- 它不是完整 GitHub Markdown 引擎，只覆盖项目文档当前需要的语法
|
||
- 文档内部链接应通过 `transformLink` 转成 `/docs/:slug`
|
||
- 标题锚点由 `getHeadingId` 注入，避免渲染器自己理解路由状态
|
||
|
||
### 6. `ConnectionTestInput`
|
||
|
||
文件：
|
||
|
||
- [ConnectionTestInput.tsx](/home/ray/dev/linkong/planet/frontend/src/components/ConnectionTestInput/ConnectionTestInput.tsx)
|
||
|
||
用途：
|
||
|
||
- Endpoint、Base URL 这类“输入值 + 连接验证”的控制台表单项
|
||
- AI Provider 和 WebSearch 的连接测试入口
|
||
- 后续采集器配置如果把连接测试放进输入框，也应复用它
|
||
|
||
当前约束：
|
||
|
||
- 输入框末端只显示一个插头/连接器图标，不再并排放“测试连接”文字按钮
|
||
- 禁用的集成能力必须同时置灰输入框和连接测试按钮
|
||
- 组件只负责输入框与测试入口组合，不保存业务状态；调用方仍负责表单值、loading、disabled 和连接请求
|
||
|
||
### 7. `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
|
||
- 当前用户
|
||
- Gatekeeper 权限组
|
||
- 登录/退出
|
||
|
||
`App.tsx` 用它判断是否进入登录页。`/docs` 仍是公开路由，但目录和正文由后端按 token 决定；未登录时只返回公开文档。
|
||
|
||
### 2. AI
|
||
|
||
文件：
|
||
|
||
- [AISettings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/AISettings/AISettings.tsx)
|
||
|
||
职责：
|
||
|
||
- `/ai` 独立承载 LLM Provider、AI Tool 配置和测试台，不再放在 `/settings` 的系统配置 tabs 中
|
||
- `模型供应商` tab 管理默认 provider、模型、base URL、provider key、本地 `aiprovider` 代理和连接测试；provider 和模型输入使用可输入组合框，models.dev 目录停更时用户仍可手动填新 provider/model
|
||
- `工具` tab 先通过下拉菜单选择工具，再管理对应配置；当前包含 WebSearch 和 OCR
|
||
- WebSearch 配置包含 provider、搜索 key、base URL、超时、结果数和高级 provider 参数
|
||
- OCR 配置包含 provider、Base URL、API Key、模型/engine、语言、超时、文件大小上限和输出格式
|
||
- `测试台` tab 嵌入原 Playground 的真实会话、预设请求和 AI Provider 状态调试
|
||
- 页面复用 Settings 的单屏 tabs、panel card 和内部滚动样式
|
||
- AI Provider / WebSearch 的连接测试使用 `ConnectionTestInput`，连接器图标固定在 Base URL 输入框末端；WebSearch 未启用时，除开关外的配置项和测试入口都置灰
|
||
|
||
旧的 `/settings?tab=ai` 应跳转到 `/ai?tab=providers`。
|
||
旧的 `/playground` 应跳转到 `/ai?tab=playground`。
|
||
|
||
### 3. 业务数据网关
|
||
|
||
目前 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`
|
||
|
||
### 数据源目录页
|
||
|
||
[DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx) 当前不再承担配置编辑职责，而是数据源目录和采集操作页。
|
||
|
||
当前页面边界：
|
||
|
||
- 内置数据源和自定义数据源合并为 `UnifiedDataSource`。
|
||
- 列表展示类型、状态、最近运行、采集进度和操作。
|
||
- 点击名称打开只读抽屉。
|
||
- 抽屉中明确显示“内置数据源”或“自定义数据源”。
|
||
- endpoint、headers、config 只展示，不在这里编辑。
|
||
- 需要凭证的采集器提示用户到“采集管理 -> 采集器”维护。
|
||
|
||
这个边界很重要：后续不要把自定义数据源编辑、内置 endpoint 覆盖或凭证表单再塞回 `/datasources`。这些配置入口统一放在 `/collection-management?tab=collector_credentials`。
|
||
|
||
页面顶部的总进度区域新增 `采集中 N` 标签：
|
||
|
||
- 仅在存在运行中采集任务时显示。
|
||
- 样式定义在 [index.css](/home/ray/dev/linkong/planet/frontend/src/index.css) 的 `data-source-bulk-toolbar__running-pill`。
|
||
- 点击后打开 `采集中任务` Modal。
|
||
- Modal 内展示每个运行任务的阶段、进度、已处理/总数。
|
||
|
||
这个标签和其他状态标签同排，但通过 hover、蓝色描边和箭头表示可交互，不应改成普通 Tag。
|
||
|
||
### 采集器设置页
|
||
|
||
[Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx) 会按路由进入三种模式：`/settings` 是系统设置，`/earth-content` 是 Earth 内容，`/collection-management` 是采集管理。`collector_credentials` tab 当前在 `/collection-management` 下显示为“采集器”。
|
||
|
||
当前页面边界：
|
||
|
||
- 下拉框选择所有内置采集器。
|
||
- 下拉框右侧只有一个插头图标按钮，用于健康检查。
|
||
- 状态标签在选择器下方展示 `未检查` / `可用` / `不可用`。
|
||
- 需要凭证的采集器将凭证卡片放在基础配置上方。
|
||
- 不需要凭证的采集器只显示基础配置：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` 渲染教程正文。
|
||
|
||
相关后端设计见：
|
||
|
||
- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
|
||
|
||
### Earth 内容页
|
||
|
||
`/earth-content` 复用 [Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx) 的单屏 tab 容器，但页面责任与系统设置分离：
|
||
|
||
- `电视直播` 迁移原直播源配置，继续管理 Earth 媒体面板内容源。
|
||
- `国界精度` 管理 Earth 静态国界资产：provider 状态、低精 fallback、高精 manifest/PMTiles、源配置 JSON 和构建动作。
|
||
- `地球底图`、`图层资源`、`三维素材`、`新闻锚点策略` 是占位页，只显示模块待接入，不造假接口或假数据。
|
||
|
||
系统级 `/settings` 不应再新增 Earth 体验资源或采集生命周期 tab；采集相关入口属于 `/collection-management`，Earth 展示资源属于 `/earth-content`。
|
||
|
||
### 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. 自定义滚动条必须是浮层，不得挤压内容宽度
|
||
|
||
详细经验见：
|
||
|
||
- [前端布局指南](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-layout-guidelines.md)
|