skara-brae-common/docs/openup/requirements/use-case-model.md

Skara Brae — Use-Case Specifications

Skara Brae — OpenUP Requirements · version 2.0 (2026-10-05, restructured to the OpenUP use-case-specification template; scenario content unchanged from version 1.0). Scope: the existing implemented system (server MVP as of main, formerly wi-2-architecture-cleanup @ 899fde8). Every flow below is derived from actual handler code (crates/sb-api/src/routes/mod.rs) — status codes cited are the implemented behavior and are normative. The EA model (docs/openup/model/skara-brae.eapx) carries the same scenarios with per-step actors; markdown and model must agree (drift rule).

Use Case Overview

ID	Use Case	Actors	Includes / Extends
UC-01	Register Account	Guest	—
UC-02	Authenticate	Guest	—
UC-03	Manage Characters	Player, Administrator	—
UC-04	Browse Game Catalogue	Player	—
UC-05	Train Stat	Player	includes Regenerate Resources
UC-06	Manage Equipment	Player	—
UC-07	Trade at Shop	Player	—
UC-08	Run Adventure	Player	includes Regenerate Resources, Resolve Combat
UC-09	Heal at Temple	Player	—
UC-10	Practice Bard Song	Player	—
UC-11	Study Magic	Player	—
UC-12	Level Up at Review Board	Player	—

Figure 1: Use case overview (rendered from the EA model via scripts/openup/export-diagram-images.ps1).

Shared sub-flow Regenerate Resources: the system recomputes time-based regeneration at specific call sites only — list characters, view character, run adventure, and train stat (routes/mod.rs:264–266, 331, 442, 642). Energy +1 per 180 s, nerve +1 per 300 s, HP +5% of max per 300 s (only if alive and injured), capped at maxima; last_regen advances to now. It is not applied by equip/unequip, gym view, shop, heal, songs, spells, or level-up.

---

UC-01 Register Account

Brief Description

Open registration: a guest submits name and password and receives a JWT with the player role. No precondition.

Actor Brief Descriptions

Actor	Type	Description
Guest	Primary	Unauthenticated caller; only register/login are open.

Preconditions and Context

Precondition: none.

Basic Flow of Events

1. Guest submits name (3–32 chars) and password (≥ 6 chars).
2. System verifies the name is unused → 409 CONFLICT if taken.
3. System hashes the password (argon2), assigns the player role and the next id, persists the user.
4. System issues a JWT (HS256, player role) and returns {token, user_id, name, role}.

Alternative and Exception Flows

Invalid input (Alternate)

1. System rejects a name outside 3–32 chars or a password under 6 chars with 400.

Hashing or token failure (Exception)

1. System fails during password hashing or JWT creation → 500; no user is persisted.

Post-conditions

• User persisted with player role; JWT issued and returned.

Special Requirements

• Passwords hashed with argon2, verification constant-time (NFR-16).
• JWT HS256, 24 h expiry (NFR-17); no secrets in code (NFR-18).

UC-02 Authenticate

Brief Description

Login with name and password; issues a JWT carrying the user's real role.

Actor Brief Descriptions

Actor	Type	Description
Guest	Primary	Unauthenticated caller; only register/login are open.

Preconditions and Context

Precondition: none.

Basic Flow of Events

1. Guest submits name and password.
2. System finds the user (401 if unknown) and verifies the password hash (401 on mismatch).
3. System issues a JWT carrying the user's real role (admin/player) and returns {token, user_id, name, role}.

Alternative and Exception Flows

Credentials rejected (Alternate)

1. Unknown name or wrong password → 401 UNAUTHORIZED.

Token creation failure (Exception)

1. JWT creation fails → 500.

Post-conditions

• JWT issued with the user's real role; no persistent state change.

Special Requirements

• The middleware guards all UC-03…12 routes with this token (NFR-17).

UC-03 Manage Characters

Brief Description

Create, list and view characters. Admin may act for any user (read-only view).

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).
Administrator	Supporting	Player with elevated rights (role = admin); may view any user's and any character's resources read-only.

Preconditions and Context

