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

# Admin Frontend Context

This document describes the current real structure of the console frontend. The goal is to help future page development, table refactoring, layout governance, and state consolidation quickly find the right entry points.

Related references:

- [Project Rules](/home/ray/dev/linkong/planet/rules.md)
- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)

## Current Goal

The console frontend is a backend workbench, not a display-style dashboard. Current constraints:

- Pages default to a single-screen work area
- Primary interaction happens through in-module scrolling, not relying on the whole page growing infinitely
- Lists, tables, and analysis pages prioritize keeping the main work area visible
- Common layout, scrollbar, and table scroll behavior should be reused across pages

## Current Route Entry Points

Main entry point:

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

Admin Next now owns the official admin routes:

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

These routes render [AdminNextRoutes.tsx](/home/ray/dev/linkong/planet/frontend/src/admin-next/AdminNextRoutes.tsx). Page metadata and menu entries come from [manifest.tsx](/home/ray/dev/linkong/planet/frontend/src/admin-next/routes/manifest.tsx). `/admin-next/*` remains only as a compatibility entry and redirects to the official route; it is no longer a parallel primary entry.

The old AntD console remains available under `/legacy/admin/*` for comparison and rollback:

- `/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/*`

Legacy pages, `AppLayout`, `antd`, and `@ant-design/icons` stay in place during the legacy validation window. Do not remove them before Admin Next parity is accepted.

`/earth` is a standalone display page and is not part of the console shell.

## Current Page Shell

The official admin shell is at:

- [AdminNextLayout.tsx](/home/ray/dev/linkong/planet/frontend/src/admin-next/components/layout/AdminNextLayout.tsx)

Responsibilities:

- Left navigation, grouped collapse, and mobile drawer
- Current account, version, logout, and theme switching
- Top search, breadcrumbs, and page shortcuts
- Single-screen content-area height closure
- Coordination for Admin Next internal scrolling, tables, detail panels, and mobile detail views

The old AntD legacy shell remains at:

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

Legacy responsibilities:

- Left-side navigation
- Collapse and expand
- Current account / version information
- Content area height closure
- Site-wide unified sidebar scrollbar

Current structure:

```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>
```

Future official admin pages should adapt to `AdminNextLayout` and Admin Next page patterns rather than adding new capability to the old `AppLayout`. Only `/legacy/admin/*` maintenance should change the old shell.

## Admin Next Section Loading

Multi-tab pages are currently coordinated by [PlainResourcePages.tsx](/home/ray/dev/linkong/planet/frontend/src/admin-next/pages/PlainResourcePages.tsx), which hosts the current management and information workbench patterns. Section loading follows these rules:

- Initial page load requests only the active tab; it does not prefetch every tab endpoint.
- Switching tabs lazily loads that tab. Loaded tabs stay cached in local `states`, so returning to a tab reuses the previous data.
- Explicit actions such as refresh, save, test, upload, and credential-guide generation refresh only the current section instead of fanning out to unrelated sections.
- Datasource directory filter changes clear the built-in-source section cache and reload the current section with the new filters.
- Top summary metrics count loaded sections only, so unopened tabs are not reported as failed interfaces.

This keeps Earth, AI, collection management, and other multi-section pages from flooding backend APIs on cold start while preserving a fast cached tab-switching experience. Full health checks should use backend health endpoints or explicit refresh flows rather than relying on page initialization to touch every business endpoint.

## Current Shared Components

### 1. `Scrollbar`

File:

- [Scrollbar.tsx](/home/ray/dev/linkong/planet/frontend/src/components/tactile-ui/Scrollbar.tsx)
- [Tactile UI Components](/home/ray/dev/linkong/planet/docs/technical/en/tactile-ui-components.md)

Purpose:

- Ordinary content containers like the console sidebar
- Internally manages visibility, thumb size, drag, and dual-axis overflow detection

Current constraint:

- The scrollbar must be a floating overlay that does not participate in layout
- Should leave no visible trace when there is no overflow
- Real scrolling is still handled by the native container; only the visible layer and interaction layer are replaced

### 2. `ScrollbarOverlay`

File:

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

Purpose:

- Areas like Ant Table that already have an internal scroll container
- Does not take over scroll semantics; only adds a new scrollbar visible layer

Current usage:

- Admin Next data sources, collected data, collection management, logs, alerts, and BGP pages
- Old AntD legacy pages continue using shared scrolling behavior through compatibility wrappers

