Add SCUM file management workbench

2026-08-04 11:33:34 +08:00
parent 2921edb401
commit f028a343d7
36 changed files with 1384 additions and 158 deletions
@@ -14,16 +14,19 @@ The SCUM plugin already declares runtime config mappings and log sources, while
 **Non-Goals:**

 - Arbitrary filesystem browsing, path entry, terminals, FTP/rsync controls, raw secrets, or host/socket exposure.
- Raw text as the default configuration editor, write access for unknown fields, or a new run-side protocol.
+- Raw text as the default configuration editor, direct write access for unknown fields, or a new run-side protocol.
 - Changing global server-list behavior or non-SCUM plugin pages.

 ## Decisions

 1. Add `fileWorkspace` to the plugin manifest/runtime projection. It contains safe logical directories/files and modeled fields, rather than host paths or unbounded schemas. This makes a page contract auditable and keeps ownership with the plugin.
 2. Give every modeled field an owning logical file key, Chinese operational metadata, and constrained control details. The frontend uses only these fields to compose proposed INI content; unmapped lines remain visible as read-only field records.
-3. Reuse `GET /config`, config diff preview, and config approval for the declared primary config file. Log-file selection maps declared logical files to existing Platform log streams; no new direct file-read API is introduced.
+3. Reuse declared file read/write dispatch for logical file keys. A completed `files.read` job may be projected through a Platform-owned declared-file snapshot endpoint, which accepts only a declared logical file key, returns no host path or job payload, and redacts secret-like assignment values before returning content. Modeled edits and optional raw config edits require a visible diff preview before the Platform queues a declared `files.write` job.
 4. Move SCUM from `operations` to `files-config`; the route resolver redirects old `overview`, `config`, `logs`, and `operations` keys only for `game.scum`. Other plugins keep their declared page keys unchanged.
 5. Build page content from existing shared console form/list/diff classes. No page-owned surface system or global decoration is added.
+6. Treat the SCUM workbench as one selected logical file at a time. The left pane contains only declared directories and files. The right pane presents either modeled fields or an optional raw mode for an editable configuration file, and a read-only log view for a log file. Selection changes must not trigger unbounded polling or path-based requests.
+7. Render the plugin bundle in embedded mode when it is mounted under a server-detail section. The generic plugin page frame and host-context diagnostics remain available for direct plugin routes, but must not be nested inside the file-management tab.
+8. Keep Companion player, reward, state, vehicle, and trajectory controls out of this page. Those remain available through their separately scoped plugin-control experiences and must not obscure the file workflow.

 ## Risks / Trade-offs

@@ -31,6 +34,8 @@ The SCUM plugin already declares runtime config mappings and log sources, while
 - [Existing installations still link old route keys] → normalize those keys in the common resolver before page lookup.
 - [A declared log stream is absent] → show an explicit unavailable state and never fall back to a filesystem path.
 - [INI parsing has formatting limits] → patch only declared simple key/value fields and rely on Platform preview before approval.
+- [A raw file has not completed an authorized read] → show an explicit pending or empty state rather than an invented template or stale file content.
+- [A declared file contains a secret-like assignment] → redact its value in the snapshot while retaining the surrounding file structure for operational review.

 ## Migration Plan

@@ -6,8 +6,10 @@ SCUM operators currently reach separate overview, configuration, and semantic-lo

 - Replace the SCUM overview-first experience with a unified `文件与配置` workbench whose default scope is the plugin-declared configuration directory.
 - Add plugin-declared logical file directories/files and a modeled configuration-field catalog, including Chinese labels, help, control metadata, constraints, defaults, restart impact, and owning file.
- Reuse Platform-mediated file requests and the existing configuration diff-preview/approval/write flow so modeled changes are previewed before dispatch.
+- Reuse Platform-mediated file requests and the existing configuration diff-preview/approval/write flow so modeled changes are previewed before dispatch; expose completed declared-file reads through a bounded, redacted Platform snapshot rather than through host paths or general job payloads.
 - Expose logs as declared log files inside the same workbench, with separate safe log-file scope; retain unknown configuration fields as read-only information.
+- Replace the static, stacked SCUM panels with a single selection-based file workbench: directory/file navigation on one side and the selected file's modeled configuration, optional raw config mode, or read-only log content on the other.
+- Embed the workbench inside the server detail section without a second plugin-page header or unrelated Companion feature panels.
 - Safely migrate legacy SCUM overview/config/log routes to the new workbench.

 ## Capabilities
@@ -22,4 +24,4 @@ SCUM operators currently reach separate overview, configuration, and semantic-lo
 ## Impact

 - Affects the SCUM plugin manifest/declarations, Platform plugin validation and safe file/config DTO handling, and SCUM frontend contracts/routes/components.
- Reuses `files.request`, existing server configuration diff/approval/write APIs, and the SCUM runtime profile without expanding filesystem or remote-access authority.
+- Reuses `files.request`, existing server configuration diff/approval/write APIs, and the SCUM runtime profile; adds a Platform-owned read-result projection without expanding filesystem or remote-access authority.
@@ -29,6 +29,50 @@ The SCUM workbench SHALL present plugin-declared log files as a log-file scope a
 - **WHEN** an operator selects a declared SCUM log file
 - **THEN** the page MUST query only its declared Platform log stream and show readable file content without host-path disclosure

