103 lines
9.5 KiB
Markdown
103 lines
9.5 KiB
Markdown
## 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.
|