docs(openspec): define SCUM plugin ownership migration

2026-07-28 17:35:32 +08:00
parent 5b15bd50cb
commit d24074134a
6 changed files with 216 additions and 0 deletions
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Companion dispatches only declared typed SCUM operations
+The SCUM Companion SHALL run a bounded authenticated command-dispatch loop and SHALL execute only command types declared by the installed SCUM plugin, validated against their payload schema, server binding, permission/approval result, and compatible SCUM capability/version. It SHALL return an idempotent typed result for every claimed command.
+
+#### Scenario: Supported gift delivery command
+- **WHEN** the Companion claims a valid, unexpired `reward.deliver` command for a server version with a registered delivery handler
+- **THEN** it executes only that handler and completes the command with a typed delivered, failed, notification-failed, or unknown result
+
+#### Scenario: Unsupported or malformed command
+- **WHEN** the Companion claims a command whose type, schema, capability, or version is not supported
+- **THEN** it does not invoke SCUM, RCON, a database, OCR, or desktop automation and completes the command with an explicit unsupported or validation failure result
+
+### Requirement: Companion emits validated semantic SCUM events
+The SCUM Companion SHALL collect only declared allowed sources and upload contiguous semantic event batches through the platform's durable log channel. It SHALL validate required event fields before upload and SHALL not emit raw IP addresses, network fingerprints, host paths, credentials, database rows, screenshots, or raw RCON command text.
+
+#### Scenario: Valid login event
+- **WHEN** a supported SCUM source produces a successful-login record containing the declared player identity and timestamp fields
+- **THEN** the Companion uploads a validated `scum.login` semantic event and the plugin can create or update the local game-player profile
+
+#### Scenario: Unknown source format
+- **WHEN** a log or extension source does not match a supported parser version or lacks required fields
+- **THEN** the Companion records a bounded diagnostic and does not fabricate a semantic login, position, vehicle, or security event
+
+### Requirement: Map event collection remains controlled
+The SCUM Companion SHALL emit `player.position`, `vehicle.position`, `player.vehicle.enter`, and `player.vehicle.leave` only from a verified legitimate server-side source declared by the plugin. The plugin SHALL apply its declared coordinate transform, sampling precision, and retention policy before exposing trajectory data.
+
+#### Scenario: Position source is unavailable
+- **WHEN** no supported server-side source can provide a validated player or vehicle position
+- **THEN** the trajectory page reports collection unavailable and does not use OCR, screenshots, keyboard/mouse injection, client-screen reading, or inferred synthetic tracks
+
+#### Scenario: Cross-server isolation
+- **WHEN** events are emitted for two bound SCUM servers
+- **THEN** the Companion tags each batch with its bound server identity and no trajectory, player, or vehicle data from one server is returned for the other
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: SCUM feature ownership is plugin-local
+The system SHALL place SCUM-specific configuration semantics, player/gift/map/state-patch behavior, schemas, validators, Companion handlers, and feature UI modules in the SCUM plugin package. The platform SHALL expose only generic authorization, isolation, audit, storage, queue, retention, and plugin-host primitives and SHALL NOT add new SCUM-named domain services, API handlers, or frontend panels.
+
+#### Scenario: A new SCUM capability is added
+- **WHEN** a SCUM-specific configuration field, event type, command, or view is introduced
+- **THEN** its implementation and tests are added to the SCUM plugin package while the platform change, if any, is reusable by non-SCUM plugins
+
+#### Scenario: Existing platform SCUM code is migrated
+- **WHEN** an existing SCUM service or panel is replaced by its plugin equivalent
+- **THEN** the platform retains only a generic primitive and no hard-coded `game.scum` branch or SCUM component import remains in the plugin host
+
+### Requirement: Plugin-owned pages mount in the platform host
+The SCUM plugin SHALL declare versioned page-module entries and their required permissions/capabilities. The platform web host SHALL mount the declared module inside the existing authenticated themed shell and SHALL pass only server-scoped, permission-filtered host context.
+
+#### Scenario: Authorized administrator opens a SCUM page
+- **WHEN** an administrator with the declared permission opens a SCUM plugin route for an assigned server
+- **THEN** the host loads the SCUM-declared page module with that server-scoped context and does not use a platform-owned SCUM page implementation
+
+#### Scenario: Page module is unavailable or incompatible
+- **WHEN** the declared SCUM page bundle fails integrity/version/capability validation
+- **THEN** the host shows an unavailable-page state and does not fall back to a hard-coded SCUM panel
+
+### Requirement: Feature availability requires a plugin implementation
+The system SHALL expose a SCUM feature as actionable only when the installed plugin declares the feature and its Companion reports a compatible handler or event producer for the bound server version. Transitional platform records MAY be displayed as migrated read-only history but SHALL NOT imply executable capability.
+
+#### Scenario: Unsupported state patch adapter
+- **WHEN** the bound SCUM version has no verified `game-state.patch` handler
+- **THEN** the plugin disables the edit control and reports that the version is unsupported without queuing a generic command
+
+#### Scenario: Historical records during migration
+- **WHEN** records created by the transitional platform implementation exist for a bound server
+- **THEN** the plugin can display them with migration provenance while new writes use the plugin-owned feature path