Jan-Peter von Hunnius
6e5d3fb45a
All checks were successful
build / build-test (push) Successful in 44s
- analysis-design/architecture-notebook.md: Architecture Notebook work product in the keyfob docx template structure (10 sections), grounded in mapping / design note / supplementary specs; embeds the component model and all 12 realization figures - scripts/openup/export-diagram-images.ps1: read-only EA COM renderer (EA-15 findings: image API on ProjectInterface, OpenDiagram before export or blank stub, type 0 = PNG); renders reflect manual layouts - renders: requirements/use-case-overview.png, analysis-design/ uc-01..12-realization.png + component-architecture.png; embedded as figures in use-case-model.md and uc-realization-mapping.md - BUILD-CHECKLIST 6.4 documents the exporter
174 lines
11 KiB
Markdown
174 lines
11 KiB
Markdown
# Skara Brae — Use Case Model
|
||
|
||
Version 1.0 (WI-2, 2026-10-03) · OpenUP artifact: `requirements/use-case-model.md`
|
||
Scope: the **existing implemented system** (server MVP as of `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.
|
||
|
||
## Actors
|
||
|
||
| Actor | Description |
|
||
|---|---|
|
||
| **Player** | Authenticated user owning one or more characters (JWT role `player`). |
|
||
| **Administrator** | Player with elevated rights (`role = admin`); may view any user's and any character's resources read-only. |
|
||
| **Guest** | Unauthenticated caller; only register/login are open. |
|
||
|
||
## Use Case Overview
|
||
|
||
| ID | Use Case | Primary Actor | Includes / Extends |
|
||
|---|---|---|---|
|
||
| UC-01 | Register Account | Guest | — |
|
||
| UC-02 | Authenticate | Guest | — |
|
||
| UC-03 | Manage Characters | Player (Admin read) | — |
|
||
| 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, `docs/openup/model/skara-brae.eapx`, 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
|
||
|
||
**Precondition:** none. **Main success scenario:**
|
||
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}`.
|
||
|
||
**Alternate flows:** name length invalid → 400; password too short → 400; name taken → 409; hashing/token failure → 500.
|
||
|
||
## UC-02 Authenticate
|
||
|
||
**Main success scenario:**
|
||
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}`.
|
||
|
||
**Alternate flows:** unknown name or wrong password → 401 UNAUTHORIZED; token creation failure → 500.
|
||
|
||
## UC-03 Manage Characters
|
||
|
||
**Main success scenario (create):**
|
||
1. Player submits character name, race, class for their user id (Admin may act for any user).
|
||
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.
|
||
|
||
**Scenario (list/view):** Player lists their characters (Admin: any user's); the system applies Regenerate Resources to each returned character and returns them. Viewing one character applies regen then returns it.
|
||
|
||
**Alternate flows:** foreign user/character without admin role → 403 FORBIDDEN; user/character not found → 404; invalid name → 400.
|
||
|
||
## UC-04 Browse Game Catalogue
|
||
|
||
**Main success scenario:**
|
||
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`).
|
||
|
||
**Alternate flows:** single item by unknown id → 404; filters may return an empty list (not an error).
|
||
|
||
## UC-05 Train Stat
|
||
|
||
**Precondition:** character exists and caller may act on it. **Main success scenario:**
|
||
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}`.
|
||
|
||
**Alternate flows:** foreign character → 403; character not found → 404; not enough energy → 422; not enough gold → 422; unknown stat name → 400.
|
||
|
||
## UC-06 Manage Equipment
|
||
|
||
**Main success scenario (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.
|
||
|
||
**Scenario (unequip):** Player submits a slot name; the system moves the equipped item back to inventory.
|
||
|
||
**Alternate flows:** foreign character → 403; character/item not found → 404; item not in inventory → 400; nothing equipped in slot → 400.
|
||
|
||
## UC-07 Trade at Shop
|
||
|
||
**Main success scenario (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}`.
|
||
|
||
**Scenario (sell):** Player submits `sell` + item id; system removes the first matching inventory item, pays half the item value, increments shop stock for non-permanent items.
|
||
|
||
**Alternate flows:** unknown action or item not owned (sell) → 400; item not found → 404; insufficient gold → 422; stock exhausted → 410.
|
||
|
||
## UC-08 Run Adventure
|
||
|
||
**Precondition:** character exists and caller may act on it. **Main success scenario:**
|
||
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).
|
||
|
||
**Alternate flows:** foreign character → 403; character/zone not found → 404; incapacitated → 400; insufficient nerve → 422. **Exception:** encounter references an unknown enemy (data error) → 500 (post WI-2; previously a panic).
|
||
|
||
## UC-09 Heal at Temple
|
||
|
||
**Main success scenario:**
|
||
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}`.
|
||
|
||
**Alternate flows:** foreign character → 403; not found → 404; already at full HP → 400; insufficient gold → 422.
|
||
|
||
## UC-10 Practice Bard Song
|
||
|
||
**Precondition:** character class is Bard. **Main success scenario:**
|
||
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}`.
|
||
|
||
**Scenario (clear):** submitting no song id clears the active song. **Alternate flows:** non-Bard → 403; unknown song → 404; level too low → 422; foreign character → 403; not found → 404.
|
||
|
||
## UC-11 Study Magic
|
||
|
||
**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, and the practical ceiling is emergent from the data (spells are defined only through level 7, so higher computed levels surface no new spells).
|
||
|
||
**Scenario (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.
|
||
|
||
**Scenario (learn spell level):**
|
||
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}`.
|
||
|
||
**Scenario (activate/clear active spell):**
|
||
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}`.
|
||
|
||
## UC-12 Level Up at Review Board
|
||
|
||
**Main success scenario:**
|
||
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}`.
|
||
|
||
**Alternate flows (all 422):** already at max level; not enough XP; not enough gold. Foreign character → 403; not found → 404.
|
||
|
||
---
|
||
|
||
## 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).
|