Specification for a new functionality.

User story
As a game master I want to be able to start a new campaign. I want to specify its title and in-game start date.

To do:

• the API endpoint
  • the role role_start_campaign
• the web-app component

The administrators should have an option to manage users. The implementation should be refactored and extended version of the code provided by the POC.

This issue is a part of the issue #5.

Use case 1
The user should be able to receive an authentication token, by using the web-api endpoint api\auth\login.

Use case 2
The user should be able to logout, by using the web-api endpoint api\auth\logout. The authentication token provided in the request header should be then blacklisted.

Use case 3
The user should be able to be authorised by providing the authentication header in the request. To fulfil the authorisation requirements, the token has to be valid (not expired and not blacklisted), and the user must have the permission specified for the called endpoint.

This issue is a part of the issue #5.
This issue should be implemented along with the issue #7.

To do:

• The new service auth_service with methods log_in and log_out
• Blacklisting Tokens
• Authenticating tokens given in the request header

Remediation

Upgrade acorn to version 6.4.1 or later. For example:

"dependencies": {
  "acorn": ">=6.4.1"
}

or…

"devDependencies": {
  "acorn": ">=6.4.1"
}

Right now, the arguments passed through execution chains are validated in various layers. This is inconsistent and very chaotic.

Key points of the refactoring

• DAOs do not validate their arguments
• internal services validate their arguments and produce an exception with a correct message for logging purposes
• services catch exceptions and pass them to the error handler, which produces a correct error message for the end-users

This decision should be also documented in the project wiki.

To do:

• Refactoring
  • Persistence layer
    • user_dao
      • create method and its tests
    • user_history_dao
      • create method and its tests
  • Internal services layer
    • auth_internal_service
      • generate_token method and its tests - here handling a missing property can be made better.
    • user_internal_service
      • check_if_user_exists method and its tests
      • create_user and its tests
    • user_history_internal_service
      • create_user_history_entry method and its tests
  • Services layer
    • auth_service
      • authenticate method - checking user roles should be moved to a separate method, possibly in the auth_internal_service class (?)
    • startup_service
      • check_if_superuser_exists method and its tests
      • create_superuser method and its tests; handling missing property
• Integrative tests for the existing endpoints:
  • auth_endpoint.log_in
  • auth_endpoint.log_out
• Documentation for argument validation, properties validation and error handling

User story
As an administrator I want to be able to delete a user.

On the application startup the program should check, if the superuser exists - if not, it should be created. This functionality has been already implemented in the POC. The new implementation should be based on the old one, but refactored to match the new architecture principles.

This issue is a part of the issue #5.

The implementation details:

Persistence layer

• The method user_dao.read_by_user_name
  Reads the user from the database.

• The method user_dao.create
  Persists a new user in the database.

• The method user_history_dao.create
  Persists a new user history entry in the database.

Internal services layer

• The method user_internal_service.check_if_user_exists
  Calls the method user_dao.read_by_user_name. If the returned value is not None, returns True, False otherwise.

• The method user_internal_service.create_user
  Calls the method user_dao.create.

• The method user_history_internal_service.create_user_history_entry
  Calls the method user_history_dao.create.

Services layer

• The method startup_service.check_if_superuser_exists
  Calls the method user_internal_service.check_if_user_exists with the superuser as a user name, handling all the exceptions that can occur. Returns a standard service response.

• The method create_superuser
  Retrieves the superuser's password from the properties, creates the password hash string (using Werkzeug), creates the superuser input data and calls user_internal_service.create_user. Then, it creates the input data and calls user_history_internal_service.create_user_history_entry. It should handle all the exceptions that can occur and return a standard service response.

The functionalities provided by the POC should be implemented in the app.

The functionalities to migrate:

• Creation of the superuser #10
• User authentication #6
• Roles #7
• Managing users by users with administrator privileges #8
• Displaying a list of campaigns run by the currently logged in game master #9

Upgrade handlebars to version 4.3.0 or later. For example:

"dependencies": {
  "handlebars": ">=4.3.0"
}

or…