### 3. `TableScrollRegion`

File:

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

Purpose:

- Provides a unified wrapper for table scroll areas
- New table pages should reuse this rather than repeating the "table area + overlay scrollbar" boilerplate

### 4. `TactileButton` / `TactileSwitch` / `ControlGroup`

Files:

- [Button.tsx](/home/ray/dev/linkong/planet/frontend/src/components/tactile-ui/Button.tsx)
- [Switch.tsx](/home/ray/dev/linkong/planet/frontend/src/components/tactile-ui/Switch.tsx)
- [ControlGroup.tsx](/home/ray/dev/linkong/planet/frontend/src/components/tactile-ui/ControlGroup.tsx)

Purpose:

- Admin Next global tool buttons and detail-panel toolbars
- Icon-only ordinary actions with tooltips
- Strong-intent actions such as save, create, confirm, delete, and stop
- Compact switches aligned with the Docs theme slider

Current constraints:

- Neutral buttons default to a white tactile surface with external shadow
- Unambiguous actions prefer icon + tooltip; strong-intent actions like save may keep text
- Feature pages should customize through props and CSS variables, not by rewriting core button CSS

### 5. `SegmentedControl`

Files:

- [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)

Purpose:

- Segmented controls for language, theme, mode, or other 2 to 3 option settings
- Settings that need the shared animated slider, active state, and compact button layout
- The `/docs` footer language switcher and theme switcher already reuse it

Interface semantics:

- `options`: each option contains `value` and `label`, with optional `icon` and `title`
- `value`: current active value
- `onChange`: called when the selected option changes
- `ariaLabel`: accessible name for the control
- `className`: page-level hook for size or local style overrides

Current constraints:

- The component owns slider count, position, and spring-like transition
- Feature pages should only pass options and state, not recreate private slider DOM
- Prefer CSS variable overrides for colors instead of hard-coding theme colors in feature components
- Best for a small set of mutually exclusive choices; do not use it as a long list, navigation menu, or select replacement

### 6. `MarkdownRenderer`

File:

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

Purpose:

- Renders Markdown content for `/docs`
- Supports headings, lists, blockquotes, code blocks, tables, and basic inline formatting
- Code blocks and tables reuse `Scrollbar` so horizontal content does not blow out the docs page
- Docs content is returned by backend `/api/v1/docs/...` endpoints according to Gatekeeper permissions; the frontend only renders content visible to the current user

Current constraints:

- It is not a full GitHub Markdown engine; it only covers the syntax currently needed by project docs
- Internal document links should be converted to `/docs/:slug` through `transformLink`
- Heading anchors are injected through `getHeadingId`, keeping route state outside the renderer

### 7. `ConnectionTestInput`

File:

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

Purpose:

- Console form fields that combine an endpoint/Base URL value with a connection check
- Connection-test entry points for AI Provider and WebSearch
- Future collector configuration fields should reuse it when the test action belongs inside the input

Current constraints:

- The input suffix shows a single plug/connector icon, not an adjacent text button
- Disabled integrations must grey out both the input and its connection-test action
- The component only combines the input and action; callers still own form state, loading, disabled state, and the request itself

### 8. `TableActions`

File:

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

Purpose:

- Shared action entry for table operation columns
- Shows inline actions when expanded
- Uses a more-actions dropdown when collapsed

Companion export:

- `actionCellProps`: for action-column `onCell`, preventing action buttons from being ellipsized or wrapped

## Current State Sources

### 1. Auth State

File:

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

Responsibilities:

- Token
- Current user
- Gatekeeper groups
- Login / logout

`App.tsx` uses it to decide whether to redirect to the login page. `/docs` remains a public route, but the backend decides the visible catalog and content from the token; anonymous visitors only receive public docs.

### 2. AI

File:

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

Responsibilities:

- `/ai` now owns LLM Provider, AI Tool configuration, and the testbench instead of nesting them under `/settings`
- The `模型供应商` tab manages default provider, model, base URL, provider key, local `aiprovider` proxy, and connection test; provider and model fields use editable comboboxes so users can manually enter new providers/models if the models.dev catalog stops updating
- The `工具` tab first selects a tool from a dropdown menu, then renders that tool's configuration; it currently includes WebSearch and OCR
- WebSearch configuration includes provider, search key, base URL, timeout, result count, and advanced provider options
- OCR configuration includes provider, Base URL, API key, model/engine, languages, timeout, file-size limit, and output format
- The `测试台` tab embeds the former Playground real session, preset prompts, and AI Provider status debugging
- The page reuses the Settings single-screen tabs, panel card, and internal scrolling style
- AI Provider and WebSearch connection tests use `ConnectionTestInput`, with the connector icon fixed at the end of the Base URL input; when WebSearch is disabled, every configuration field and the test entry point are greyed out except the switch

