browser/openspec/changes/complete-platform-web-management-workflows/specs/platform-web-management-completion/spec.md

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