linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
fbca3815129898b44036d0577ccb2b543b46d5a7
planet/docs/technical/zh/frontend-admin-frontend-context.md
linkong fbca381512
Some checks failed
ci / backend (push) Has been cancelled
Details
ci / frontend (push) Has been cancelled
Details
ci / delivery (push) Has been cancelled
Details
release / images (push) Has been cancelled
Details
release: bump version to 0.62.0
2026-05-21 01:37:32 +08:00

17 KiB
Raw Blame History

控制台前端结构

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

相关规则建议一起参考：

当前目标

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

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

当前路由入口

主入口在：

当前正式后台路由已经由 Admin Next 接管：

  • /admin
  • /users
  • /datasources
  • /data
  • /alerts/system
  • /alerts/bgp
  • /alerts/situational
  • /bgp
  • /ai
  • /earth-content
  • /collection-management
  • /settings

这些路径渲染 AdminNextRoutes.tsx，页面清单和菜单元信息来自 manifest.tsx。/admin-next/* 仅作为兼容入口存在，会重定向到上面的正式路径，不再作为并行主入口。

旧 AntD 控制台保留在 /legacy/admin/*，用于对照和回退：

  • /legacy/admin
  • /legacy/admin/datasources
  • /legacy/admin/data
  • /legacy/admin/collection-management
  • /legacy/admin/earth-content
  • /legacy/admin/ai
  • /legacy/admin/logs
  • /legacy/admin/settings
  • /legacy/admin/users
  • /legacy/admin/bgp
  • /legacy/admin/alerts/*

旧页面、AppLayout、antd 和 @ant-design/icons 在 legacy 验收期继续保留。不要在新版 parity 验收前删除这些文件或依赖。

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

当前页面骨架

正式后台公共壳层在：

职责：

  • 左侧导航、分组折叠和移动端抽屉
  • 当前账号、版本、退出登录和主题切换
  • 顶部搜索、面包屑和页面快捷入口
  • 内容区单屏高度闭合
  • Admin Next 内部滚动、表格、详情面板和移动端详情视图协调

旧 AntD legacy 壳层仍在：

legacy 职责：

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

当前结构是：

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

后续正式控制台页面应优先适配 AdminNextLayout 和 Admin Next 页面模式，而不是继续往旧 AppLayout 增加新能力。只有维护 /legacy/admin/* 时才应修改旧壳层。

Admin Next 分区加载策略

多 tab 页面由 PlainResourcePages.tsx 统一承载当前的管理型和信息型工作台。分区加载规则是：

  • 初次进入页面只请求当前 active tab，不预先拉取所有 tab 的接口。
  • 用户切换 tab 时懒加载该 tab；已经加载过的 tab 保留在本地 states 缓存中，切回时直接复用。
  • 手动刷新、保存、测试、上传、生成教程等明确动作只刷新当前分区，避免把无关分区的接口一起打出去。
  • 数据源目录的筛选条件变化会清掉内置源分区缓存，并按新筛选重新请求当前分区。
  • 顶部 summary 只统计“已加载分区”，不把未访问 tab 误报成异常接口。

这样做是为了降低 Earth、AI、采集管理等多分区页面的冷启动压力，同时保留 tab 数量、状态和用户切换后的缓存体验。需要全量健康巡检时应走后端健康接口或显式刷新流程，不要依赖页面初始化时顺手拉所有业务接口。

当前共享组件

1. Scrollbar

文件：

用途：

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

当前约束：

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

2. ScrollbarOverlay

文件：

用途：

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

当前使用场景：

  • Admin Next 数据源、采集数据、采集管理、日志、告警和 BGP 页面
  • 旧 AntD legacy 页面通过兼容封装继续使用共享滚动能力

3. TableScrollRegion

文件：

用途：

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

4. TactileButton / TactileSwitch / ControlGroup

文件：

用途：

  • Admin Next 全局工具按钮和详情页工具按钮
  • icon-only + tooltip 的普通操作
  • 保存、创建、确认、删除、停止等强意图操作
  • 与 Docs 主题滑块一致的紧凑开关

当前约束：

  • 默认按钮是白色触感按钮，通过外部投影表达轻微立体感
  • 无歧义动作优先图标 + tooltip；保存这类强意图动作可保留文字
  • 业务页面通过 props 和 CSS variables 调整，不要直接手写按钮核心样式

5. SegmentedControl

文件：

用途：

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

接口语义：

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

当前约束：

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

6. MarkdownRenderer

文件：

用途：

  • 渲染 /docs 的 Markdown 正文
  • 支持标题、列表、引用、代码块、表格和基础行内格式
  • 代码块和表格内部复用 Scrollbar，避免横向内容撑爆文档页
  • Docs 正文由后端 /api/v1/docs/... 按 Gatekeeper 权限返回；前端只渲染当前用户可见内容

当前约束：

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

7. ConnectionTestInput

文件：

用途：

  • Endpoint、Base URL 这类“输入值 + 连接验证”的控制台表单项
  • AI Provider 和 WebSearch 的连接测试入口
  • 后续采集器配置如果把连接测试放进输入框，也应复用它

当前约束：

  • 输入框末端只显示一个插头/连接器图标，不再并排放“测试连接”文字按钮
  • 禁用的集成能力必须同时置灰输入框和连接测试按钮
  • 组件只负责输入框与测试入口组合，不保存业务状态；调用方仍负责表单值、loading、disabled 和连接请求

8. 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 代理和连接测试；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 / 态势感知相关服务集中在：

约束：

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

当前页面分层

1. 仪表盘和摘要型页面

例如：

优先目标：

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

2. 表格型页面

例如：

约束：

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

数据源目录页

DataSources.tsx 当前不再承担配置编辑职责，而是数据源目录和采集操作页。

当前页面边界：

  • 内置数据源和自定义数据源合并为 UnifiedDataSource。
  • 列表展示类型、状态、最近运行、采集进度和操作。
  • 点击名称打开只读抽屉。
  • 抽屉中明确显示“内置数据源”或“自定义数据源”。
  • endpoint、headers、config 只展示，不在这里编辑。
  • 需要凭证的采集器提示用户到“采集管理 -> 采集器”维护。

这个边界很重要：后续不要把自定义数据源编辑、内置 endpoint 覆盖或凭证表单再塞回 /datasources。这些配置入口统一放在 /collection-management?tab=collector_credentials。

页面顶部的总进度区域新增 采集中 N 标签：

  • 仅在存在运行中采集任务时显示。
  • 样式定义在 index.css 的 data-source-bulk-toolbar__running-pill。
  • 点击后打开 采集中任务 Modal。
  • Modal 内展示每个运行任务的阶段、进度、已处理/总数。

这个标签和其他状态标签同排，但通过 hover、蓝色描边和箭头表示可交互，不应改成普通 Tag。

采集器设置页

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 渲染教程正文。

相关后端设计见：

Earth 内容页

/earth-content 复用 Settings.tsx 的单屏 tab 容器，但页面责任与系统设置分离：

  • 电视直播 迁移原直播源配置，继续管理 Earth 媒体面板内容源。
  • 国界精度 管理 Earth 静态国界资产：provider 状态、低精 fallback、高精 manifest/PMTiles、源配置 JSON 和构建动作。
  • 地球底图、图层资源、三维素材、新闻锚点策略 是占位页，只显示模块待接入，不造假接口或假数据。

系统级 /settings 不应再新增 Earth 体验资源或采集生命周期 tab；采集相关入口属于 /collection-management，Earth 展示资源属于 /earth-content。

3. 复杂工作区页面

例如：

约束：

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

当前布局约束

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

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

详细经验见：

Reference in New Issue View Git Blame Copy Permalink