feat(scum): add versioned gift grants

2026-07-28 16:40:35 +08:00
parent 4527175a6f
commit e2d0bc0595
26 changed files with 1224 additions and 14 deletions
@@ -0,0 +1,52 @@
+## ADDED Requirements
+
+### Requirement: Version-fenced gift catalog and revisions
+The system SHALL let authorized SCUM server operators create and edit gift catalog drafts whose items reference only the Platform-verified item catalog for the server's exact game version. Publishing SHALL create an immutable, monotonically versioned revision, and the system MUST reject unknown versions, stale or invalid items, duplicate items, and out-of-range quantities.
+
+#### Scenario: Publish validated draft
+- **WHEN** an authorized operator publishes a draft containing only verified items for the current SCUM version
+- **THEN** the system creates an immutable revision with its frozen item list and exposes it for preview and granting
+
+#### Scenario: Reject invalid item
+- **WHEN** a draft references an item absent from the verified item catalog for the selected SCUM version
+- **THEN** the system rejects the change without creating a publishable revision
+
+### Requirement: Frozen and idempotent targeted grant
+The system SHALL create a durable grant from a selected published revision and local game-player record, freezing the revision contents and target identity before approval. A repeated request with the same scoped idempotency key MUST return the original grant and MUST NOT create another delivery command.
+
+#### Scenario: Later catalog edit does not alter a grant
+- **WHEN** an operator creates a grant and subsequently edits or publishes the gift catalog
+- **THEN** the existing grant retains its original revision, item snapshot, and target identity snapshot
+
+#### Scenario: Duplicate grant request
+- **WHEN** a requester submits the same target/revision grant request again with the same idempotency key
+- **THEN** the system returns the original grant and queues no duplicate delivery
+
+### Requirement: Approved bounded game delivery
+The system SHALL require a platform administrator with target-server access to approve a pending grant and SHALL dispatch only the declared typed `reward.deliver` bridge command assembled from the frozen grant. Approval MUST reject offline targets, invalidated catalog/revision data, and unauthorized callers.
+
+#### Scenario: Offline player is not dispatched
+- **WHEN** a platform administrator attempts to approve a grant for a player not present in the current online-player snapshot
+- **THEN** approval is rejected and no delivery command is queued
+
+#### Scenario: Authorized approval queues delivery
+- **WHEN** a platform administrator approves a valid grant for an online local game player
+- **THEN** the system records the approver and queues one typed delivery command using the grant identity as its idempotency key
+
+### Requirement: Delivery and notification lifecycle safety
+The system SHALL expose queued, delivered, notification_failed, failed, and unknown grant outcomes with readable audit evidence. A succeeded delivery followed by notification failure MUST remain visible as `notification_failed`; unknown delivery outcomes and notification failures MUST NOT automatically retry or redeliver items.
+
+#### Scenario: Notification failure after delivered item
+- **WHEN** the delivery command succeeds and the targeted-notification command fails
+- **THEN** the grant is retained as `notification_failed` with the successful delivery evidence and failed notification evidence
+
+#### Scenario: Unknown delivery is terminal
+- **WHEN** a queued delivery command expires, is cancelled, or has no conclusive result
+- **THEN** the grant becomes `unknown` and the system queues neither a retry nor another item delivery
+
+### Requirement: Safe console and API projections
+The system SHALL provide Chinese shared-console workflows for draft/version editing, item preview, local player selection, grant confirmation, approval, and history. Browser requests and responses MUST NOT contain raw game item codes, generator commands, arbitrary RCON text, run credentials, host paths, or direct game connection data.
+
+#### Scenario: Safe grant submission
+- **WHEN** an operator confirms a gift grant in the console
+- **THEN** the browser submits only bounded catalog/revision, player-record, notice, and idempotency references and renders the returned readable lifecycle record