feat: redesign server deployment workflow

2026-07-24 19:22:35 +08:00
parent 220ef91a8e
commit ab943536b0
10 changed files with 362 additions and 243 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-24
@@ -0,0 +1,68 @@
+## Context
+
+The existing server-create dialog serializes target selection, deployment choice, paths, plugin game fields, runtime binding fields, and custom commands into one form. A server's deployment editor exists only in the detail overview beside many unrelated operational panels. The API already distinguishes drafts, protected deployment inputs, deployment modes, and explicit dispatch; the design problem is the management-console workflow, not a missing host-side capability.
+
+The console must preserve its black-mecha / magical-girl shared visual system and must not return protected paths, commands, credentials, or direct Run access to the browser.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the normal operator flow target-first, mode-second, configuration-third, then review.
+- Provide a single reusable workflow for new definitions and safe edits to drafts or stopped servers.
+- Make draft creation explicit and keep deployment impact, capability issues, and write-only values understandable.
+- Keep changes compatible with existing create, update-deployment, and deploy endpoints.
+
+**Non-Goals:**
+
+- Changing Run's protected deployment protocol, adding SSH/host browsing, returning protected values, or allowing deployment-definition mutation for an active server.
+- Adding new game plugins, changing plugin manifest semantics, or replacing the console visual language.
+- Implementing a generic shell editor or a path browser in Platform.
+
+## Decisions
+
+### 1. One controlled workflow owns both creation and deployment edits
+
+Introduce a `ServerDeploymentWorkflow` component with `create` and `edit` modes. The page that opens it owns only the lifecycle request: create calls the existing workflow-create endpoint, while edit saves the existing deployment definition and lets the operator explicitly deploy afterward. This removes duplicate form policy without introducing an API abstraction that hides lifecycle actions.
+
+The alternative—incrementally rearranging the two current forms—would keep divergent defaults, labels, and field visibility.
+
+### 2. Workflow steps follow operator decisions, not storage fields
+
+The component has four steps: target (plugin plus Run or explicit draft), deployment method, configuration, and review. Forward navigation validates only fields required by the selected mode. Back navigation preserves typed values. The final review is the only submit point.
+
+`guided-install` shows plugin game inputs and a primary “server directory”; `existing-server` shows the existing server directory; `custom-command` adds launch data. `workingDirectory` is an advanced custom-command input labelled as an execution directory and defaults logically to `serverRoot` when omitted. This preserves the current protocol distinction without demanding it from normal users.
+
+### 3. Draft is a deliberate outcome
+
+The target step presents compatible nodes and a separate “save as draft” choice with explanatory copy. It never represents draft creation as an empty selection accidentally left in a select input. A draft review changes the final action to save only; it does not offer a deceptive deployment promise.
+
+### 4. Editing is a discoverable operation with safe prefill
+
+Server cards and the detail header expose `编辑部署`. Detail opening uses the same workflow. The edit form receives safe deployment view values (mode, configured flags, create inputs, selected endpoint) and starts protected input fields blank with replacement copy. It is disabled for active servers, matching the existing server-side rule.
+
+### 5. Review uses only safe, operator-facing summaries
+
+The review names the plugin, chosen node/draft outcome, method, game configuration, and configured/replaced protected inputs. It never renders protected values. Plugin profile keys remain internal implementation values; where a choice is necessary, the UI calls it a runtime preset and formats a readable label.
+
+### 6. Styling is shared and compact
+
+Use `ManagementDialog`, `console-*`, command, form, and theme token primitives, adding only narrowly scoped workflow layout classes in `theme/base.css`. The step indicator is functional state, not page-local decoration; no fixed particles, opaque SaaS cards, or independent color system are introduced.
+
+## Risks / Trade-offs
+
+- [An edit lacks the original protected values] → Show configured state and make blank fields preserve the stored values; copy states that re-entry replaces the value.
+- [A user mistakes a stopped-server edit for immediate deployment] → Separate “save changes” from the explicit later “deploy” operation and show the consequence in review.
+- [Node compatibility information is incomplete before Run preflight] → Show only known endpoint availability/capability; retain Run preflight as authoritative.
+- [A shared component expands scope] → Limit it to deployment-definition inputs and leave server metadata, game config editor, and runtime operations in their existing sections.
+
+## Migration Plan
+
+1. Ship the shared frontend workflow behind the existing API contracts.
+2. Preserve all existing definition fields and treat missing working directories as inherited from the server directory for review copy only.
+3. Route card/detail edit actions into the workflow and remove the old duplicate create/deployment forms.
+4. Roll back by restoring the previous page components; persisted deployment definitions and endpoints remain unchanged.
+
+## Open Questions
+
+- None for the initial workflow: endpoint capability is already authoritatively checked at dispatch and protected input values intentionally cannot be prefilled.
@@ -0,0 +1,30 @@
+## Why
+
+The server console technically supports deployment editing, but it is buried in a crowded overview and separates naming, node binding, deployment mode, and protected execution inputs into unrelated surfaces. Creation presents all fields at once, making ordinary game-server setup feel like an internal control-plane form and leaving operators uncertain about whether an existing server can be changed safely.
+
+Operators need one understandable deployment workflow: choose a game and target node, choose the intended deployment path, configure only the fields relevant to that path, review the impact, and later reopen the same workflow to change a stopped server.
+
+## What Changes
+
+- Replace the one-page server create form with a staged create workflow: target, deployment mode, relevant configuration, and review/submit.
+- Add prominent “edit deployment” entry points from a server card and server-detail header; reuse the staged workflow for stopped servers and drafts.
+- Make “save as draft” an explicit secondary path instead of an unexplained empty-node option.
+- Simplify directory input: use a single primary server directory and expose the execution working directory only in advanced custom-command settings, defaulting it to the server directory when omitted.
+- Replace plugin-internal labels such as “运行配置” and raw profile keys with operator-oriented copy, while preserving the existing protected-input and Run capability checks.
+- Show a safe deployment summary and impact confirmation before create, save, or deploy.
+
+## Capabilities
+
+### New Capabilities
+
+- `server-deployment-console-workflow`: A shared staged console workflow for creating and editing server deployment definitions, including explicit draft handling, mode-specific fields, safe review, and discoverable entry points.
+
+### Modified Capabilities
+
+- None.
+
+## Impact
+
+- `platform_web/`: server list actions, server detail header/overview, shared deployment-workflow component and contracts, API adapters, theme-consistent styles, and focused frontend tests.
+- `platform/`: no relaxation of protected deployment inputs, Run-only execution, capability validation, or active-server mutation protection; a small safe response projection may be added only if necessary for workflow prefill.
+- Existing draft, deployment-update, and deploy endpoints remain the backing lifecycle operations; this change does not add platform-side host access, SSH, or a second executor.
@@ -0,0 +1,44 @@
+## ADDED Requirements
+
+### Requirement: Server creation follows a staged deployment workflow
+The management console SHALL collect a server definition in the order target, deployment method, mode-relevant configuration, and review. The console MUST preserve entered values while the operator moves between workflow steps and MUST prevent submission until the selected mode's required values are present.
+
+#### Scenario: Create a guided server
+- **WHEN** an operator selects a game plugin and compatible Run node, chooses guided installation, completes the plugin configuration, and confirms review
+- **THEN** the console creates the server through the existing lifecycle workflow using the selected target and deployment definition
+
+### Requirement: Draft creation is explicit
+The management console SHALL present saving without a Run node as an explicit draft choice and MUST explain that no deployment job will be dispatched.
+
+#### Scenario: Save an unbound definition
+- **WHEN** an operator selects the draft choice during target selection and confirms the review
+- **THEN** the console saves a draft and labels the final action as saving rather than deploying
+
+### Requirement: Deployment configuration is mode-specific
+The management console SHALL show only the deployment inputs needed by the selected deployment method. It MUST use server directory as the primary directory input and MUST expose execution working directory only in advanced custom-command configuration, with copy that it inherits the server directory when omitted.
+
+#### Scenario: Configure an existing server
+- **WHEN** an operator chooses existing-server deployment
+- **THEN** the console requests the existing server directory and does not render installation or custom command inputs
+
+#### Scenario: Configure a custom launcher
+- **WHEN** an operator chooses custom-command deployment
+- **THEN** the console renders the required startup command and optional advanced execution directory, shell, install, stop, and status inputs
+
+### Requirement: Existing server deployment editing is discoverable and safe
+The management console SHALL expose an edit-deployment action from a server card and server-detail header. It MUST reuse the staged deployment workflow, use only safe deployment projections for prefill, and MUST prevent opening an editable deployment workflow for active servers.
+
+#### Scenario: Edit a stopped server
+- **WHEN** an operator invokes edit deployment for a stopped server
+- **THEN** the console opens the staged workflow with its selected node, mode, create inputs, and protected-input configured state without revealing protected values
+
+#### Scenario: Attempt to edit a running server
+- **WHEN** an operator views a running server
+- **THEN** the console identifies that deployment settings require stopping the server before editing and does not submit a deployment mutation
+
+### Requirement: Review preserves deployment-input protection
+The workflow review SHALL identify the chosen plugin, endpoint or draft status, deployment method, game configuration, and configured protected input state. It MUST NOT render stored or newly entered full host paths, command text, credentials, or runtime-binding secrets.
+
+#### Scenario: Review custom deployment
+- **WHEN** an operator reaches review with a custom-command deployment
+- **THEN** the review reports that server directory, startup command, and optional execution fields are configured or replaced without exposing their values
@@ -0,0 +1,16 @@
+## 1. Shared deployment workflow
+
+- [x] 1.1 Add a reusable staged deployment workflow contract and component that owns target, mode, configuration, and safe review state.
+- [x] 1.2 Move the server-create request mapping into the workflow and implement explicit draft copy and mode-specific configuration visibility.
+- [x] 1.3 Implement safe edit prefill and deployment-update submission, including protected-field configured/replacement summaries.
+
+## 2. Server management integration
+
+- [x] 2.1 Replace the Servers page create dialog with the staged workflow and expose an edit-deployment action from each eligible server card.
+- [x] 2.2 Add a detail-header edit-deployment action and replace the overview's inline deployment mutation form with a concise safe summary and workflow launch.
+
+## 3. Theme-consistent interaction and verification
+
+- [x] 3.1 Add compact shared-theme workflow layout styles and remove obsolete one-page deployment form presentation.
+- [x] 3.2 Add focused contracts/page tests for step order, explicit drafts, field visibility, safe review, and edit availability.
+- [x] 3.3 Run focused frontend checks, `scripts/check-structure.sh`, and `openspec validate redesign-server-deployment-workflow --strict`; mark tasks complete only after evidence exists.