Legacy `/settings?tab=ai` should redirect to `/ai?tab=providers`.
Legacy `/playground` should redirect to `/ai?tab=playground`.

### 3. Business Data Gateway

AI / situational awareness related services are currently in:

- [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)

Constraints:

- Pages must not scatter URL construction directly
- Define boundaries through port/types first
- Then implement via http/mock gateway

## Current Page Layer Recommendations

### 1. Dashboard and Summary Pages

Example:

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

Priority goals:

- Stable header
- Summary cards compact first
- Main work area occupies primary height

### 2. Table Pages

Examples:

- [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)

Constraints:

- Prefer internal scrolling
- Do not let tables blow out the full page
- New table areas should reuse `TableScrollRegion` / `ScrollbarOverlay`

### Datasource Directory Page

[DataSources.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/DataSources/DataSources.tsx) is the datasource directory and collection operation page. It should not grow back into a configuration editor.

Current page boundary:

- Built-in and custom sources are merged as `UnifiedDataSource`.
- The list shows type, state, last run, collection progress, and actions.
- Clicking a name opens a read-only drawer.
- Endpoint, headers, and config are displayed here, not edited.
- Credential-bearing collectors point users to `Collection Management -> Collectors`.

Keep this boundary: do not put custom datasource editing, built-in endpoint overrides, or credential forms back into `/datasources`. Those configuration entry points live at `/collection-management?tab=collector_credentials`.

### Collectors Page

[Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx) has three route modes: `/settings` for System Settings, `/earth-content` for Earth Content, and `/collection-management` for Collection Management. The `collector_credentials` tab is shown as `Collectors` under `/collection-management`.

Current boundary:

- The dropdown selects built-in collectors.
- The plug icon beside the dropdown runs the health check.
- Credential-bearing collectors place credential forms above base config.
- Free collectors show endpoint, default endpoint, headers, timeout, and retry.
- BarentsWatch AIS keeps its dedicated credential form.

### Earth Content Page

`/earth-content` reuses the same single-screen tab container from [Settings.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/Settings/Settings.tsx), but its ownership is separate from System Settings:

- `TV Livestream` owns the Earth media-panel source configuration.
- `Boundary Precision` owns the Earth static boundary asset state: provider, low-precision fallback, high-precision manifest/PMTiles, source JSON, and build action.
- `Base Map`, `Layer Resources`, `3D Assets`, and `News Anchor Strategy` are placeholders only. They show module status and do not invent fake APIs or fake data.

Do not add Earth experience resources or collection-lifecycle tabs back into `/settings`; collection belongs to `/collection-management`, and Earth display resources belong to `/earth-content`.

### 3. Complex Workspace Pages

Examples:

- [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)

Constraints:

- Tab content must not share the same height logic
- Table tabs, Markdown tabs, and config tabs each need their own scroll responsibility
- AI result areas and long text areas should maintain a minimum readable height

## Current Layout Constraints

These principles have been repeatedly validated in the project:

1. Parent container height chain must close
2. `min-height: 0` must not be omitted
3. Overflow responsibility must be explicit
4. Do not use `overflow: hidden` to mask structural issues
5. Do not compress the main work area to make summary cards show completely
6. Custom scrollbars must be floating overlays; they must not squeeze content width

For detailed experience, see:

- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)

## Recommended Change Approach

For future console page changes:

1. Confirm whether the page is a summary page, table page, or complex workspace
2. Integrate into the existing shell and scroll semantics first
3. Reuse shared scroll components
4. Handle visual and detail interactions last

Do not write local CSS patches first, then retrofit the structure.

## Current Clear Boundary

The console frontend and the Earth frontend are not the same system:

- Console frontend: React + Ant Design workbench
- Earth frontend: independent native HUD system under `public/earth`

Therefore:

- Do not move Earth's HUD / animations / state machine directly into the console
- Do not force the console's table / scroll strategy onto the Earth HUD

For Earth-related structure, see:

- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)