Precondition (create): target user exists. Admin may act for any user.

Basic Flow of Events (create)

1. Player submits character name, race, class for their user id.
2. System validates the target user exists (404) and the trimmed name is 1–32 chars (400).
3. System rolls stats (d6+5 base 6–16 per stat ± race modifiers), computes max HP/energy/nerve from class, grants starting gold (50) and level-1 class spells to casters.
4. System assigns the next character id, stores and persists the character; returns it fully.

Alternative and Exception Flows

List / view (Alternate)

1. Player lists their characters (Admin: any user's); the system applies Regenerate Resources to each returned character and returns them.
2. Player views one character; the system applies regen then returns it.

Access denied (Alternate)

1. Foreign user/character without admin role → 403 FORBIDDEN.

Not found (Alternate)

1. User or character not found → 404.

Invalid name (Alternate)

1. Trimmed name outside 1–32 chars → 400.

Post-conditions

• (create) Character persisted with rolled stats, class resources and starting gold.
• (view/list) Regeneration applied to returned characters.

Special Requirements

• Stat rolls use the injected rng — deterministic under seed (NFR-05, WI-1).

UC-04 Browse Game Catalogue

Brief Description

Races, classes, items (type/quality/slot filters), enemies, adventure zones from static game data.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: authenticated.

Basic Flow of Events

1. Player requests the catalogue: races, classes, items (optional type/quality/slot filters), enemies, or adventure zones.
2. System returns static game data loaded from skara-brae-common JSON (class info is enriched with is_caster).

Alternative and Exception Flows

Unknown item (Alternate)

1. Single item by unknown id → 404.

Empty filter result (Alternate)

1. Filters may return an empty list (not an error).

Post-conditions

• None (read-only).

Special Requirements

• Catalogue is compiled-in and parsed once behind LazyLock; lock-free reads (NFR-04).
• Content source is skara-brae-common JSON, never duplicated in code (NFR-13).

UC-05 Train Stat

Brief Description

Train a stat at a training ground; costs 1 energy + gold. Includes Regenerate Resources.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character exists and caller may act on it.

Basic Flow of Events

1. Player selects a training ground (strength / dexterity / constitution / intelligence / luck) and submits the stat name.
2. System applies Regenerate Resources.
3. System checks energy ≥ 1 and gold ≥ training cost (cost grows ~1.3× per 10 stat points).
4. System deducts 1 energy and the gold cost, increments the stat; constitution training recomputes max HP (current HP clamped).
5. System persists and returns {success, message, character}.

Alternative and Exception Flows

Foreign character (Alternate)

1. Character owned by another user without admin role → 403.

Not found (Alternate)

1. Character not found → 404.

Not enough energy (Alternate)

1. Energy < 1 → 422.

Not enough gold (Alternate)

1. Gold below training cost → 422.

Unknown stat (Alternate)

1. Unknown stat name → 400.

Post-conditions

• Stat incremented; energy −1 and gold −cost deducted; max HP recomputed on constitution training; character persisted.

Special Requirements

• Rule failures flow through DomainError → central status mapping (CON-04).

UC-06 Manage Equipment

Brief Description

Equip from inventory / unequip back to inventory.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character exists and caller may act on it.

Basic Flow of Events (equip)

1. Player submits an item id from their inventory.
2. System moves the item from inventory to its slot; a previously equipped item in that slot returns to inventory.
3. System persists and returns the updated character.

Alternative and Exception Flows

Unequip (Alternate)

1. Player submits a slot name; the system moves the equipped item back to inventory.

Foreign character (Alternate)

1. Foreign character without admin role → 403.

Not found (Alternate)

1. Character or item not found → 404.

Item not in inventory (Alternate)

1. Equip target not in inventory → 400.

Empty slot (Alternate)

1. Unequip on a slot with nothing equipped → 400.

Post-conditions

• Item moved between inventory and equipment slot; character persisted.

Special Requirements

• Rule failures flow through DomainError → central status mapping (CON-04).

UC-07 Trade at Shop

Brief Description

Buy from (always-stocked + rotating) shop stock or sell inventory items.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character exists and caller may act on it.

Basic Flow of Events (buy)

1. Player views the shop: always-stocked items plus rotating stock (with quantities) alongside their inventory.
2. Player submits buy + item id.
3. System checks gold ≥ price (422), and for non-always-in-stock items decrements the limited stock (410 GONE if 0).
4. System deducts gold, adds the item to inventory, persists character and stock; returns {success, message, gold}.

Alternative and Exception Flows

Sell (Alternate)

1. Player submits sell + item id; system removes the first matching inventory item, pays half the item value, increments shop stock for non-permanent items.

Bad request (Alternate)

1. Unknown action, or sell of an item not owned → 400.

Not found (Alternate)

1. Item not found → 404.

Insufficient gold (Alternate)

1. Gold below price → 422.

Stock exhausted (Alternate)

1. Limited stock at 0 → 410.

Post-conditions

• Buy: gold deducted, item in inventory, stock decremented; Sell: item removed, half value paid, stock incremented; persisted.

Special Requirements

• Shop business logic is handler-side recorded debt (Architecture Notebook D1, Q3).

UC-08 Run Adventure

Brief Description

Zone adventure with weighted enemy pick and turn-based combat. Includes Regenerate Resources, Resolve Combat. Exception: encounter references an unknown enemy → 500 (post WI-2; previously a panic). WI-2 design driver (sb_core::adventure extraction).

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character exists and caller may act on it.

Basic Flow of Events

1. Player requests an adventure for a zone (default skara_brae_streets).
2. System validates the zone (404) and applies Regenerate Resources.
3. System refuses incapacitated characters (HP ≤ 0 → 400) and characters with nerve below the zone cost (422); otherwise deducts the nerve cost.
4. System draws one enemy from the zone's weighted encounter table.
5. System resolves turn-based combat: open-ended d100 attack rolls, OB vs DB, RoleMaster crit tables with level-gap damage caps, active bard song effects, active spell damage/heal per round.
6. On player victory: XP and gold per the enemy definition, character HP set to the last round's defender HP, and loot dropped per-item chance rolls (only items existing in the catalogue).
7. On defeat: character HP set to 0; no rewards.
8. Spell-point upkeep is charged whenever a spell was active, win or lose.
9. System persists the character and returns {zone, enemy, combat_log, loot} (loot = item display names).

Alternative and Exception Flows

Foreign character (Alternate)

1. Foreign character without admin role → 403.

Not found (Alternate)

1. Character or zone not found → 404.

Incapacitated (Alternate)

1. HP ≤ 0 → 400.

Insufficient nerve (Alternate)

1. Nerve below zone cost → 422.

Unknown encounter enemy (Exception)

1. Encounter references an enemy id missing from the catalogue (data error) → 500 (post WI-2; previously a panic).

Post-conditions

• Victory: rewards granted, loot added, HP set to last defender HP; defeat: HP 0, no rewards; spell upkeep charged if a spell was active; character persisted.

Special Requirements

• Enemy draw and combat rolls use the injected rng (NFR-05, CON-03).
• Referential integrity violations surface as DomainError::UnknownEncounterEnemy → 500 (NFR-07).
• Crit damage caps by level gap; open-ended d100 (combat canon, docs/game/).

UC-09 Heal at Temple

Brief Description

Full or partial healing, cost = amount healed, minimum 1 gold.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character exists, is injured, and caller may act on it.

Basic Flow of Events

1. Player requests healing, optionally partial.
2. System computes missing HP; full heals all, partial heals half (rounded up); cost = amount healed, minimum 1 gold.
3. System checks gold (422), deducts it, restores HP, persists; returns {hp, max_hp, gold, healed: true}.

Alternative and Exception Flows

Foreign character (Alternate)

1. Foreign character without admin role → 403.

Not found (Alternate)

1. Character not found → 404.

Already at full HP (Alternate)

1. No missing HP → 400.

Insufficient gold (Alternate)

1. Gold below heal cost → 422.

Post-conditions

• HP restored, gold deducted, character persisted.

Special Requirements

• Healing logic is handler-side recorded debt (Architecture Notebook D1, Q3).

UC-10 Practice Bard Song

Brief Description

Set or clear the active bard song (Bard only, level-gated).

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character class is Bard.

Basic Flow of Events

1. Player views available songs (level-gated, with combat effect descriptions) and the active song.
2. Player submits a song id; system validates level requirement (422) and sets it active; returns {success, message, active_song}.

Alternative and Exception Flows

Clear (Alternate)

1. Submitting no song id clears the active song.

Non-Bard (Alternate)

1. Character class is not Bard → 403.

Unknown song (Alternate)

1. Unknown song id → 404.

Level too low (Alternate)

1. Character level below the song requirement → 422.

Foreign character / not found (Alternate)

1. Foreign character → 403; character not found → 404.

Post-conditions

• Active song set or cleared; character persisted.

Special Requirements

• Song effects apply in UC-08 combat (step 5).

UC-11 Study Magic

Brief Description

View spellbook, learn spell levels (1–7, gold cost), activate/clear the active spell. Caster classes only; spell level = (character level / 3) + 1, uncapped by code.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character belongs to a caster class (Mage→magician, Wizard, Conjurer, Sorcerer). Spell level = (character level / 3) + 1 — uncapped by code (level 100 → spell level 34); learn requests are validated to 1–7.

Basic Flow of Events (view spellbook)

1. Player requests their spellbook: caster class, current spell level, spell points, spells up to the achievable level (each marked known), and the learn-cost table for levels 2–7.

Alternative and Exception Flows

Learn spell level (Alternate)

1. Player submits a spell level (1–7).
2. System validates caster class (403), level range (400), level not above the character's current spell level (422), gold ≥ learn cost (422), and that new spells exist (400).
3. System deducts gold, adds all unknown spell ids of that level, recomputes and refills max spell points; returns {learned_count, spell_points, max_spell_points, gold}.

Activate / clear active spell (Alternate)

1. Player submits a spell id (or empty to clear).
2. System validates the spell is known (403), exists (404), and spell points suffice (422); deducts the spell's points and sets it active; returns {active_spell, spell_points}.

Post-conditions

• (learn) spells of the level known, gold deducted, max spell points recomputed and refilled; (activate) active spell set, spell points deducted; persisted.

Special Requirements

• Active spell deals damage/heals per round and charges upkeep in UC-08 combat (steps 5, 8).
• Parts of spell logic are handler-side recorded debt (Architecture Notebook D1, Q3).

UC-12 Level Up at Review Board

Brief Description

Manual level-up: XP threshold + gold cost (500 per next level), full resource restore on level-up.

Actor Brief Descriptions

Actor	Type	Description
Player	Primary	Authenticated user owning one or more characters (JWT role player).

Preconditions and Context

Precondition: character exists and caller may act on it.

Basic Flow of Events

1. Player requests a level-up.
2. System validates: below max level 100, XP ≥ 18·100·(level)² for the next level (i.e. xp_for_level(next)), gold ≥ 500·next level.
3. System deducts the gold cost, increments the level, recomputes and fully restores HP/energy/nerve and max spell points; persists; returns {success, message, character}.

Alternative and Exception Flows

Level-up rejected (Alternate)

1. Already at max level, not enough XP, or not enough gold → 422.

Foreign character (Alternate)

1. Foreign character without admin role → 403.

Not found (Alternate)

1. Character not found → 404.

Post-conditions

• Level +1, gold deducted, all resources fully restored and maxima recomputed; character persisted.

Special Requirements

• Level-up rule failures flow through DomainError → central status mapping (CON-04).

---

Traceability Notes

• UC-08 is the design driver for WI-2's service extraction (sb_core::adventure); its status mapping feeds DomainError (see analysis-design/design-wi-2-architecture-cleanup.md §4.1–4.2).
• Catalogue data backing UC-04 lives in skara-brae-common/data/ (items, enemies, zones, spells, crit tables).
• Analysis realizations for all twelve use cases: analysis-design/uc-realization-mapping.md §2 + EA model; design sequences: analysis-design/sequences/.
• Requirement traceability: supplementary-specifications.md coverage matrix.