swt23w23/src/main/asciidoc/developer_documentation.adoc

281 lines
14 KiB
Plaintext
Raw Normal View History

2023-10-05 11:42:24 +02:00
[options="header"]
[cols="1, 3, 3"]
|===
|Version | Bearbeitungsdatum | Autor
|... | ... | ...
|===
= Entwicklerdokumentation
== Introduction and Goals
== Task Definition
As our client Mr Wurst has built up the large catering service Mampf over the years, he now needs a system that will simplify planning for him and his customers. The catering service should enable him to process all billing, ordering and administrative tasks in a standardised way. Previously, Mr Wurst used various programmes for this and was always annoyed by their incompatibility with each other and the additional work involved in separate data storage. He gave us the following description of his small company as a basis for the system development:
The company is divided into four business areas. Event catering provides catering for large events, whether in the form of a buffet or a gala dinner. On request, Mampf can also organise the entire event, i.e. in addition to the food and drinks, decoration, equipment (i.e. crockery, tablecloths, etc.) and staff are also provided, whereby the customer must of course pay rental fees and staff costs in addition to the actual price for food and working hours. The party service supplies private celebrations with cold platters - from weddings and funerals to garden parties and grandma's 75th birthday. There are fixed prices depending on the offer and number of people (e.g. ham platter for 5 people at EUR 20, cheese platter for 3 people at EUR 12.50, etc.) and special offers (e.g. sushi evening for 10 people). A speciality of Mampf is Mobile Breakfast - a mobile breakfast service for smaller companies without their own canteen. Employees can buy a selection of breakfast options (sandwiches, muesli, coffee and tea, etc.) at their workplace at set times. The companies book the offer on a monthly basis. However, planning this offer is problematic - a cost-saving solution (e.g. in the form of pre-ordering) is currently being sought. Mampf's fourth offer is also becoming increasingly popular with customers: Rent-a-Cook. This involves hiring out kitchen and service staff to private households, for example to impress the host's boss with culinary delights. Customers have to take care of the food themselves.
The most important functions that the system should include are to support customer management, take over staff management and allocation, plan appointments, manage accessories (decoration, equipment), determine food requirements (number of dishes/plates/served sandwiches, quantity of drinks in litres), simplify invoicing to customers and facilitate all billing. However, food procurement does not have to be considered. In the end, the catering service should be fully functional and include all the functions already mentioned. The aim is to use centralised data management to make processes more efficient, especially planning within the company. The system should be easy to expand in order to open up new business areas.
The client made the following statements verbally on request:
Customers must be able to register themselves, book orders and delete their account if necessary. The latter should also be possible for the administrator for any customer. The administrator also has special overview pages for managing the business. Orders can only be paid for in cash. The allocation of resources to an order must take place without manual intervention. As part of the special promotions mentioned above, certain offers should have a promotional price and be specially labelled. Bookings for Mobile Breakfast are made on a monthly basis at fixed time slots. There are several menus to choose from. Invoice means an informal list of order items in PDF format and on the website. Billing refers to an informal statement of the actual hours worked by employees each month. In technical terms, passwords for user accounts should be stored securely in accordance with current standards.
== Quality Demands
Functional Suitability::
This characteristic represents the degree to which a product or system provides functions that meet stated and implied needs when used under specified conditions.
Performance efficiency::
This characteristic represents the performance relative to the amount of resources used under stated conditions.
Compatability::
Degree to which a product, system or component can exchange information with other products, systems or components, and/or perform its required functions while sharing the same hardware or software environment
Usability::
Degree to which a product or system can be used by specified users to achieve specified goals with effectiveness, efficiency and satisfaction in a specified context of use.
Reliability::
Degree to which a system, product or component performs specified functions under specified conditions for a specified period of time.
Security::
Degree to which a product or system protects information and data so that persons or other products or systems have the degree of data access appropriate to their types and levels of authorization
Maintainability::
This characteristic represents the degree of effectiveness and efficiency with which a product or system can be modified to improve it, correct it or adapt it to changes in environment, and in requirements.
Portability::
Degree of effectiveness and efficiency with which a system, product or component can be transferred from one hardware, software or other operational or usage environment to another.
The following table shows what quality demands have to be fulfilled to which extent.
The first column lists the quality demands, while in the following columns an "x" is used to mark the priority.
1 = Not Important ..
5 = Very Important
[options="header", cols="3h, ^1, ^1, ^1, ^1, ^1"]
|===
|Quality Demand | 1 | 2 | 3 | 4 | 5
2023-11-07 10:32:37 +01:00
|Functional Suitability | | | | | x
|Performance efficiency | x | | | |
|Compatability | x | | | |
2023-11-07 10:32:37 +01:00
|Usability | | | | x |
|Reliability | | | | x |
|Security | | x | | |
|Maintainability | | | x | |
2023-11-07 10:32:37 +01:00
|Portability | x | | | |
|===
2023-10-05 11:42:24 +02:00
== Constraints
Each constraint is annotated with b, r and/or u,
each representing if it is a
build-time (includes development),
run-time (backend),
or use-time (frontend)
constraint.
Use-time constraints can be separated into customer (c) and administration (a),
each denoted by having their letter prefixed with `u.`.
=== Hardware Specifications
* r: server computer
* b: mid-range computer
* u: computer
* b: input device for text
* u: input/output devices
** pointing device
(e.g, mouse, TrackPoint™, digitizer, touch input)
** text input device
(i.e. keyboard),
can be emulated (software/touch or for accessibility reasons)
** u.a: screen with a resolution of at least 1920×1080 at a DPR of 1 (= 96dpi)
** u.c: screen with a resolution of at least 360×640/640×360 at a DPR of 1 (= 96dpi)
=== Software Specifications
* r: JRE 17
* b: JDK 17
* u: Any HTML5/CSS3 compatibly browser using one of the following engines (or a newer version)
** Chromium 108
** Firefox 115
** WebKit 605.1.15
** Explicity not supported are any browsers based on Trident/EdgeHTML
=== Product Usage
The system is going to to be used as a website for administration and handling of orders for the catering service operated by Hannes Wurst.
The system is supposed to run on a server computer
(a computer running 24/7 with a datacenter-grade internet connection)
so that customers and the administrator can access it at any time.
Its provided service is made available as a web site (HTML5/CSS3/ECMAScript over HTTP).
Should the customer of the project require an encrypted connection using TLS,
it is their responsibility to set up a reverse proxy in front of the system.
It cannot be assumed that the users (customers and administrator) have a technical background,
so common patterns that are easily learned should be used.
2023-10-05 11:42:24 +02:00
== Kontextabgrenzung
image:models/design/systemContextDiagram.svg[]
2023-10-05 11:42:24 +02:00
== Lösungsstrategie
2023-11-09 17:22:54 +01:00
=== Quality Demand Fulfillment
2023-10-05 11:42:24 +02:00
[options="header"]
2023-11-09 17:22:54 +01:00
|===
|Quality Demand |Solution approach
|Functional Suitability a|
* *Exchange* Ensure that the exchange of system data between the system component works flowlessly.
* *Requirements* Ensure that all functional requirements as descripted in the contrect are fulfilled.
|Performance efficient a|
*Not important*
|Compatability a|
*Not important*
|Usability a|
* *Language* Ensure that every word on the web interface corresponds to its definition in the industry.
* *Learnability* Ensure that the system can be easily used and understood by its users. This can be realized by e.g. unambiguously describing the content of inputs with labels or tooltips.
* *User error protection / Error handling* Protect user against making errors. Invalid inputs must not lead to invalid system states.
* *User interface aesthetics* Provide a pleasing and satisfying interaction for the user.
* *Accessibility* Ensure that people with a wide range of characteristics can fully use the system. This can be realized by e.g. using suitable font sizes and color contrasts.
|Reliability a|
* *Tests* Add tests to ensure functional integrity.
|Security a|
* *Confidentiality* Ensure that only data can be only accessed by people who are authorized to access them. This can be realized with _Spring Security_ and _Thymeleaf_ (`sec:authorize` - tag).
* *Integrity* Prevent unauthorized modification of data. This can be realized with _Spring Security_ (`@PreAuthorize` - annotation).
* *Accountability* Traceability of actions or event to a unambiguously entity or person. For this application, every `Order` should be linked to a `Customer`.
|Maintainability a|
* *Modularity* Compose the application out of discrete components such that changes of a component have less impact on other components.
* *Reusability* Ensure that components of the system can be reused by other components or systems.
|Portability a|
*Not important*
2023-10-05 11:42:24 +02:00
|===
=== Softwareararchitecture
==== Top-Level-Architecture
image:models/design/topLevelArchitecture.svg[]
==== Client-Server-Diagram
image:models/design/clientServer.svg[]
2023-10-05 11:42:24 +02:00
=== Entwurfsentscheidungen
* Verwendete Muster
* Persistenz
* User Interface
image:models/design/dialogue_map.svg[Dialog Map of the Videoshop]
2023-10-05 11:42:24 +02:00
* Verwendung externer Frameworks
[options="header", cols="1,2,3"]
|===
|Externes Package |Verwendet von |Warum
|... |... |...
|===
== Building block view
=== Package diagram
2023-10-05 11:42:24 +02:00
Note: In this example project the content package diagram would look like the Top Level Architecture, so it was omitted.
=== Catering
image:models/design/catering.svg[class design diagram - Catering]
[options="header"]
|===
|Class/Enumeration |Description
|Catering|The central application class to configure the Spring container and run the application
|CateringWebConfiguration|Configuration class to route `/login` directly to the `login.html` template
|WebSecurityConfiguration|Configuration class to set up basic security and login/logout options
|===
=== Catalog
image:models/design/catalog.svg[class design diagram - Catalog]
2023-10-05 11:42:24 +02:00
[options="header"]
|===
|Class/Enumeration |Description
|CatalogController |A Spring MVC Controller to handle requests to show ``Product``s
|CatalogInitializer |An implementation of the DataInitializer to create dummy ``Product``s on application startup
|Consumable,Rentable| Extensions of ``Product`` to describe offered Products more precise
|ConsumableCatalog, RentableCatalog| An extension of Salespoint.Catalog to add catering specific queries
|===
=== Inventory
image:models/design/inventory.svg[class design diagram - Inventory]
[options="header"]
|===
|Class/Enumeration |Description
|InventoryController |A Spring MVC Controller to handle the request to list and mutate the catering services inventory
|InventoryInitilalizer |An implementation of the DataInitializer to create dummy data on application startup
|InventoryMutateForm |An class to validate the user input of the edit/add form
|===
=== Order
image:models/design/order.svg[class design diagram - Order]
[options="header"]
|===
|Class/Enumeration |Description
|OrderController |A Spring MVC Controller to handle the cart and all orders
|CustomOrder |An extension of `Order` to save the start and finish of an event
|ProductForm |A Form to cache a user input that was made while planning and event
|===
=== User
image:models/design/user.svg[class design diagram - User]
[options="header"]
2023-10-05 11:42:24 +02:00
|===
|Class/Enumeration |Description
|===
=== Staff
image:models/design/staff.svg[class design diagram - Staff]
[options="header"]
|===
|Class/Enumeration |Description
2023-11-10 19:01:38 +01:00
|Usercontroller |A Spring MVC Controller to handle profile management.
|UserDataInitalizer |An Initalizer with primary purpose to add the admin.
|UserManagement |A class that manages the UserRepository.
|UserRepository |An exntension of 'CrudRepository' to save Users.
|User |A class that allows a person to associate system data with themself.
|===
2023-10-05 11:42:24 +02:00
=== Rückverfolgbarkeit zwischen Analyse- und Entwurfsmodell
_Die folgende Tabelle zeigt die Rückverfolgbarkeit zwischen Entwurfs- und Analysemodell._
[options="header"]
|===
|Klasse/Enumeration (Analysemodell) |Klasse/Enumeration (Entwurfsmodell)
|... |...
|===
== Laufzeitsicht
* Darstellung der Komponenteninteraktion anhand eines Sequenzdiagramms, welches die relevantesten Interaktionen darstellt.
=== Catalog
image:models/design/seq_catalog.svg[sequence diagram - catalog]
=== User
image:models/design/seq_users.svg[sequence diagram - user]
=== Inventory
image:models/design/seq_inventory.svg[sequence diagram - inventory]
=== Order
image:models/design/seq_order.svg[sequence diagram - order]