browser/openspec/changes/add-scum-player-state-patch/specs/scum-player-state-patch/spec.md

ADDED Requirements

Requirement: Version-scoped player state catalog

The system SHALL allow SCUM player state patches only for a declared exact game version and an explicit catalog of skill/attribute fields with numeric ranges.

Scenario: Unknown server version

• WHEN an administrator requests a patch and the current server state reports an unknown game version
• THEN the system SHALL disable the patch request and SHALL not queue a bridge command

Scenario: Out-of-range or unknown field

• WHEN a request contains a field absent from the version catalog or a value outside its range
• THEN the system SHALL reject the request before an audit approval or game-side command is created

Requirement: Authorized and safe patch request

The system SHALL ensure that the game player belongs to the target server, the requester has server access, the expected player-state version matches the current snapshot, and the snapshot declares a verified maintenance/offline safety window before creating a patch record.

Scenario: Stale player state

• WHEN a patch carries an expected state version different from the current player-state snapshot
• THEN the system SHALL reject it as a conflict and SHALL not dispatch a patch command

Scenario: Online server without a safe window

• WHEN a state snapshot indicates the target player is online or maintenance is not verified
• THEN the system SHALL reject the request with a readable safety status

Requirement: Explicit administrator approval and immutable audit

The system SHALL persist each accepted request with field-level before/after values, reason, requester, approval state, approver, and execution status. Only a platform administrator with server access MAY approve dispatch.

Scenario: Non-admin approval

• WHEN a server-authorized non-platform-admin attempts to approve a pending patch
• THEN the system SHALL deny approval and SHALL leave the patch pending

Requirement: Typed game-state patch execution and confirmation

The system SHALL dispatch only the declared game-state.patch command through the game-client bridge. A successful record SHALL require a typed per-field result and a read-after-write confirmation whose values equal the requested values and whose state version advances.

Scenario: Companion reports a failure

• WHEN the companion returns a failed patch command result
• THEN the patch record SHALL be terminal execution-failed, preserve the readable result summary, and SHALL not be reported as applied

Scenario: Result is missing or unconfirmable

• WHEN the command expires, is cancelled, returns malformed state, or cannot confirm the requested values
• THEN the record SHALL retain an explicit execution-unknown or confirmation-failed status and SHALL not be reported as applied

Requirement: Readable SCUM console workflow

The SCUM player console SHALL show player detail context and provide a Chinese patch form only for supported safe states. It SHALL show a textual field diff, reason, approval status, executor result, and confirmation status without relying only on color.

Scenario: Pending approval

• WHEN a patch is awaiting approval
• THEN the console SHALL label it as awaiting platform-administrator approval and display the old/new values and requester reason