Complete platform management workflows

2026-07-14 16:39:37 +08:00
parent 7e05d0a4e7
commit 4f33f761a3
106 changed files with 11313 additions and 460 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-12
@@ -0,0 +1,102 @@
+## Context
+
+The platform web console already includes the required first-party routes for overview, server management, plugin marketplace, user management, and AI provider management. The current pages are uneven: some are data-backed, some fall back to local demonstration data, and several management surfaces expose create or status actions without complete edit, deletion, retirement, or operational error handling.
+
+This change completes the management console without changing the product scope. Browser code continues to call platform APIs only. AI provider keys remain owned by `platform/`. Run internals, host paths, raw credentials, and direct sockets remain outside `platform_web/` and plugin pages.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make visible management data come from platform APIs in normal operation, with explicit empty/error states when APIs are unavailable.
+- Complete user management for editing profile/contact fields, roles, status, and removal or deactivation.
+- Complete server management for metadata edits, safe delete/archive, administrator assignment, lifecycle feedback, and detail refresh.
+- Complete plugin marketplace behavior for real API data, state actions, detail refresh, and no production demo fallback masking failures.
+- Complete AI provider management for correct empty-list behavior, create/update/status/test/model refresh, and deletion or disable-only retirement semantics.
+- Keep frontend DTOs, validators, route contracts, and shared view contracts outside page components.
+- Preserve the platform_web theme and visual system while making controls dense enough for routine operations.
+
+**Non-Goals:**
+
+- No billing, cloud host sales, provider marketplace, or agent-provider/cloud-provider workflow.
+- No direct plugin-to-run access and no browser access to run credentials, host paths, or raw sockets.
+- No raw AI key entry or display in `platform_web`; the UI continues to work with secret references only.
+- No replacement of the hash router, design system, or global theme architecture.
+- No real game process orchestration beyond existing platform-mediated workflows.
+
+## Decisions
+
+### API inventory and removal semantics
+
+- Users: existing `GET/POST /api/v1/users` and `GET/PUT /api/v1/users/{id}` cover list, create, edit, role updates, status updates, and safe removal by deactivation. Hard delete is not exposed; the UI labels removal as `停用` and sends `status=disabled`.
+- Server instances: existing list/create/get/lifecycle/admin APIs are extended with `PUT /api/v1/server-instances/{id}` for metadata edits and `DELETE /api/v1/server-instances/{id}` for safe archive. Archive marks the server `deleted`, rejects running/installing states, hides deleted servers from normal lists, and returns them only with `state=deleted`.
+- Server administrators: `GET /administrators/candidates`, `POST /administrators`, and `DELETE /administrators/{userId}` remain membership APIs; they never delete user accounts.
+- Plugin marketplace: `GET /plugin-marketplace/plugins`, `GET /plugin-marketplace/plugins/{id}`, and `POST /plugin-marketplace/plugins/{id}/state` are the source of list/detail/action state. The page no longer maps `pluginCatalog` into runtime fallback data.
+- AI providers: `GET/POST /ai-providers`, `GET/PUT /ai-providers/{id}`, `POST /ai-providers/{id}/status`, `POST /test`, and `GET /models` cover empty lists, save, enable/disable, metadata test, model refresh, and retirement. Retirement is disable-only (`status=disabled`) and raw key material remains rejected by validators.
+- Config/logs/run/artifacts/audit: management pages continue using platform-mediated DTOs. Config API failure renders an explicit unavailable state instead of local sample config.
+
+Missing backend support identified during implementation was limited to server instance metadata update and archive/list semantics; these were added with DTO, service, validator, repository, route, documentation, and API tests.
+
+Request/response shapes remain bounded to IDs, logical refs, redacted secret refs, and platform-owned metadata. They do not include raw AI keys, raw host paths, run credentials, direct socket details, or unrestricted plugin execution fields.
+
+### Decision 1: Treat demo data as development-only fixtures
+
+Production pages will not silently replace failed API calls with `pluginCatalog`, `userAccess`, `seedProviders`, or `fallbackConfig`. Development fixtures may remain for isolated tests or explicit local-auth fallback paths, but page status must clearly show API unavailable or empty data.
+
+Alternative considered: keep local fallback data for visual continuity. Rejected because it hides missing backend behavior and makes the console appear functional when data was not loaded.
+
+### Decision 2: Add typed API contracts before page work
+
+Any missing update, delete, retire, archive, or detail-refresh behavior will be represented first in `platform_web/api/types.ts`, `platform_web/api/client.ts`, shared contracts, and schemas. Page components will consume those typed contracts rather than defining request or response shapes inline.
+
+Alternative considered: implement form submit handlers directly against ad hoc endpoints. Rejected because the repository requires API clients, DTOs, contracts, and schemas to stay outside page components.
+
+### Decision 3: Use deactivation or archive when hard deletion is unsafe
+
+Delete-like UI must respect domain safety. Users can be disabled or deleted according to platform rules. AI providers can be disabled or retired if deletion would break references. Server instances can be archived or soft-deleted if a running server or existing history prevents hard deletion. The UI must name the action accurately.
+
+Alternative considered: add one generic delete button everywhere. Rejected because operational resources have different safety and audit requirements.
+
+### Decision 4: Make fallback and failure states auditable
+
+Pages that cannot load API data must show an error or empty state with retry and diagnostic context. Development-only fixtures must be visually isolated and must not enable state-changing actions that imply persistence.
+
+Alternative considered: keep current optimistic local writes after failed API calls. Rejected because it can produce false success for management actions.
+
+### Decision 5: Verify UI workflows in browser after implementation
+
+Because this change touches frontend pages and interactions, completion requires automated tests plus a browser walkthrough. The walkthrough must include the edited pages at desktop and narrow widths and must confirm that no raw secrets, host paths, run credentials, or direct socket values are visible.
+
+Alternative considered: rely only on unit tests. Rejected because these workflows depend on visible controls, responsive layout, and operational feedback states.
+
+## Risks / Trade-offs
+
+- [Risk] Backend APIs may not yet expose every edit/delete operation. Mitigation: implement missing platform DTO, service, repository, handler, and tests in the same change before wiring the UI.
+- [Risk] Removing silent fallbacks can make local development feel less populated. Mitigation: keep explicit local debug fixtures behind development-only paths and show clear labels when they are active.
+- [Risk] Delete semantics can vary by resource. Mitigation: define resource-specific action labels and confirmation copy, and prefer disable/archive where hard deletion is unsafe.
+- [Risk] This change spans several pages. Mitigation: implement one resource workflow at a time with focused tests, then finish with a full browser walkthrough and structure check.
+
+## Migration Plan
+
+1. Inventory current platform API coverage for users, server instances, marketplace plugins, AI providers, config, and maintenance data.
+2. Add or extend backend routes and service behavior where required for edit, delete, archive, retire, and detail refresh operations.
+3. Update frontend API types, schemas, and shared contracts before page components.
+4. Replace silent demo fallbacks with explicit empty/error/local-development states.
+5. Implement page-level controls, confirmations, operation feedback, and tests per resource.
+6. Run frontend tests/build, relevant backend tests, browser walkthrough, `scripts/check-structure.sh`, and strict OpenSpec validation.
+
+Rollback is contained before downstream changes depend on these workflows: remove the new routes/client methods, restore previous page interactions, and keep read-only views. After users rely on edit/archive actions, rollback should be handled by a new OpenSpec change with data compatibility notes.
+
+## Open Questions
+
+- Resolved: server instance removal is named archive in the UI and implemented as `DELETE` to a `deleted` state so history remains visible by explicit filter.
+- Resolved: AI provider removal is disable-only retirement for this implementation.
+- Resolved: user removal is deactivation (`disabled`) for this implementation; hard delete is not exposed.
+
+## Verification Evidence
+
+- `go test ./...` from `platform/` passed.
+- `cd platform_web && npm run typecheck && npm run test && npm run build` passed.
+- `scripts/browser-acceptance.sh` passed, covering users, servers, plugin marketplace, AI providers, server detail, plugin controls, desktop/mobile widths, black-mecha/magical-girl themes, and forbidden-fragment scans. Evidence: `.local-debug/browser-acceptance/browser-acceptance-evidence.json`.
+- `scripts/check-structure.sh` passed.
+- `openspec validate complete-platform-web-management-workflows --strict` passed. The CLI emitted PostHog telemetry flush network errors after the success line because external network access is unavailable.
@@ -0,0 +1,29 @@
+## Why
+
+The platform web console now has the required first-party pages, but several management workflows still depend on local demonstration data or stop at create/status-only interactions. Operators need data-backed editing, deletion, and failure-visible empty states so the console can be used as a real game server operations workspace instead of a partially mocked prototype.
+
+## What Changes
+
+- Replace page-visible demo fallbacks for users, AI providers, plugin marketplace data, and server configuration with explicit API-backed loading, empty, and error states.
+- Complete user management with edit, role/profile update, status change, and deletion or deactivation workflows backed by platform APIs.
+- Complete server management with metadata edit actions such as rename, ownership/admin changes, safe delete/archive, and clear lifecycle/history feedback without exposing run internals.
+- Complete plugin marketplace operations with real empty/error states, safe install/enable/disable handling, plugin detail refresh, and no production reliance on `pluginCatalog` fallback data.
+- Complete AI provider management with reliable list-empty behavior, create/update/status/test/model refresh workflows, and deletion or disable-only retirement semantics that preserve secret boundaries.
+- Keep the existing platform_web magical game operations visual direction and role-scoped navigation while making pages dense, operational, and browser-verifiable.
+
+## Capabilities
+
+### New Capabilities
+
+- `platform-web-management-completion`: Data-backed platform_web management workflows for users, servers, plugins, AI providers, and related operational states.
+
+### Modified Capabilities
+
+- None. This change builds on existing workflow specs and adds a frontend completion contract rather than modifying archived requirement files.
+
+## Impact
+
+- Affects `platform_web/` API types/client methods, page contracts, schemas, server/user/plugin/AI provider pages, stores, tests, and browser acceptance coverage.
+- May require `platform/` DTOs, validators, services, repositories, and HTTP routes where current APIs do not support edit/delete/retire operations.
+- May require updates to frontend structure checks if new shared contract/schema directories or rules are introduced.
+- Must not add billing, cloud host sales, agent-provider/cloud-provider workflows, unrelated SaaS marketplace features, raw AI key exposure, raw host path exposure, direct run sockets, or plugin access to platform secrets.
@@ -0,0 +1,109 @@
+## ADDED Requirements
+
+### Requirement: Management pages use API-backed data states
+The platform web management pages SHALL use platform APIs as the source of visible operational data and SHALL render explicit loading, empty, error, or development-fixture states instead of silently substituting production data with local examples.
+
+#### Scenario: API returns an empty list
+- **WHEN** a management page API returns an empty list for users, servers, plugins, AI providers, logs, audit events, or run endpoints
+- **THEN** the page MUST render an empty state that reflects the empty API response and MUST NOT keep previously seeded demonstration rows visible
+
+#### Scenario: API request fails
+- **WHEN** a management page API request fails in normal operation
+- **THEN** the page MUST render an error state with retry affordance or diagnostic context and MUST NOT enable persistence-looking actions against local fallback data
+
+#### Scenario: Development fixture is active
+- **WHEN** an explicit development fixture or local-auth fallback is active
+- **THEN** the page MUST label the data as local development data and MUST disable or clearly reject state-changing actions that cannot be persisted
+
+### Requirement: Management list pages preserve full-width work surfaces
+The platform web management pages SHALL keep list, grid, and table views as full-width work surfaces and SHALL put create, edit, and detail workflows in modal, drawer, or detail-route surfaces instead of permanent side panes or inline split forms.
+
+#### Scenario: Operator opens create, edit, or detail workflow
+- **WHEN** an operator opens create, edit, or detail workflows on users, plugin marketplace, AI providers, servers, or similar management list pages
+- **THEN** the page MUST keep the underlying list, grid, or table full-width and MUST render the workflow in a modal, drawer, or detail route without a permanent right-side form/detail pane
+
+### Requirement: User management supports full account maintenance
+The user management page SHALL allow authorized platform administrators to create users, edit user identity/contact fields, update roles, update status, and remove or deactivate users through platform APIs.
+
+#### Scenario: Administrator edits user fields
+- **WHEN** a platform administrator edits a user's display name, email, phone, QQ, contact note, roles, or status
+- **THEN** the frontend MUST submit a named API request, render success or failure feedback, and update the list from the persisted response
+
+#### Scenario: Administrator removes or deactivates a user
+- **WHEN** a platform administrator confirms a user removal or deactivation action
+- **THEN** the platform MUST enforce the resource safety rule and the frontend MUST render the resulting removed, disabled, or rejected state without pretending a local write succeeded
+
+#### Scenario: Non-admin reaches user management
+- **WHEN** a user without `users.manage` reaches the user management route directly
+- **THEN** the page MUST avoid rendering account maintenance controls and MUST return or explain the authorized workspace state
+
+### Requirement: Server management supports metadata edit and safe removal
+The server management workspace SHALL allow authorized users to create server instances, edit server metadata, manage server administrators, start and stop eligible instances, and archive or delete safe instances through platform-mediated APIs.
+
+#### Scenario: Operator edits server metadata
+- **WHEN** an authorized operator updates a server name, ownership-visible metadata, or other editable server fields
+- **THEN** the frontend MUST submit a typed platform API request and render the persisted server instance response
+
+#### Scenario: Operator archives or deletes a server
+- **WHEN** an authorized operator confirms archive or delete for a server instance
+- **THEN** the platform MUST reject unsafe states such as running instances unless the chosen operation is explicitly allowed, and the frontend MUST render the accepted or rejected result with diagnostic context
+
+#### Scenario: Server detail manages administrators
+- **WHEN** a server owner adds or removes server administrators from the server detail page
+- **THEN** the frontend MUST use platform administrator membership APIs and refresh candidate and assigned member state after the operation
+
+### Requirement: Plugin marketplace avoids production demo fallbacks
+The plugin marketplace SHALL render platform marketplace data and state actions from platform APIs and SHALL NOT rely on `pluginCatalog` fallback data in production behavior.
+
+#### Scenario: Marketplace API is unavailable
+- **WHEN** the marketplace list or detail API request fails
+- **THEN** the marketplace page MUST show an error or explicitly labeled development fixture state and MUST NOT present local catalog rows as persisted marketplace data
+
+#### Scenario: Plugin state action is submitted
+- **WHEN** an operator installs, enables, or disables a plugin
+- **THEN** the frontend MUST call the platform marketplace state API, display the operation result, and update the selected plugin detail from the persisted response
+
+#### Scenario: Plugin detail is refreshed
+- **WHEN** an operator selects or refreshes a plugin detail
+- **THEN** the frontend MUST prefer the platform detail API response and MUST render validation, permission, lifecycle, page, bridge, and AI purpose metadata without exposing secrets or run internals
+
+### Requirement: AI provider management handles empty data and retirement safely
+The AI provider management page SHALL handle empty API lists correctly and SHALL support create, update, enable/disable, test, model refresh, and deletion or retirement semantics without exposing raw AI key material.
+
+#### Scenario: AI provider API returns zero providers
+- **WHEN** the AI provider list API succeeds with zero providers
+- **THEN** the page MUST render an empty state or creation form and MUST NOT keep seed providers visible
+
+#### Scenario: Provider is saved
+- **WHEN** an operator creates or updates an AI provider
+- **THEN** the frontend MUST submit a named API request using secret references only and MUST render the redacted provider response
+
+#### Scenario: Provider is retired or deleted
+- **WHEN** an operator confirms provider deletion or retirement
+- **THEN** the platform MUST enforce reference safety and the frontend MUST remove, disable, or mark the provider according to the persisted response
+
+#### Scenario: Provider action fails
+- **WHEN** provider save, status, test, model refresh, delete, or retire action fails
+- **THEN** the frontend MUST display failure feedback and MUST NOT mutate local state as if the action succeeded
+
+### Requirement: Management completion preserves security boundaries
+The completed management workflows SHALL NOT expose raw AI keys, raw host paths, run credentials, direct socket addresses, or unrestricted plugin execution controls to `platform_web` or plugin pages.
+
+#### Scenario: Page renders operational data
+- **WHEN** any completed management page renders users, servers, plugins, AI providers, logs, audit events, artifacts, jobs, or run endpoints
+- **THEN** the rendered data MUST omit raw AI keys, raw host paths, run credentials, and direct socket details
+
+#### Scenario: Plugin control action is rendered
+- **WHEN** plugin controls or bridge actions are rendered for a server
+- **THEN** the controls MUST be derived from platform-approved plugin metadata and MUST dispatch through platform APIs rather than direct run or host access
+
+### Requirement: Management completion is verified end to end
+The change SHALL include automated tests, structure validation, strict OpenSpec validation, and browser walkthrough evidence for the completed management workflows.
+
+#### Scenario: Verification commands run
+- **WHEN** the implementation is complete
+- **THEN** relevant backend tests, `cd platform_web && npm run typecheck && npm run test && npm run build`, `scripts/check-structure.sh`, and `openspec validate complete-platform-web-management-workflows --strict` MUST pass or have documented blockers
+
+#### Scenario: Browser walkthrough covers edited pages
+- **WHEN** frontend management workflows are claimed complete
+- **THEN** a browser walkthrough MUST verify users, servers, plugin marketplace, AI providers, and related error/empty states at desktop and narrow widths
@@ -0,0 +1,65 @@
+## 1. API and Safety Inventory
+
+- [x] 1.1 Inventory current platform APIs for users, server instances, server administrators, plugin marketplace, AI providers, config, logs, run endpoints, and audit events.
+- [x] 1.2 Decide and document resource-specific removal semantics for users, server instances, and AI providers: delete, disable, archive, or retire.
+- [x] 1.3 Identify missing backend DTOs, validators, repository methods, service methods, and HTTP routes required by the frontend completion workflows.
+- [x] 1.4 Confirm no planned request or response shape includes raw AI keys, raw host paths, run credentials, direct socket details, or unrestricted plugin execution fields.
+
+## 2. Platform API Support
+
+- [x] 2.1 Add or extend user management APIs for editing identity/contact fields, roles, status, and delete/deactivate behavior.
+- [x] 2.2 Add or extend server instance APIs for metadata edits and safe archive/delete behavior while preserving lifecycle validation.
+- [x] 2.3 Add or extend AI provider APIs for empty list correctness and delete/retire behavior with secret-reference-only validation.
+- [x] 2.4 Add backend tests for accepted and rejected edit/delete/archive/retire workflows and stable JSON errors.
+- [x] 2.5 Update platform route/API documentation for newly added management actions.
+
+## 3. Frontend Contracts and Schemas
+
+- [x] 3.1 Add frontend API DTO types and client methods for all new user, server, plugin, and AI provider management actions.
+- [x] 3.2 Add shared frontend contracts for edit forms, removal confirmations, operation result state, and development-fixture state outside page components.
+- [x] 3.3 Add or update frontend schemas for user edit, server metadata edit, server removal, AI provider save, and AI provider retirement requests.
+- [x] 3.4 Remove unused static shell demo constants or isolate them as explicit test/development fixtures.
+
+## 4. User Management Completion
+
+- [x] 4.1 Replace silent `fallbackUsers` display with API-backed loading, empty, error, and explicitly labeled local-development states.
+- [x] 4.2 Add existing-user edit controls for profile/contact fields, roles, and status using typed API requests.
+- [x] 4.3 Add user delete/deactivate confirmation flow with persisted result feedback and rejection diagnostics.
+- [x] 4.4 Add tests for user empty state, edit success, edit failure, status update, and delete/deactivate behavior.
+
+## 5. Server Management Completion
+
+- [x] 5.1 Add server list or detail controls for editable server metadata such as display name and allowed ownership-visible fields.
+- [x] 5.2 Add safe server archive/delete flow with state-aware confirmation and platform rejection feedback.
+- [x] 5.3 Ensure server administrator add/remove flows refresh assigned administrators and candidates after each operation.
+- [x] 5.4 Replace server config fallback behavior with explicit API unavailable state or clearly labeled local-development fixture state.
+- [x] 5.5 Add tests for server metadata edit, archive/delete rejection, administrator refresh, and config unavailable state.
+
+## 6. Plugin Marketplace Completion
+
+- [x] 6.1 Remove production reliance on `pluginCatalog` fallback data from marketplace list and detail rendering.
+- [x] 6.2 Render marketplace API empty and error states with retry and diagnostic context.
+- [x] 6.3 Ensure install, enable, and disable actions update list and detail state only from persisted platform responses.
+- [x] 6.4 Add tests for marketplace API failure, empty list, detail refresh, disabled fixture actions, and state action feedback.
+
+## 7. AI Provider Completion
+
+- [x] 7.1 Fix zero-provider API responses so seed providers are not kept visible after a successful empty list.
+- [x] 7.2 Remove optimistic local success for failed save, status, test, model refresh, and delete/retire actions.
+- [x] 7.3 Add delete or retire action UI with confirmation, persisted response handling, and reference-safety rejection feedback.
+- [x] 7.4 Add tests for empty provider list, create/update failure, status failure, model refresh failure, and delete/retire behavior.
+
+## 8. Verification
+
+- [x] 8.1 Run relevant backend tests from `platform/` and record evidence.
+- [x] 8.2 Run `cd platform_web && npm run typecheck && npm run test && npm run build` and record evidence.
+- [x] 8.3 Run a browser walkthrough covering users, servers, plugin marketplace, AI providers, and empty/error states at desktop and narrow widths.
+- [x] 8.4 Run forbidden-fragment checks for raw AI keys, raw host paths, run credentials, and direct socket details in rendered management pages.
+- [x] 8.5 Run `scripts/check-structure.sh` and record evidence.
+- [x] 8.6 Run `openspec validate complete-platform-web-management-workflows --strict` and record evidence.
+
+## 9. Management Layout Corrections
+
+- [x] 9.1 Replace permanent inline create/edit/detail panes on AI provider, user, and plugin marketplace list pages with modal workflows while preserving full-width list surfaces.
+- [x] 9.2 Document the ban on permanent right-side or inline split management panes in platform_web Markdown guidance.
+- [x] 9.3 Verify AI provider create/edit, user create/edit, and plugin detail workflows in a browser after the modal conversion.