96 lines
6.8 KiB
Markdown
96 lines
6.8 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Server-scoped gift package CRUD
|
|
The system SHALL provide effective-user-authorized create, read, update, enable/disable, and delete operations for gift packages and typed items scoped to one server instance and compatible plugin/game version.
|
|
|
|
#### Scenario: User has gift read access only
|
|
- **WHEN** the current session has `server.game-client.read` but lacks `server.game-client.maintenance`
|
|
- **THEN** package data and delivery history remain readable while create/edit/enable/delete controls are unavailable and direct mutation requests are forbidden
|
|
|
|
#### Scenario: Operator creates a valid package
|
|
- **WHEN** an operator with effective `server.game-client.maintenance` submits a name, classification, eligibility/limit rules, and bounded quantities of plugin-catalogued item keys
|
|
- **THEN** Platform stores the package and items for the target server without storing raw RCON, shell, SQL, or arbitrary command strings
|
|
|
|
#### Scenario: Package item is invalid
|
|
- **WHEN** a package contains an unknown or incompatible item key, duplicate item, out-of-range quantity, or game-version mismatch
|
|
- **THEN** Platform rejects the change and preserves the previous package
|
|
|
|
#### Scenario: Package is deleted
|
|
- **WHEN** an authorized operator confirms deletion of a package not protected by an active delivery
|
|
- **THEN** Platform removes or retires the package without deleting immutable completed delivery facts
|
|
|
|
### Requirement: Plugin-owned immutable gift catalog and transport
|
|
Gift item aliases, compatibility rules, quantities, and delivery transport declarations SHALL come only from versioned digest-referenced assets in the plugin package and, where executable, the generated Run package.
|
|
|
|
#### Scenario: Catalog or transport digest changed
|
|
- **WHEN** a package or frozen delivery references a catalog/transport version or digest that no longer matches the active compatible plugin package
|
|
- **THEN** Platform rejects creation or dispatch and SHALL NOT translate the item into an arbitrary command or newer unreviewed alias
|
|
|
|
### Requirement: Validated gift eligibility and limits
|
|
The system SHALL evaluate package eligibility and atomically reserve database-backed per-player, per-server, and configured period limits in the server's declared timezone before a delivery can dispatch.
|
|
|
|
#### Scenario: Player belongs to another server
|
|
- **WHEN** a caller attempts to deliver a package to a player record outside the package's server instance
|
|
- **THEN** Platform rejects the request before creating a delivery or Run job
|
|
|
|
#### Scenario: Period limit is reached
|
|
- **WHEN** a player already has the allowed number of reserved, in-progress, partial, unknown, or delivered grants in the active daily/weekly or declared period boundary
|
|
- **THEN** Platform rejects another delivery without relying on an in-memory count
|
|
|
|
#### Scenario: Concurrent eligibility requests occur
|
|
- **WHEN** two workers request the same limited package for the same player and period concurrently
|
|
- **THEN** a server-scoped uniqueness/idempotency constraint allows at most one request to reserve the remaining entitlement
|
|
|
|
#### Scenario: Delivery conclusively did not execute
|
|
- **WHEN** Run returns a conclusive failure proving that no gift effect occurred
|
|
- **THEN** Platform may release the reserved period entitlement transactionally; partial or unknown outcomes SHALL continue to hold it until reconciled
|
|
|
|
### Requirement: Frozen and idempotent gift delivery
|
|
The system SHALL freeze the target player, package/item definitions, plugin/game version, and delivery parameters before dispatch and SHALL use a stable server-scoped delivery ID and idempotency key.
|
|
|
|
#### Scenario: Package changes after delivery request
|
|
- **WHEN** an operator edits or disables a package after a delivery has been created
|
|
- **THEN** the existing delivery retains its frozen target/items/version and the edit does not mutate an in-flight or completed delivery
|
|
|
|
#### Scenario: Same idempotency key is submitted again
|
|
- **WHEN** the same scoped delivery request is repeated or submitted concurrently
|
|
- **THEN** Platform returns the original delivery and queues no duplicate effect
|
|
|
|
#### Scenario: Run receives a delivery
|
|
- **WHEN** a user with current effective `server.game-client.command` confirms an eligible frozen delivery
|
|
- **THEN** Run receives only the plugin-declared typed item aliases/quantities and stable delivery identity, not arbitrary browser commands
|
|
|
|
### Requirement: Conclusive delivery outcomes
|
|
The system SHALL record a gift as delivered only after conclusive Run execution evidence, and ambiguous or partial outcomes SHALL not trigger automatic whole-package redelivery.
|
|
|
|
#### Scenario: Job is queued or accepted
|
|
- **WHEN** Run has only claimed, acknowledged, or begun the delivery job
|
|
- **THEN** Platform records the delivery as in progress and SHALL NOT create a successful claim/receipt
|
|
|
|
#### Scenario: Delivery succeeds conclusively
|
|
- **WHEN** Run returns a schema-valid success receipt for every required item under the delivery idempotency key
|
|
- **THEN** Platform records the delivery as delivered exactly once
|
|
|
|
#### Scenario: Connection is lost after possible execution
|
|
- **WHEN** delivery may have executed but the result is missing, timed out, cancelled, or cannot be confirmed
|
|
- **THEN** Platform records an unknown outcome, performs confirmation before any explicit retry, and never automatically queues the entire delivery again
|
|
|
|
#### Scenario: Multi-item delivery is partial
|
|
- **WHEN** the transport cannot guarantee atomic delivery and only some item receipts are conclusive
|
|
- **THEN** Platform records per-item receipts and a partial/unknown package outcome and SHALL NOT label the whole package delivered or blindly redeliver confirmed items
|
|
|
|
#### Scenario: Notification fails after delivery
|
|
- **WHEN** all items are confirmed delivered but a post-delivery notification fails
|
|
- **THEN** Platform preserves the delivered fact, records the notification failure separately, and SHALL NOT redeliver the package
|
|
|
|
### Requirement: Gift management surface and history
|
|
The gift page SHALL provide statistics, a searchable/filterable paginated package table, package create/edit/detail/delete controls, a real player selector, a reviewed send dialog, and server-scoped delivery history without Workflow terminology.
|
|
|
|
#### Scenario: Operator opens gift management
|
|
- **WHEN** local gift data is available
|
|
- **THEN** the page shows package totals/enabled counts/delivery statistics, package contents and limits, and compact row actions without a hard-coded `starter-pack`, fixed player cards, or fixed notification text
|
|
|
|
#### Scenario: Operator reviews delivery result
|
|
- **WHEN** a delivery is in progress, delivered, failed, unknown, partial, or has a notification failure
|
|
- **THEN** the page shows the ordinary gift-delivery result and safe reason without exposing a Workflow instance, Workflow step, raw command, or audit-initiation action
|