add release notes

doc/release-notes/release-01-11-2024.md

@@ -0,0 +1,257 @@
+## List of changes
+New features:
+
+- Leaderboards
+- Player tasks = Daily tasks
+- Player statistics
+- Notifications of player tasks
+- Player points tracking
+
+
+Changes to existing features:
+
+- Item stealing logic
+- Log files saving
+- Clan creation default items
+- Models of Player, Clan, Item
+
+
+Other internal API changes
+
+- Enhanced Jest setup
+- Improved test coverage of /common package
+- Improved API architecture and its documentation
+- env variables handling logic
+
+## Links
+
+[Swagger file](https://github.com/Alt-Org/Altzone-Server/blob/dev/swagger/releases/01-11-2024-release.json)
+
+[Release](https://devapi.altzone.fi/latest-release/) address: _https://devapi.altzone.fi/latest-release/_
+
+
+## Contributors
+
+@PlayJeri
+@MikhailDeriabin
+
+
+## Detailed descriptions of changes
+
+
+### Leaderboards
+New endpoint /leaderboards/:board_type GET:
+
+_/leaderboards/player_ get top players based on `points` field
+_/leaderboards/clan_ get top clans based on `points` field
+
+You can see the logic behind the leaderboards mechanism [here](https://github.com/Alt-Org/Altzone-Server/tree/dev/doc/img/leader_board)
+
+### Player tasks
+
+Player tasks or "Daily tasks" tracking logic is now done for the following events:
+
+- Send x amount of messages
+- Play x amount of battles
+- Win x amount of battles
+
+Player's clan as well as Player himself/herself will get a defined amount of points and coins for each completed task.
+
+You can find the json file with all tasks and rewards [here](https://github.com/Alt-Org/Altzone-Server/blob/dev/src/playerTasks/playerTasks.json).
+
+There are an endpoint for retrieving player's tasks:
+
+- _/playerTasks_ GET with period query (daily, weekly, monthly) for specified the required period of the tasks.
+
+All the tracking logic is hidden and happen automatically for example, when a player wins a game the "win battles" tasks info is updated.
+Here is a list of the endpoints used for track the tasks:
+- /gameData/battle POST
+- /chat/:_id/messages POST
+
+You can check the player tasks logic in [this diagram](https://github.com/Alt-Org/Altzone-Server/blob/dev/doc/img/daily_task/daily_task_add_update.svg)
+
+
+### Player statistics
+
+Now the following player statistic is being tracked:
+- played battles
+- won battles
+- sent messages
+
+The statistics tracking is hidden in the API logic and being updated by API automatically via these endpoints:
+- /gameData/battle POST
+- /chat/:_id/messages POST
+
+The statistics can be retrieved from nested object `gameStatistics` in Player data:
+- /player GET
+- /player/:_id GET
+
+Notice however that if player does not have any statistics yet, this object will not be provided.
+
+
+### Notifications of player tasks
+
+There are now notifications of updated or completed player tasks.
+
+Notice that the notification are sent via MQTT over WS protocol, 
+that means that the client need to subscribe to certain topics in order to get the notifications.
+
+Read more about the notifications mechanism and structure [here](https://github.com/Alt-Org/Altzone-Server/blob/dev/doc/img/notifications/mqtt_notifications_mechanism.svg)
+
+Notice that the protocol that you need to use on the client (URL start) is probably should start from _ws:_ not _mqtt:_, 
+but the logic remains same as it is for MQTT protocol, so you should use a library for the MQTT protocol.
+
+Notice that it is possible only to subscribe to topics, but not publish.
+
+The topics are secured with a password, please reach me out to get it and store it in a secure place. 
+At the moment the password will not change and any other security measures are taken to protect the topics, 
+so that it is possible to set up everything on the client with ease.
+
+You can subscribe to all notification coming to a player with this topic: _/player/{player _id}_. 
+You can also subscribe to more specific topics if you or the player want to choose which notifications should be shown in UI. 
+The more fine tuned subscription is the recommended way to subscribe in order to save server resources.
+
+The notifications of player tasks have the task data as a payload.
+
+Here are a list of all supported atm topics:
+
+- /player/{player_id}/daily_task/update updates of task data, for example when player send a message or win a game
+- /player/{player_id}/daily_task/end the task is done, for example player won 3 games = completed daily task
+
+
+### Player points tracking
+
+Player now will get additional points for different events happen. Currently the following events are tracked and therefore supported:
+
+- Player sends 3 messages in a day +20 points
+- Player wins a game +50 points
+- Player plays a game +10 points
+
+
+### Item stealing logic
+
+Item stealing flow is now slightly changed and now by requesting data from _/item/steal GET_ 
+only not empty rooms will be returned, but not all as it was before.
+
+
+### Log files saving
+
+The log files logic is changed, so that now a separate folder created for each battle,
+it is possible to set the folder name for the log file with `Battle-Id` header or it will be current timestamp as default.
+
+Also the max file size is increased to 50 MB.
+
+The changed endpoint is _/gameAnalytics/logFile POST_.
+
+
+### Clan creation default items
+
+There are now other items created for the clan, which are corresponding to existing ones:
+
+For stock:
+```ts
+{...itemProperties.Carpet_Rakkaus, stock_id, room_id: null, unityKey: ItemName.CARPET_RAKKAUS, location : [1,1] },
+{...itemProperties.Mirror_Rakkaus, stock_id, room_id: null, unityKey: ItemName.MIRROR_RAKKAUS, location : [1,2] },
+{...itemProperties.Closet_Rakkaus, stock_id, room_id: null, unityKey: ItemName.CLOSET_RAKKAUS, location : [1,3] }
+```
+
+For room:
+
+```ts
+{...itemProperties.Sofa_Rakkaus, stock_id: null, room_id, unityKey: ItemName.SOFA_RAKKAUS, location : [1,1] },
+{...itemProperties.Carpet_Rakkaus, stock_id: null, room_id, unityKey: ItemName.CARPET_RAKKAUS, location : [1,2] },
+{...itemProperties.Chair_Neuro, stock_id: null, room_id, unityKey: ItemName.CHAIR_NEURO, location : [1,3] },
+{...itemProperties.SideTable_Taakka, stock_id: null, room_id, unityKey: ItemName.SIDETABLE_TAAKKA, location : [1,4] },
+{...itemProperties.Floorlamp_Taakka, stock_id: null, room_id, unityKey: ItemName.FLOORLAMP_TAAKKA, location : [1,5] },
+{...itemProperties.Sofa_Taakka, stock_id: null, room_id, unityKey: ItemName.SOFA_TAAKKA, location : [1,6] }
+```
+
+### Models of Player, Clan, Item
+
+Player model now have the `points` and `gameStatistics` fields.
+
+Clan model now have the `labels` and points fields, as well as the `tag` field is deprecated now.
+
+Item model is changed and uses more enums:
+```ts
+export class ItemDto {
+    _id: string;
+    name: ItemName;
+    weight: number;
+    recycling: Recycling;
+    qualityLevel: QualityLevel;
+    unityKey: string;
+    price: number;
+    location: Array<number>;
+    isFurniture: boolean;
+
+    stock_id: string;
+    Stock: StockDto;
+
+    room_id: string;
+    Room: RoomDto;
+}
+
+//Here are the enums used:
+enum ItemName {
+    SOFA_TAAKKA = 'Sofa_Taakka',
+    MIRROR_TAAKKA = 'Mirror_Taakka',
+    FLOORLAMP_TAAKKA = 'Floorlamp_Taakka',
+    TOILET_SCHRODINGER = 'Toilet_Schrodinger',
+    SINK_SCHRODINGER = 'Sink_Schrodinger',
+    CLOSET_TAAKKA = 'Closet_Taakka',
+    SOFATABLE_TAAKKA = 'SofaTable_Taakka',
+    SIDETABLE_TAAKKA = 'SideTable_Taakka',
+    CARPET_SCHRODINGER = 'Carpet_Schrodinger',
+    CARPET_RAKKAUS = 'Carpet_Rakkaus',
+    MIRROR_SCHRODINGER = 'Mirror_Schrodinger',
+    MIRROR_RAKKAUS = 'Mirror_Rakkaus',
+    ARMCHAIR_TAAKKA = 'ArmChair_Taakka',
+    SOFA_RAKKAUS = 'Sofa_Rakkaus',
+    ARMCHAIR_RAKKAUS = 'ArmChair_Rakkaus',
+    CLOSET_RAKKAUS = 'Closet_Rakkaus',
+    CHAIR_NEURO = 'Chair_Neuro',
+    DRESSER_NEURO = 'Dresser_Neuro',
+    STOOL_NEURO = 'Stool_Neuro',
+}
+
+enum Recycling {
+    MIXED_WASTE = 'Mixed_waste',
+    ELECTRICAL_EQUIPMENT = 'Electrical_Equipment',
+    WOOD = 'Wood',
+    GLASS = 'Glass',
+    METAL = 'Metal',
+    LANDFILL = 'Landfill'
+}
+
+enum QualityLevel {
+    common = 'common',
+    rare = 'rare',
+    epic = 'epic'
+}
+```
+
+### Enhanced Jest setup
+
+The jest is now configured to use in-memory DB, which is cleaned automatically after each test. 
+Also custom matchers are added for Service and API errors.
+
+Tests structure is improved: test data builders are introduced in order to decouple tests from the data structures use din the code.
+
+
+### Improved test coverage of /common package
+
+More tests are written for _/common_ package and the coverage now is close to 80% of the package.
+
+
+### Improved API architecture and its documentation
+
+Now API has more modular structure and have less coupling.
+
+Also a new [diagram](https://github.com/Alt-Org/Altzone-Server/tree/dev/doc/img/architecture) of API modules is created.
+
+
+### env variables handling logic
+
+The env variables retrieving now happening via a separate object not straight from the file.
+Also a check of the .env file validity is added on the start of the API.