"devDependencies": {
  "handlebars": ">=4.3.0"
}

On login, when an incorrect user name is given and the password input is empty, the following message is shown: Niepoprawny login lub hasło.. This is the desired behavior, but when the user name is correct and the password input is empty, the message is: Brakujące dane: Hasło.. This can be used by a malevolent person to get access to existing user names.

To do:

• The message in both cases is Niepoprawny login lub hasło.

When a user does not log out from the application, the token remains in the local storage. This way it is possible to access the dashboard with an expired token.

On the web-application startup, if a token is present in the local storage, it should be validated.

To do:

• implement validation of a token in the local storage on the web-application startup

The web-application is missing a component that would display messages sent by the application.

To do:

• implement the messaging component

Specified in #23

• use of native Python exceptions
• making use of exception args instead of raising an error with a message for the frontend (mixed technical and presentation layer)

Right now, when an administrator creates a new user, s/he must provide a password.

The password should be generated and displayed only once after creation. The same should happen after password reset, a feature described in #29.

User story
As a user I want to be able to view a page with all the details of a campaign I participate in/run.

The following data should be shown on the details page:

• Title
• ID
• Date of creation
• Game master's name
• Begin date
• Passed days
• Current in-game date
• Timeline
• Participating players

The children components to implement:

• Campaign info (title, ID, date of creation)
• Game master info (Game master's name and a placeholder for an avatar)
• In-game time (Begin date, passed days, current date)
• Campaign timeline (Just a stub for now - the implementation of the timeline itself is a part of a different story)
• Participating players (A stub - the list is a part of a different story)

TODO

Since more subtypes of BusinessError will be implemented and raised during the validation processes, a handler for these exceptions should be implemented to be used in services.

The handler should return a corresponding message in Polish basing on the type of error passed as an argument.

To do:

• implement a new util module error_handler
• resolve all the TODOs in #12

Integration of the ngx-translate in the GUI app.

TODO

User story
As an administrator I want to be able to reset user's password.

Use case
The user should be able to call the endpoints, to which their role grants an access.

This issue is a part of the issue #5.
This issue should be implemented along with the issue #6.

To do:

• Definition of the user roles
• Role checking on the web-service method call

User story
As a player I want to be able to view all campaigns I participate in and navigate to the page of a selected one.

User story
As an admin I want to be able to see details of every campaign, whether I am its game master or a player participating in it, or not.

This issue describes a feature that allows game masters to create session summaries - short descriptions of what happened during each session. The summaries can be seen on the details page of a campaign.

Editor for session summaries

User story
As a game master I want to be able to add a session summary to my campaign. I should be able to specify the date when the session took place, add a session title and a text describing what happened during the session.

GUI

First step in implementing the editor is to add a toolbar on the campaign page. It should only appear when the page is opened by the game master of a particular campaign. The toolbar should be placed just under the header. The design prototype is shown in the image below:

The button on the toolbar should lead to the page with the editor, illustrated by the prototype below:

When the submit button is clicked, the editor should check if the fields with title and the date are filled, and show an appropriate warning if not (the description can be left empty). If everything is correct, a POST request should be sent towards the backend.

Backend

The creation of a new session summary should be able through the endpoint: \my_campaigns\<int:campaign_id>\timeline\entry (method: POST). On the endpoint call, the application should make the following checks:

• the caller has the role ROLE_CREATE_SESSION_SUMMARY
• the caller is a game master of the given campaign
• the date of the summary is not empty
• the title of the summary is not empty

Entity CAMPAIGN_TIMELINE

Session summaries should be stored in the database in the new table: CAMPAIGN_TIMELINE:

Viewer for session summaries

User story
As a user I want to be able to see the summaries of all sessions of a campaign. The summaries should be displayed on the campaign page.

GUI

The stub implementation of the GUI component showing session summaries has been already added to the details page of a campaign. In this issue a working solution should be implemented, as shown by the image below:

Backend

The data shown by the component should be retrieved by the GUI through the endpoint: \my_campaigns\<int:campaign_id>\timeline (method: GET).

The endpoint should return all session summaries of the campaign. On the call it should check if the user is related to the campaign and has a role ROLE_VIEW_CAMPAIGN_TIMELINE.

Additional points

• The new roles should be assignable in the user creator.

Basic flask-app should be implemented.

User story 1
As a game master I want to be able to invite other players to my campaigns by giving their user name.

User story 2
As a player I want to be able to receive and view the invitations. I want to be able to respond to them and give an information with which character I want to participate in.

User story 3
As a game master I want to be able to accept or decline the character proposals. When I decline a character, the invitation should return to the player, who can respond with the same (corrected) character or a new one.

User story
As a player I want to be able to create a character.

In the first phase the creator should be implemented only as a stub: Users should be able to specify only the name of a character.

Specified in #23

To unify the format of the dates across the application, the UTC date should be used everywhere.
It should be up to the client to transform the date to the correct time zone.

The method auth_service.log_in does not handle errors that can be raised by the auth_internal_service on generating the authentication token.

To do:

• implement error handling for token generation
• add missing unit tests

In the POC displaying the list of campaigns run by the currently logged in game master has been implemented. This implementation should be migrated into the application.

This issue is a part of the issue #5.

Use case
As a game master I want to be able to see a list of all campaigns that I run. I want to have access to this list from my dashboard.

To do:

• SQL script with create statements for the tables campaign and campaign_history
• New module in backend: campaign
  • New entities corresponding to the new tables
  • New module campaign_repository with the method get_by_gm_id retrieving the GM's campaigns from the database
  • New module campaign_service with the method get_campaigns_by_gm_id validating the existence of the given user and calling the repository
• New role: role_show_owned_campaigns allowing a user to view the campaigns belonging to him
• New method in the auth_service -- get_user_id. The method should return the ID of the currently logged in user
• New endpoint api/my_campaigns and the web-method /list
• New web-app module and component for the list of owned campaigns
• New dashboard element in the web-app

Background

In #22 the page showing the details of a selected campaign has been implemented, but it shows stub-data. In this issue we add a new API endpoint that should deliver the data from the database and modify the GUI to integrate it with the endpoint.

Requirements

The endpoint should be available under the URL: /api/my_campaigns/details/<campaignId>

The web method: GET

Only the users who are the game masters of a given campaign should be able to get the data. In the future this functionality will be made available also to the participating players.

The object returned by the endpoint should have the following structure:

{
    "status": "success",
    "message": "",
    "campaignDetails": {
        "id": 99,
        "title": "<campaign title>",
        "creationDate": "<date in the ISO format>",
        "startDate": "<date in the ISO format>",
        "passedDays": 99,
        "currentDate": "<date in the ISO format>",
        "gameMasterId": 99,
        "gameMasterName": "<user name>"
    }
}

On any error, the endpoint should return the following response:

{
    "status": "failure",
    "message": "<error description>"
}

The GUI application should send the request in the MyCampaignsAdapterService class.

The component CampaignDetailsComponent (and its subcomponents) should call the service, get the data and display it correctly.

Additional information

currentDate - this field is in fact the result of the following equation: startDate + passedDays

gameMasterId - we do not want to show it on the page. It is sent with the response for future use (navigating to the details of a user)

To do:

• New API endpoint
• GUI integration

In order to extend the abilities of the application, a new frontend should be introduced - a web-app created in Angular.

This task is about providing a prototype of such application and adjusting the existing code to the requirements.

To do:

• The main flask-app should provide only one view - the index of the Angular app
• All other views should be converted into REST API endpoints
• The usage of the flask.session should be removed - required authentication should be token-based
• Working login, logout and dashboard functionalities
• Cleanup after the implementation

The issue will be implemented on the separate branch dev_webapp_prototype.

When all the to-dos in this issue are implemented, the branch will be able to be merged into the main development branch.

For one of the dependencies of the web-app a security risk has been reported.

Dependency name: serialize-javascript
Current version: 1.9.1
Safe version: 2.1.1

User story
As a user I want to be able to change my password.

The basic layout of the project structure should be created.