Merge branch 'main' into 'chore/95-write-document-for-software-quality'

2026-04-12 19:27:42 +02:00
parent 761d4b1cae d7eb9701c9
commit 1952f720de
27 changed files with 1132 additions and 179 deletions
@@ -82,6 +82,7 @@ This document describes the protocol for client-server communication in our appl
    - [Required pre-execution checks](#required-pre-execution-checks)
    - [Request Parameters](#request-parameters)
    - [Success Response](#success-response)
+  - [START_GAME command](#start_game-command)
  - [GET_LOBBY_STATUS command](#get_lobby_status-command)
    - [Required pre-execution checks](#required-pre-execution-checks)
    - [Request Parameters](#request-parameters)
@@ -547,8 +548,64 @@ END
 ```
 -ERR
  CODE=LOBBY_NOT_FOUND
-  MESSAGE=Lobby not found
+  MSG=Lobby not found
 END
+
+## START_GAME command
+
+The `START_GAME` command requests the server to start a new game in the specified lobby. The
+server requires an explicit numeric `ID` parameter identifying the target lobby.
+
+### Required pre-execution checks
+- [`UserLoggedInCheck`](#userloggedincheck)
+
+### Request Parameters
+| Parameter Name | Type | Optional | Description |
+| :------------- | :--- | :------: | :---------- |
+| `ID` | `int` | no | Numeric id of the target lobby |
+
+### Implementation notes
+
+- Parser: `StartGameParser` — reads the required `ID` parameter and builds `StartGameRequest`.
+- Handler: `StartGameHandler` — resolves the lobby by id, checks the requester is a member of the
+  lobby, verifies a game is not already running and that enough players are present, initializes
+  `GameController` and attaches it to the lobby. On success a structured `START_GAME` success
+  response containing `GAME` and `MESSAGE` fields is returned.
+
+### Success Response
+| Field    | Type    | Description                       |
+| :------- | :------ | :-------------------------------- |
+| `GAME`   | `int`   | Numeric id of the started game (uses lobby id) |
+| `MESSAGE`| `String`| Human-readable status message     |
+
+### Error Response
+| Code             | Description                               |
+| :--------------- | :---------------------------------------- |
+| `MISSING_PARAMETER` | Required parameter `ID` missing (parser) |
+| `LOBBY_NOT_FOUND` | The specified lobby id does not exist     |
+| `NOT_IN_LOBBY`    | Requesting user is not a member of the lobby |
+| `NOT_ENOUGH_PLAYERS` | Not enough players to start the game   |
+| `ALREADY_STARTED` | A game is already running in the lobby   |
+| `USER_NOT_LOGGED_IN` | No user associated with the session    |
+
+### Example Request
+
+```
+
+START_GAME ID=1
+
+```
+
+### Example Response (success)
+
+```
+
+OK
+  GAME=1
+  MESSAGE=Game started successfully
+END
+
+```
 ```

 ## GET_LOBBY_LIST command
@@ -1111,4 +1168,58 @@ GET_LOBBY_STATUS ID=1
  CODE=LOBBY_NOT_FOUND
  MESSAGE=Lobby not found
 END
+```
+
+## CREATE_LOBBY command
+
+The `CREATE_LOBBY` command requests the server to create a new lobby and return its identifier.
+
+### Required pre-execution checks
+
+None.
+
+### Request Parameters
+
+No parameters.
+
+### Implementation notes
+
+- Parser: CreateLobbyParser — constructs a CreateLobbyRequest from the incoming PrimitiveRequest context (no parameters are read).
+- Handler: CreateLobbyHandler — calls LobbyManager.createNewLobby(null).
+  - If the returned LobbyId is null, the handler dispatches an ErrorResponse with code `LOBBIES_FULL` and message "Maximum number of 8 lobbies reached".
+  - On success, the handler dispatches a CreateLobbyResponse containing the new lobby id.
+
+### Success Response
+
+| Field     | Type | Description |
+| :-------- | :--- | :---------- |
+| `LOBBY_ID`| `int`| Numeric id of the newly created lobby |
+
+### Error Response
+
+| Code        | Description                                                            |
+| :---------- | :--------------------------------------------------------------------- |
+| `LOBBIES_FULL` | The server cannot create a new lobby because the maximum number of lobbies has been reached |
+
+### Example Request
+
+```
+CREATE_LOBBY
+```
+
+### Example Success Response
+
+```
+OK
+  LOBBY_ID=1
+END
+```
+
+### Example Error Response
+
+```
+-ERR
+  CODE=LOBBIES_FULL
+  MESSAGE=Maximum number of 8 lobbies reached
+END
 ```