+### Requirement: Raw file content is a bounded declared-file snapshot
+Platform SHALL expose raw configuration or log text only from the latest completed `files.read` result for the same server and a plugin-declared logical file key.
+
+#### Scenario: Declared file result is ready
+- **WHEN** an authorized operator requests the raw view of a declared file after its read job completes
+- **THEN** Platform MUST return only that file's bounded content, logical key, version, checksum, and read state
+- **AND THEN** the response MUST NOT contain a host path, a generic job execution payload, or another file's content
+
+#### Scenario: Declared file is not read yet
+- **WHEN** no successful declared-file read is available for the selected file
+- **THEN** Platform MUST return an explicit pending or not-read state without inventing file contents
+
+#### Scenario: Raw file contains a secret-like assignment
+- **WHEN** a completed declared-file result includes a secret-like `key=value` assignment
+- **THEN** Platform MUST redact the assignment value before returning the raw snapshot
+
+### Requirement: SCUM workbench has one active file surface
+The SCUM workbench SHALL keep declared directory/file navigation separate from the selected file content, rather than stacking every declared file and every unrelated SCUM feature on one page.
+
+#### Scenario: Operator selects a declared configuration file
+- **WHEN** an operator selects `ServerSettings.ini` or another declared configuration file
+- **THEN** the workbench MUST show only that file's metadata and supported modes in the content pane
+- **AND THEN** modeled fields MUST be limited to fields owned by that selected file
+
+#### Scenario: Operator switches a selected configuration file to raw mode
+- **WHEN** an operator activates the raw configuration mode for a selected declared configuration file
+- **THEN** the workbench MUST show only the most recent Platform-mediated file result or an explicit not-yet-read state
+- **AND THEN** an editable declared configuration file MAY expose a raw editor only after a completed read snapshot is available
+- **AND THEN** raw-mode changes MUST require a visible diff preview before dispatching a declared logical `files.write` request
+- **AND THEN** it MUST NOT expose a host path, arbitrary file selector, or unrestricted text editor
+
+#### Scenario: Operator selects a declared log file
+- **WHEN** an operator selects a declared log file
+- **THEN** the workbench MUST replace the configuration controls with that log file's declared read surface
+- **AND THEN** the log raw view MUST stay read-only and support switching between UTF-8 and UTF-16 LE display
+
+### Requirement: Embedded SCUM file management avoids duplicate page chrome
+When the SCUM workbench is rendered inside a server detail section, the frontend SHALL render it without a second plugin page frame, host-context panel, or unrelated Companion feature panels.
+
+#### Scenario: Server detail opens SCUM file management
+- **WHEN** an operator opens the SCUM `文件管理` section in server detail
+- **THEN** the first workbench surface MUST be the declared directory/file navigation and selected file content
+- **AND THEN** the page MUST NOT render a nested `PLUGIN PAGE` title or `平台托管上下文` panel
+
 ### Requirement: Legacy SCUM pages migrate safely
 The frontend SHALL migrate legacy SCUM overview, config, logs, and operations page keys to the `files-config` page while leaving non-SCUM routing unchanged.

@@ -3,14 +3,16 @@
 - [x] 1.1 Add safe logical file-directory/file and modeled-field contracts to plugin manifests, Platform domain/DTO projections, copying, and validation.
 - [x] 1.2 Declare SCUM configuration/log files and bounded Chinese configuration field metadata, then remove legacy SCUM overview page declarations.
 - [x] 1.3 Add focused Platform validation/projection tests for safe declaration and field ownership behavior.
+- [x] 1.4 Add a bounded redacted Platform projection for completed declared-file read results.

 ## 2. SCUM file and configuration workbench

 - [x] 2.1 Add frontend declaration contracts and resolver for the SCUM `files-config` default workbench and legacy route migration.
- [x] 2.2 Build the shared-theme file list, modeled configuration form, read-only unknown-field list, preview diff, and approval experience.
+- [x] 2.2 Build the shared-theme selection-based file list, selected-file modeled configuration form, raw config mode, unknown-field list, preview diff, and declared write dispatch experience.
 - [x] 2.3 Add declared log-file scope and Platform log stream content reading without path exposure.
+- [x] 2.4 Render the SCUM workbench embedded in server detail and keep unrelated Companion feature panels out of the file-management tab.

 ## 3. Verification

- [x] 3.1 Add/update focused backend, plugin, route, contract, and component tests.
- [x] 3.2 Run strict OpenSpec validation, relevant backend/plugin/frontend checks, and scripts/check-structure.sh.
+- [x] 3.1 Add/update focused backend, plugin, route, contract, and component tests for selection state, raw mode, and embedded rendering.
+- [x] 3.2 Run strict OpenSpec validation, relevant backend/plugin/frontend checks, browser verification, and scripts/check-structure.sh.