first commit
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-07-08
|
||||
@@ -0,0 +1,67 @@
|
||||
## Context
|
||||
|
||||
The platform_web console already exposes the required first-party product areas and now has automated browser acceptance proving API-backed behavior across 首页、服务器管理、插件市场、用户管理、AI 提供商管理, server detail, and plugin controls. The next gap is not a new product capability; it is interaction quality. The console needs clearer hierarchy, denser-but-readable operational surfaces, stronger feedback, and responsive confidence while preserving its game operations visual contract.
|
||||
|
||||
This change should stay inside platform_web interaction and visual polish. It must not introduce new business workflows, billing/cloud host flows, provider marketplaces, direct run access, or plugin transport shortcuts. It should use existing API-backed data and existing route contracts.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Turn UI dissatisfaction into objective acceptance criteria that implementation can complete and verify.
|
||||
- Polish navigation, first-party route scanability, state feedback, command affordances, and server detail workflows.
|
||||
- Keep the default black mecha console and optional magical-girl theme visually distinct while sharing the same layout and interaction model.
|
||||
- Reuse `theme/tokens.ts`, `theme/base.css`, and shared surface classes before adding new styles.
|
||||
- Require browser walkthrough evidence at desktop and mobile widths.
|
||||
- Keep automated browser acceptance passing after polish.
|
||||
|
||||
**Non-Goals:**
|
||||
- Do not change platform, run, plugin, AI provider, authorization, lifecycle, log, artifact, or config semantics.
|
||||
- Do not add billing, cloud host sales, agent-provider/cloud-provider workflows, or unrelated SaaS marketplace features.
|
||||
- Do not replace the visual direction with generic opaque SaaS cards, one-off dark dashboards, or unrelated gradients.
|
||||
- Do not add page-local fixed decorative spans, sparkles, sigils, snowflakes, hearts, moons, or other one-off background DOM.
|
||||
- Do not create a fixed left-list/right-detail master-detail layout for server or plugin details.
|
||||
- Do not bundle third-party character art or recognizable external visual assets.
|
||||
|
||||
## Decisions
|
||||
|
||||
1. Use accepted interaction criteria instead of taste-only language.
|
||||
|
||||
Each polished page should have observable requirements: clear primary action, visible loaded/empty/error state, scannable hierarchy, no overlapping UI, readable status signals, responsive behavior, and preserved API-backed markers. This makes the implementation measurable in tests and browser walkthroughs.
|
||||
|
||||
2. Polish shared primitives first.
|
||||
|
||||
The implementation should start with existing shared classes such as `metric-card`, `overview-card`, `console-panel`, `catalog-card`, `server-card`, `server-detail-header`, `resource-table-wrap`, `provider-table-wrap`, `drawer-panel`, `confirm-panel`, `plugin-group`, and `operation-item`. If a new reusable pattern is needed, it belongs in `theme/base.css` with token-driven styling, not inside page-local opaque card systems.
|
||||
|
||||
3. Preserve one route model across both themes.
|
||||
|
||||
Black mecha and magical-girl should differ through tokens, frame treatments, materials, motifs, and `MagicalParticleLayer`, not through separate page implementations. The same route structure should remain usable and readable in both themes.
|
||||
|
||||
4. Favor operational clarity over decoration.
|
||||
|
||||
Lifecycle actions, destructive confirmations, logs, diffs, config review, operation results, warnings, and AI recommendations must remain text-readable, traceable, and not color-only. Decorative theme effects must stay behind operational surfaces and respect reduced motion.
|
||||
|
||||
5. Use browser walkthroughs for acceptance, not screenshots alone.
|
||||
|
||||
Completion requires exercising the actual routes and workflows in a browser at representative desktop and mobile widths. Screenshots can help debugging, but accepted evidence should focus on route behavior, visible controls, responsive layout, and absence of overlap or sensitive/fallback content.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Visual polish can drift into scope expansion -> Keep tasks limited to platform_web interaction and theme presentation; do not change platform/run/plugin semantics.
|
||||
- Theme work can create duplicate styles -> Require shared token/classes first and update `theme/README.md` only when new shared patterns are introduced.
|
||||
- Responsive polishing can break automated acceptance markers -> Require automated browser acceptance after changes.
|
||||
- Dense game-console visuals can harm readability -> Require operational clarity for logs, tables, diffs, warnings, and command results.
|
||||
- Browser checks can be flaky -> Use stable routes, loaded states, viewport checks, and the existing local debug acceptance command.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Audit current first-party routes and server detail surfaces against the accepted interaction criteria.
|
||||
2. Polish shared theme/layout primitives and route components in small focused batches.
|
||||
3. Verify desktop and mobile browser walkthroughs across required routes and server detail workflows.
|
||||
4. Run platform_web tests/build and automated browser acceptance.
|
||||
5. Update task evidence and delivery stream pointers after verification passes.
|
||||
|
||||
Rollback is straightforward because the change should stay in platform_web presentation and interaction code. Revert affected styles/components if a polish pass harms usability or breaks acceptance.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None currently. If implementation discovers a needed new product behavior, split it into a future OpenSpec instead of expanding this polish change.
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
The console now has real API-backed coverage and automated browser acceptance, but the current interaction polish still depends on scattered page-level choices instead of explicit acceptance criteria. This change converts UI dissatisfaction into a concrete platform_web polish contract so the next implementation can improve usability without drifting into a generic SaaS dashboard or changing product scope.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Define accepted interaction/design criteria for the required first-party areas: 首页、服务器管理、插件市场、用户管理、AI 提供商管理.
|
||||
- Define server detail workflow polish for lifecycle controls, logs, config, plugin controls, AI assistant, and operation history.
|
||||
- Require responsive desktop/mobile walkthrough coverage and no visible overlap, clipped text, unreadable panels, or inaccessible control states.
|
||||
- Require the polish to preserve the existing black mecha default theme, magical-girl alternate theme, translucent game-operations surfaces, grouped navigation, and shared theme primitives.
|
||||
- Require compatibility with the automated browser acceptance suite so visual/interaction polish does not weaken API-backed route proof or safety scanning.
|
||||
- No breaking product behavior, API, authorization, plugin, run, billing, cloud-host, or provider-marketplace changes are expected.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `platform-interaction-design-polish`: Defines accepted interaction and visual polish requirements for platform_web first-party console areas, server detail workflows, responsive behavior, theme preservation, browser walkthrough evidence, and automated acceptance compatibility.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected roots: `platform_web/`, platform_web documentation, and OpenSpec delivery stream files.
|
||||
- Expected implementation areas: shared theme surfaces/classes, route/page layouts, command affordances, responsive behavior, state feedback, browser walkthrough evidence, and test coverage.
|
||||
- Validation impact: requires `cd platform_web && npm run typecheck && npm test && npm run build`, automated browser acceptance against the local debug stack, `scripts/check-structure.sh`, and `openspec validate polish-platform-interaction-design --strict`.
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: First-party routes provide accepted interaction polish
|
||||
The platform_web console SHALL provide polished, scannable, API-backed interaction surfaces for the required first-party areas without changing product scope.
|
||||
|
||||
#### Scenario: Home route has clear operational hierarchy
|
||||
- **WHEN** an operator opens 首页
|
||||
- **THEN** the route MUST present loaded platform overview state, key resource/health signals, game/plugin counts or equivalent operational summaries, and a clear refresh or recovery affordance without visible overlap or clipped primary labels
|
||||
|
||||
#### Scenario: Server management route is action-oriented and scannable
|
||||
- **WHEN** an operator opens 服务器管理
|
||||
- **THEN** the route MUST make server identity, lifecycle state, run assignment, filtering, creation entry point, and drill-in affordance easy to scan without using a fixed left-list/right-detail master-detail layout
|
||||
|
||||
#### Scenario: Plugin marketplace route communicates trust and capability
|
||||
- **WHEN** an operator opens 插件市场
|
||||
- **THEN** the route MUST present plugin identity, installed state, manifest reference, lifecycle capabilities, platform-mediated permissions, bridge actions, and validation state in a readable structure without unsafe runtime transport details
|
||||
|
||||
#### Scenario: User management route supports account operations clearly
|
||||
- **WHEN** an operator opens 用户管理
|
||||
- **THEN** the route MUST present API-connected account data, roles/statuses, create/edit affordances, and empty/error/loading states with text labels and non-color-only status cues
|
||||
|
||||
#### Scenario: AI provider route keeps sensitive settings understandable
|
||||
- **WHEN** an operator opens AI 提供商管理
|
||||
- **THEN** the route MUST present provider identity, connection status, relay mode, model/default-model information, and redacted key references without exposing raw keys or making status dependent on color alone
|
||||
|
||||
### Requirement: Server detail workflows are polished without direct run access
|
||||
The platform_web server detail route SHALL provide polished workflow surfaces for lifecycle, logs, config, plugin controls, AI assistant, and operation history while preserving platform-mediated boundaries.
|
||||
|
||||
#### Scenario: Server detail header and tabs show stable context
|
||||
- **WHEN** an operator opens `#/servers/server-local-debug` or another server detail route
|
||||
- **THEN** the route MUST keep server name, server ID, plugin version, run node, lifecycle state, and tab navigation visible and readable across desktop and mobile widths
|
||||
|
||||
#### Scenario: Lifecycle commands have safe feedback
|
||||
- **WHEN** an operator views or triggers lifecycle controls
|
||||
- **THEN** start/stop or equivalent controls MUST have clear labels, enabled/disabled states, confirmation or progress feedback where appropriate, and operation-history visibility without browser or plugin pages contacting run directly
|
||||
|
||||
#### Scenario: Logs, config, artifacts, and operation history remain traceable
|
||||
- **WHEN** an operator uses detail tabs for logs, config, plugin controls, AI assistant, or operation history
|
||||
- **THEN** each surface MUST show meaningful loaded/empty/error states, logical IDs or safe references, readable timestamps/statuses, and no raw host paths, sockets, credentials, or plugin-owned transport details
|
||||
|
||||
### Requirement: Visual system contract is preserved during polish
|
||||
The platform_web polish SHALL preserve the existing game operations visual direction and shared theme architecture.
|
||||
|
||||
#### Scenario: Shared theme primitives drive surfaces
|
||||
- **WHEN** implementation changes route or component presentation
|
||||
- **THEN** it MUST reuse or extend shared tokens/classes in `theme/tokens.ts` and `theme/base.css` rather than introducing page-local opaque card systems, one-off dark dashboards, or unrelated visual languages
|
||||
|
||||
#### Scenario: Black mecha and magical-girl themes stay distinct
|
||||
- **WHEN** an operator uses the default black mecha theme or optional magical-girl theme
|
||||
- **THEN** both themes MUST keep their theme-specific materials, readable translucent surfaces, grouped large-entry navigation, and background visibility while sharing the same product workflows
|
||||
|
||||
#### Scenario: Global decorative effects remain centralized
|
||||
- **WHEN** implementation changes ambient or decorative effects
|
||||
- **THEN** full-workspace theme-aware effects MUST remain in `components/MagicalParticleLayer.tsx` and MUST NOT use page-local fixed decorative DOM/CSS elements
|
||||
|
||||
### Requirement: Responsive browser walkthrough proves polish acceptance
|
||||
The polish change SHALL require browser verification across required routes and representative viewport sizes before completion.
|
||||
|
||||
#### Scenario: Desktop and mobile walkthroughs cover required routes
|
||||
- **WHEN** implementation claims the polished UI is accepted
|
||||
- **THEN** browser walkthrough evidence MUST cover 首页、服务器管理、插件市场、用户管理、AI 提供商管理, server detail workflows, and representative desktop and mobile viewport widths
|
||||
|
||||
#### Scenario: Walkthrough rejects layout regressions
|
||||
- **WHEN** browser walkthroughs inspect accepted routes
|
||||
- **THEN** they MUST reject visible overlap, clipped primary text, unreachable primary controls, unreadable loaded/error/empty states, and navigation states that hide required first-party areas
|
||||
|
||||
#### Scenario: Automated acceptance remains compatible
|
||||
- **WHEN** polish implementation is complete
|
||||
- **THEN** `scripts/browser-acceptance.sh` with the documented local debug environment MUST still pass and MUST continue proving API-backed content, fallback rejection, forbidden-fragment scanning, and platform-mediated plugin/server operation proof
|
||||
|
||||
### Requirement: Polish verification commands are concrete
|
||||
The OpenSpec tasks SHALL list reproducible commands that prove implementation quality.
|
||||
|
||||
#### Scenario: Verification commands are available
|
||||
- **WHEN** contributors read implementation tasks
|
||||
- **THEN** they MUST find concrete commands for platform_web typecheck/tests/build, automated browser acceptance, structure checks, and strict OpenSpec validation
|
||||
|
||||
#### Scenario: Evidence is recorded before task completion
|
||||
- **WHEN** implementation tasks are marked complete
|
||||
- **THEN** task evidence MUST record the browser walkthrough coverage, automated acceptance command output or evidence path, platform_web verification, `scripts/check-structure.sh`, and `openspec validate polish-platform-interaction-design --strict`
|
||||
@@ -0,0 +1,57 @@
|
||||
## 1. Interaction Audit and Acceptance Criteria
|
||||
|
||||
- [x] 1.1 Audit 首页、服务器管理、插件市场、用户管理、AI 提供商管理, and server detail against the accepted interaction polish requirements.
|
||||
- [x] 1.2 Identify any visible overlap, clipped labels, weak hierarchy, unclear primary actions, missing empty/error/loading states, or color-only status cues.
|
||||
- [x] 1.3 Confirm the implementation scope remains platform_web polish only and does not add billing, cloud host sales, provider marketplace workflows, direct run access, or plugin transport shortcuts.
|
||||
- [x] 1.4 Map every planned UI change to shared route components, shared theme primitives, or documented shared CSS additions.
|
||||
|
||||
## 2. Shared Theme and Layout Polish
|
||||
|
||||
- [x] 2.1 Reuse or extend `theme/tokens.ts` and `theme/base.css` for any new shared materials, frames, command states, tables, drawers, dialogs, or responsive primitives.
|
||||
- [x] 2.2 Preserve black mecha as the default theme and magical-girl as the alternate theme, with distinct token-driven materials and readable translucent surfaces.
|
||||
- [x] 2.3 Keep grouped large-entry navigation, large icon badges, bold Chinese labels, expandable child rows, active frames, and single-column/double-column density behavior.
|
||||
- [x] 2.4 Keep full-workspace decorative effects centralized in `components/MagicalParticleLayer.tsx`; do not add page-local fixed decorative DOM/CSS motifs.
|
||||
- [x] 2.5 Keep framed repeated items at 8px-or-less radii unless a native pill/circle control shape is required.
|
||||
|
||||
## 3. First-Party Route Polish
|
||||
|
||||
- [x] 3.1 Polish 首页 hierarchy so loaded platform overview, resource/health signals, game/plugin counts, and refresh/recovery affordance are clear at desktop and mobile widths.
|
||||
- [x] 3.2 Polish 服务器管理 so server identity, lifecycle state, run assignment, filters, creation entry point, and drill-in affordance are scannable without a fixed left-list/right-detail layout.
|
||||
- [x] 3.3 Polish 插件市场 so plugin identity, installed state, manifest reference, lifecycle capabilities, permissions, bridge actions, and validation state are readable and safe.
|
||||
- [x] 3.4 Polish 用户管理 so API-connected account rows, role/status cues, create/edit affordances, and loading/empty/error states are clear and not color-only.
|
||||
- [x] 3.5 Polish AI 提供商管理 so provider status, relay mode, model/default-model details, and redacted key references are readable without exposing raw keys.
|
||||
|
||||
## 4. Server Detail Workflow Polish
|
||||
|
||||
- [x] 4.1 Polish server detail header and tabs so server name, ID, plugin version, run node, lifecycle state, and tab navigation remain visible across desktop and mobile widths.
|
||||
- [x] 4.2 Polish lifecycle command states so start/stop controls have clear labels, disabled/progress behavior, confirmations or feedback where appropriate, and operation-history visibility.
|
||||
- [x] 4.3 Polish logs, config, plugin controls, AI assistant, artifacts, and operation history surfaces with meaningful loaded/empty/error states, safe logical IDs, readable timestamps, and traceable outcomes.
|
||||
- [x] 4.4 Confirm server detail and plugin controls remain platform-mediated and do not expose raw host paths, sockets, credentials, direct run URLs, or plugin-owned transports.
|
||||
|
||||
## 5. Browser Walkthrough and Automated Acceptance
|
||||
|
||||
- [x] 5.1 Run a browser walkthrough at a desktop viewport across 首页、服务器管理、插件市场、用户管理、AI 提供商管理, server detail, lifecycle controls, plugin controls, logs/config/AI/operation-history tabs, and record evidence.
|
||||
- [x] 5.2 Run a browser walkthrough at a mobile viewport across the same required first-party areas and server detail workflow surfaces, and record evidence.
|
||||
- [x] 5.3 Verify both black mecha and magical-girl themes preserve readable surfaces, distinct theme treatments, navigation clarity, and background visibility.
|
||||
- [x] 5.4 Run `LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh` and record the evidence path.
|
||||
|
||||
## 6. Verification and Stream Update
|
||||
|
||||
- [x] 6.1 Run `cd platform_web && npm run typecheck && npm test && npm run build` and record evidence.
|
||||
- [x] 6.2 Run `scripts/check-structure.sh` and record evidence.
|
||||
- [x] 6.3 Run `openspec validate polish-platform-interaction-design --strict` and record evidence.
|
||||
- [x] 6.4 If structural theme rules or shared style contracts change, update `platform_web/theme/README.md` and any relevant tests in the same change.
|
||||
- [x] 6.5 Update `openspec/changes/architecture-delivery-stream/delivery-plan.md` and `openspec/changes/architecture-delivery-stream/NEXT_CHANGE.md` after implementation evidence exists.
|
||||
|
||||
## Evidence
|
||||
|
||||
- `platform_web/pages/UsersPage.tsx`: added explicit loading, API fallback error, empty-state, and accessible row action labels for 用户管理.
|
||||
- `platform_web/pages/AiProvidersPage.tsx`: added an explicit empty-state for filtered AI provider lists while preserving redacted `apiKeyRef` display.
|
||||
- `platform_web/pages/ServersPage.tsx`: polished create workflow feedback with an inline result strip.
|
||||
- `platform_web/pages/PluginsPage.tsx`: polished plugin detail framing and action strip behavior.
|
||||
- `platform_web/theme/base.css`: hardened shared action strips, server toolbars, catalog cards, plugin detail panels, result strips, responsive grids, and table/workspace min-width behavior.
|
||||
- `platform_web/acceptance/browser-acceptance.mjs`: expanded browser acceptance to record desktop/mobile walkthroughs for black mecha and magical-girl themes, route marker checks, visible-layout checks, API-backed route proof, plugin controls, and operation-history proof.
|
||||
- Browser evidence: `LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh` passed; evidence file `/private/tmp/browser-local-debug-acceptance/browser-acceptance/browser-acceptance-evidence.json` records 7 required routes plus 4 walkthrough scenarios: desktop/mobile black mecha and desktop/mobile magical-girl.
|
||||
- Frontend evidence: `cd platform_web && npm run typecheck`, `cd platform_web && npm test` (11 files / 49 tests), and `cd platform_web && npm run build` passed.
|
||||
- Structure evidence: `scripts/check-structure.sh` passed.
|
||||
- OpenSpec evidence: `openspec validate polish-platform-interaction-design --strict` passed.
|
||||
Reference in New Issue
Block a user