tim/SlipItIn
1
0
Fork 0
Code Pull Requests 1 Actions 1 Packages Releases Wiki Activity

Update der Dokumentation

Browse Source
This commit is contained in:
Tim Krampitz
2026-08-08 12:50:15 +02:00
parent bbc6ad6080
commit 118a62a804
15 changed files with 460 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
openwiki/domain/game-mechanics.md
View File

@@ -1,21 +1,27 @@
---
type: Domain Model
title: Game Domain & State Models
description: Detailed domain model and state lifecycles for SlipItIn games, rounds, phrase decks, players, and challenges.
tags: [domain, models, state-machine, entity-framework, privacy]
description: Detailed domain model and state lifecycles for SlipItIn games, rounds, phrase decks, players, challenges, and client offline action queue.
tags: [domain, models, state-machine, entity-framework, privacy, offline-queue]
openwiki:
roles: [domain]
change_kinds: [public-api, lifecycle]
source_paths: [SlipItIn.Shared/Models/Game.cs, SlipItIn.Shared/Models/Player.cs, SlipItIn/Models/QueuedGameAction.cs, SlipItIn.Shared/DTOs/GameStateDto.cs]
symbols: [Game, Player, PlayerCard, SlipChallenge, QueuedGameAction, GameStateDto, PlayerHandDto]
validation_commands: ["dotnet build SlipItIn.Shared/SlipItIn.Shared.csproj"]
---
# Game Domain & State Models
This page describes the core domain entities, relational schema, state machines, and data transfer objects (DTOs) that form the foundation of the SlipItIn game engine.
This page describes the core domain entities, relational schema, state machines, offline action queue models, and data transfer objects (DTOs) that form the foundation of the SlipItIn game engine.
The domain model [is secured by data privacy models defined in](/openwiki/architecture/overview.md) the system architecture, [defines state lifecycles executed by](/openwiki/workflows/slip-and-challenge.md) real-time game workflows, and [maps domain classes in C# project files indexed in](/openwiki/source-map.md) the source map (`SlipItIn.Shared/Models/` and `SlipItIn.Shared/DTOs/`).
The domain model [is secured by data privacy models defined in](/openwiki/architecture/overview.md) the system architecture, [defines state lifecycles executed by](/openwiki/workflows/slip-and-challenge.md) real-time game workflows, and [maps domain classes in C# project files indexed in](/openwiki/source-map.md) the source map (`SlipItIn.Shared/Models/`, `SlipItIn.Shared/DTOs/`, and `SlipItIn/Models/`).
---
## 1. Entity Relationship Diagram (ERD)
The database schema is managed via Entity Framework Core (`SlipItInDbContext`) targeting PostgreSQL.
The backend database schema is managed via Entity Framework Core (`SlipItInDbContext`) targeting PostgreSQL.
```mermaid
erDiagram
@@ -70,19 +76,20 @@ erDiagram
ChallengeStatus Status
}
User ||--o{ Game : "hosts"
User ||--o{ Player : "participates as"
User ||--o{ Phrase : "creates"
Game ||--o{ Player : "contains"
Game ||--o{ GameRound : "has"
Player ||--o{ PlayerCard : "holds"
Phrase ||--o{ PlayerCard : "used in"
GameRound ||--o{ PlayerCard : "active in"
GameRound ||--o{ SlipChallenge : "contains"
Player ||--o{ SlipChallenge : "challenges"
Player ||--o{ SlipChallenge : "target of"
PlayerCard ||--o{ SlipChallenge : "targeted by"
User ||--o{ Game : hosts
User ||--o{ Player : participates_as
User ||--o{ Phrase : creates
Game ||--o{ Player : contains
Game ||--o{ GameRound : has
Player ||--o{ PlayerCard : holds
Phrase ||--o{ PlayerCard : used_in
GameRound ||--o{ PlayerCard : active_in
GameRound ||--o{ SlipChallenge : contains
Player ||--o{ SlipChallenge : challenges
Player ||--o{ SlipChallenge : target_of
PlayerCard ||--o{ SlipChallenge : targeted_by
```
*Entity Relationship Diagram showing relational database schema for users, games, players, phrases, cards, rounds, and challenges.*
---
@@ -125,7 +132,19 @@ Represents an accusation made by one player against another player's submitted s
---
## 3. Enumerations & State Lifecycles
## 3. Client State & Offline Action Queue Models (`SlipItIn/Models`)
### `QueuedGameAction`
Represents a game action (such as `SubmitSlip` or `ChallengeSlip`) initiated on the client while offline (`!SignalRService.IsConnected`).
* **Properties**:
* `Method`: Target SignalR hub method name (e.g. `"SubmitSlip"`, `"ChallengeSlip"`).
* `ArgumentsJson`: JSON serialized array of method arguments.
* `CreatedAtUtc`: Timestamp recording when the action was taken.
* **Lifecycle**: Enqueued into `Preferences` via `GameStateService.EnqueueActionAsync()`, replayed sequentially upon reconnection via `GameStateService.FlushQueuedActionsAsync()`, and removed from storage.
---
## 4. Enumerations & State Lifecycles
### Game Status (`GameStatus`)
```mermaid
@@ -136,6 +155,7 @@ stateDiagram-v2
Lobby --> Cancelled: Host cancels
InProgress --> Cancelled: Session abort
```
*State diagram illustrating lifecycle transitions of a game session from lobby creation to completion or cancellation.*
* **`Lobby`**: Waiting for players to join and set ready status.
* **`InProgress`**: Active gameplay with dealt cards and active rounds.
@@ -151,6 +171,7 @@ stateDiagram-v2
Resolving --> Active: Challenge resolved
Active --> Completed: Timer expires / All phrases used
```
*State diagram illustrating round lifecycles from card dealing to challenge resolution.*
### Challenge Status (`ChallengeStatus`)
* **`Pending`**: Accusation registered, awaiting response from the accused player.
@@ -159,13 +180,33 @@ stateDiagram-v2
---
## 4. Data Transfer Objects (DTOs) & Data Privacy
## 5. Data Transfer Objects (DTOs) & Data Privacy
To enforce security and data privacy ([Architecture Overview](/openwiki/architecture/overview.md)), the backend exposes decoupled DTOs in `SlipItIn.Shared/DTOs`:
| DTO | Visibility | Purpose & Content |
|---|---|---|
| `LoginRequestDto` | Direct REST | Credentials for authentication: `Email`, `Password`. |
| `RegisterRequestDto` | Direct REST | Account creation details: `Username`, `Email`, `Password`. |
| `AuthResponseDto` | Direct REST | JWT Access Token, Expiration, Username, Email. |
| `GameStateDto` | Broadcast (Group) | Public lobby/game status: `GameId`, `LobbyCode`, `Status`, `CurrentRound`, `RoundTimeRemaining`, `Players` (`PlayerInfoDto` array containing `PlayerId`, `Username`, `Score`, `IsReady`, and `CardCount`). **No card text.** |
| `PlayerHandDto` | Unicast (Client) | Private hand data sent strictly to the card owner: `PlayerId`, `Cards` (`PlayerCardDto` array containing `CardId`, `PhraseId`, `Text`, `IsUsed`). |
| `SlipChallengeDto` | Unicast / Group | Challenge notification: `ChallengeId`, `ChallengingPlayerId`, `TargetPlayerId`, `TargetCardId`, `Status`, `CreatedAt`. |
---
## 6. Guidance for Future Agents & Developers
- **When to Consult**: Consult this page when adding domain attributes, extending DTOs, adding new game state statuses, or modifying offline action serialization.
- **Invariants**:
- `PlayerCard.IsUsed` transitions from `false` to `true` upon `SubmitSlip` and cannot be reverted without server intervention.
- `QueuedGameAction.ArgumentsJson` must store arguments in the exact order and type expected by `GameHub` methods.
- **Primary Source Files**:
- `SlipItIn.Shared/Models/Game.cs`
- `SlipItIn.Shared/Models/PlayerCard.cs`
- `SlipItIn.Shared/DTOs/GameStateDto.cs`
- `SlipItIn/Models/QueuedGameAction.cs`
- **Minimal Validation Command**:
```bash
dotnet build SlipItIn.Shared/SlipItIn.Shared.csproj
```