46 lines
5.8 KiB
Markdown
46 lines
5.8 KiB
Markdown
# AGENTS.md for platform_web
|
|
|
|
This file applies to `platform_web/`.
|
|
|
|
## Frontend Scope
|
|
|
|
Build the actual management console, not a marketing site. Required first-party areas are 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
|
|
|
## Structure Rules
|
|
|
|
Do not define API clients, shared DTOs, route definitions, schemas, or bridge contracts inside page components. Put them in dedicated directories.
|
|
|
|
## Interaction Rules
|
|
|
|
Management list pages must keep the primary list, grid, or table as the full-width working surface. Do not add permanent right-side create/edit/detail panes or fixed left-list/right-form master-detail layouts for users, plugins, AI providers, servers, or similar management resources. Use modals, drawers, or detail routes for create, edit, and detail workflows unless an explicit future product/design decision requires an inline split layout.
|
|
|
|
Server card and resource-row action menus must behave like real compact dropdowns/popovers, not like full-height button towers. The screenshot-failure pattern is explicitly forbidden: opening "运行操作" or any similar trigger must not inject a tall vertical stack of large command buttons inside a card, over a card, or between cards where it covers metrics, health bars, titles, status badges, or neighboring cards.
|
|
|
|
Dropdown and contextual action menus must follow these rules:
|
|
|
|
- Anchor the menu to the trigger with a bounded floating layer that handles viewport collision; do not resize, stretch, or reflow the underlying card/list row when the menu opens.
|
|
- Keep the menu compact: normal actions use dense menu rows, grouped sections, or a primary action plus "more" menu. If there are too many operational actions for a compact popover, use a drawer, detail route, or command dialog instead of stacking oversized buttons.
|
|
- Preserve operational readability: the underlying card stats, progress bars, and status labels must remain legible and must not be dimmed, blurred, or physically covered except by the small anchored menu itself.
|
|
- Use shared command/menu styling and theme tokens. Do not create page-local translucent button slabs, repeated decorative icon rails, or one-off menu panels that bypass `theme/base.css`.
|
|
- Provide normal menu behavior: close on outside click, Escape, and item selection; support keyboard focus order; keep destructive/warning actions visibly labeled and icon-marked.
|
|
|
|
## Visual Style Rules
|
|
|
|
The platform_web visual system is a game operations console, not a generic SaaS dashboard. The default theme is black mecha; the selectable alternate theme is magical-girl. Future UI work must preserve the current style contract:
|
|
|
|
- Use the shared theme tokens in `theme/tokens.ts` and shared styles in `theme/base.css`; do not add page-local opaque card systems, one-off dark dashboards, or unrelated visual languages.
|
|
- Repeated console modules, record lists, compact status rows, metric strips, action rows, and access lists should use the shared `console-module`, `console-record-list`, `console-record`, `console-row-list`, `console-row`, `console-stat-strip`, `console-row-actions`, and `access-list` classes. Treat older page-specific operation/user/maintenance class names as compatibility aliases, not new style ownership.
|
|
- Keep major surfaces translucent enough for the selected desktop/background to remain visible: side navigation, account/profile controls, metric cards, console panels, server cards, server detail headers, tables, drawers, dialogs, plugin groups, and operation history.
|
|
- Preserve theme-specific materials: black mecha uses dark cockpit panels, angular clipped frames, cyan scanner lines, and amber energy accents; magical-girl uses pink jelly glass, gold star frames, ribbon glow, and visible magic-circle motifs.
|
|
- Theme changes must be isolated and complete. Switching from magical-girl to black mecha must clear previous magical variables and update root theme marker, sidebar subtitle, active navigation frame, swatch strip, and shared surface accessories together.
|
|
- Do not double-frame nested content. A `.state-view` inside an already framed shared parent such as a console panel, card, table wrapper, plugin group, `console-record`, or compatibility operation item is content only; the parent owns the visible border and accessory layer.
|
|
- Keep the primary menu as a compact admin sidebar with two states: expanded text menu and collapsed icon rail. Do not reintroduce the single-column / double-column menu toggle. The same route order should render as a restrained dark mecha operations rail in black mecha and as a semi-transparent pink frosted-glass rail with star-framed active states in magical-girl.
|
|
- Use `components/MagicalParticleLayer.tsx` for full-workspace theme-aware ultimate effects. Each theme should have a distinct low-cost “大招” scene, not a dense field of tiny rotating particles. Do not reintroduce hardcoded fixed decorative DOM/CSS elements such as page-local sparkles, hearts, moons, snowflakes, or sigils.
|
|
- Built-in backgrounds must stay original CSS/generated motif desktops. Do not bundle recognizable third-party character art. User-uploaded backgrounds are allowed and must render behind readable contrast overlays.
|
|
- Uploaded backgrounds take precedence over built-in desktop presets; the selected preset remains the fallback after the upload is removed.
|
|
- Non-dangerous commands may use theme-appropriate lucide icons. Destructive, failed, warning, and safety-critical operations must retain familiar warning/status iconography and text.
|
|
- Status, errors, operation results, logs, configuration diffs, and LLM review output must remain readable, traceable, and not color-only.
|
|
- Cards and framed repeated items should keep 8px-or-less radii unless a native control shape requires a pill or circle.
|
|
|
|
See `theme/README.md` before changing theme tokens, shared CSS surfaces, page chrome, account/theme settings, or background behavior.
|