Add SCUM operations workflow OpenSpec

2026-08-10 18:24:51 +08:00
parent ff34a20906
commit ba2b1a9d9f
8 changed files with 496 additions and 0 deletions
@@ -0,0 +1,68 @@
+## ADDED Requirements
+
+### Requirement: Sequential workflow definitions
+The system SHALL define SCUM workflows as ordered typed steps with dependencies, inputs, permissions, safety gates, execution transport, confirmation, retry policy, and blocking states.
+
+#### Scenario: Workflow starts with dependencies
+- **WHEN** a workflow instance is created for a server instance
+- **THEN** platform evaluates dependency steps and dispatches only the first runnable step whose prerequisites are satisfied
+
+#### Scenario: Step depends on projection freshness
+- **WHEN** a step requires fresh player, squad, vehicle, flag, or position projections
+- **THEN** platform runs or waits for the required observation workflow before dispatching the dependent write or UI-facing step
+
+### Requirement: One-by-one execution per server
+The system SHALL execute SCUM workflow steps one by one per server instance when steps mutate game state, while allowing safe read observation steps to run with bounded concurrency.
+
+#### Scenario: Two write workflows are queued
+- **WHEN** two player mutation or gift-delivery workflows target the same server instance
+- **THEN** platform dispatches the next state-changing step only after the prior state-changing step reaches confirmed, failed, blocked, cancelled, or unknown terminal state
+
+#### Scenario: Read observation workflows are queued
+- **WHEN** multiple read observation steps target players, squads, vehicles, and flags
+- **THEN** platform may batch or parallelize them within declared row, timeout, and concurrency limits without violating run channel priority
+
+### Requirement: Integrated SCUM workflow library
+The system SHALL provide first-party workflow templates for common SCUM operations that combine real data reads, typed writes, and product-state updates.
+
+#### Scenario: Player profile refresh workflow
+- **WHEN** an operator refreshes a player profile
+- **THEN** platform runs login evidence sync, player SCUM.db lookup, economy lookup, squad membership lookup, current position lookup, and projection update as one tracked workflow
+
+#### Scenario: Player correction workflow
+- **WHEN** an operator approves a player correction
+- **THEN** platform runs safety check, before-value read, RCON or DB mutation, confirmation read, projection update, and audit completion in order
+
+#### Scenario: Gift delivery workflow
+- **WHEN** a gift grant becomes eligible by schedule, player type, achievement, or manual approval
+- **THEN** platform runs eligibility check, inventory/reward operation, player notification, confirmation read/result, and grant-state transition in order
+
+#### Scenario: Territory risk workflow
+- **WHEN** an operator opens squad or flag governance
+- **THEN** platform can run squad roster refresh, flag ownership refresh, member-position overlay, stale-owner detection, and risk-signal projection without direct browser database access
+
+#### Scenario: Vehicle inventory workflow
+- **WHEN** an operator requests vehicle inventory/map refresh
+- **THEN** platform runs vehicle query, coordinate projection, owner/nearby squad enrichment where available, stale vehicle marking, and map overlay update
+
+#### Scenario: AI configuration workflow
+- **WHEN** an operator asks AI to configure or tune the SCUM plugin
+- **THEN** platform gathers allowed plugin config fields, generates a reviewable diff, validates the diff, dispatches approved writes through existing config approval, and reports completion
+
+### Requirement: Workflow status and audit evidence
+The system SHALL expose workflow status, current step, blocker reason, retry count, confirmation status, stale data references, and audit references through safe product APIs.
+
+#### Scenario: Workflow blocks on missing run
+- **WHEN** a workflow step requires bound run execution but no current run session can claim the capability
+- **THEN** platform marks the workflow blocked with a safe reason and does not leak machine paths, tokens, sockets, or protected payload text
+
+#### Scenario: Workflow completes
+- **WHEN** all required steps reach terminal success and confirmations pass
+- **THEN** platform marks the workflow confirmed, links audit evidence, and updates the relevant player, squad, vehicle, flag, gift, or configuration projection
+
+### Requirement: Retry without duplicating game effects
+The system SHALL apply idempotency keys, fencing tokens, and confirmation reads so retries do not duplicate gifts, duplicate currency updates, or overwrite newer player state.
+
+#### Scenario: Run loses connection after command dispatch
+- **WHEN** run disconnects after a state-changing command may have executed
+- **THEN** platform performs a confirmation read before deciding whether to retry, mark unknown, or mark confirmed