//
// ============LICENSE_START=======================================================
//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
//  Modifications Copyright (C) 2020 Nordix Foundation.
// ================================================================================
// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
//
// SPDX-License-Identifier: CC-BY-4.0
// ============LICENSE_END=========================================================
//
// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
//

== Data Models

=== Sales Input Event
Each time a PoS system processes a sales item an event with the following format is triggered:

.Sale Input Event
[width="100%",options="header"]
|====================
|Event| Fields | Description
| SALE_INPUT | time, sale_ID, amount, item_ID, quantity, assistant_ID, branch_ID, notes, ... |  Event indicating a sale of an item is occurring
|====================

In each `SALE_INPUT` event the `sale_ID` field is a unique ID generated by the PoS system.
A timestamp for the event is stored in the `time` field.
The `amount` field refers to the value of the item(s) to be sold (in cents).
The `item_ID` field is a unique identifier for each item type, and can be used to retrieve more information about the item from _HyperM_'s stock control system.
The `quantity` field refers to the quantity of the item to be sold.
The `assistant_ID` field is a unique identifier for the PoS operator, and can be used to retrieve more information about the operator from the _HyperM_'s personnel system.
Since __HyperM__ has many branches the `branch_ID` identifies the shop.
The `notes` field contains arbitrary notes about the sale.


=== Sales Decision Event
After a `SALE_INPUT` event is triggered by the PoS system _HyperM_'s policy-based controlled sales checking system triggers a Sale Authorization Event indicating whether the sale is authorized or denied.
The PoS system can then listen for this event before continuing with the sale.

.Sale Authorisation Event
[width="100%",options="header"]
|====================
|Event| Fields | Description
| SALE_AUTH | sale_ID, time, authorized, amount, item_ID, quantity, assistant_ID, branch_ID, notes, message... |  Event indicating if the sale of an item is authorized or denied
|====================

In each `SALE_AUTH` event the `sale_ID` field is copied from the `SALE_INPUT` event that trigger the decision request.
The `SALE_AUTH` event is also timestamped using the `time` field, and a field called `authorised` is set to `true` or `false` depending on whether the sale is authorized or denied.
The `message` field carries an optional message about why a sale was not authorized.
The other fields from the `SALE_INPUT` event are also included for completeness.


=== Stock Control: Items
_HyperM_ maintains information about each item for sale in a database table called `ITEMS`.

.Items Database
[width="100%",options="header"]
|====================
|Table| Fields | Description
| ITEMS | item_ID, description, cost_price, barcode, supplier_ID, category, ... |  Database table describing each item for sale
|====================

The database table `ITEMS` has a row for each items that _HyperM_ sells.
Each item is identified by an `item_ID` value.
The `description` field stores a description of the item.
The cost price of the item is given in `cost_price`.
The barcode of the item is encoded in `barcode`, while the item supplier is identified by `supplier_ID`.
Items may also be classified into categories using the `category` field.
Useful categories might include: `soft drinks`, `alcoholic drinks`, `cigarettes`, `knives`, `confectionery`, `bakery`, `fruit&vegetables`, `meat`, etc..


=== Personnel System: Assistants

.Assistants Database
[width="100%",options="header"]
|====================
|Table| Fields | Description
| ASSISTANTS | assistant_ID, surname, firstname, middlename, age, grade, phone_number, ... |  Database table describing each _HyperM_ sales assistant
|====================

The database table `ASSISTANTS` has a row for each sales assistant employed by _HyperM_.
Each assistant is identified by an `assistant_ID` value, with their name given in the `firstname`, `middlename` and `surname` fields.
The assistant's age in years is given in `age`, while their phone number is contained in the `phone_number` field.
The assistant's grade is encoded in `grade`.
Useful values for `grade` might include: `trainee`, `operator`, `supervisor`, etc..


=== Locations: Branches

.Branches Database
[width="100%",options="header"]
|====================
|Table| Fields | Description
| BRANCHES | branch_ID, branch_Name, category, street, city, country, postcode, ... |  Database table describing each _HyperM_ branch
|====================

_HyperM_ operates a number of branches.
Each branch is described in the `BRANCHES` database table.
Each branch is identified by a `branch_ID`, with a branch name given in `branch_Name`.
The address for the branch is encoded in  `street`, `city`, `country` and `postcode`.
The branch category is given in the `category` field.
Useful values for `category` might include: `Small`, `Large`, `Super`, `Hyper`, etc..