Design Document - Product Handling

1. Business Requirements

• Goals of the Product Catalog Handling System:

  • Enable unified reporting across event editions.

  • Allow reuse of merchant products for multiple editions with customization.

  • Support merchants with multiple POS locations, each having multiple positions.

  • Support customization of products down to the position level. (in most cases the merchants have a flat list of products for all locations and positions, we aim to have minimal overhead and just enter overrides instead of copying products to different levels like in IntelliPay)

• Definition of Merchants, Products (Merchant, Event, Deposit), POS Locations, Positions. VAT Locations.

• Product Types and their availability rules:

  • The system must support two types of products: Merchant Products and Event Products.

  • Merchant Products:

    • Owned by Merchants, and can only be sold by POS locations associated to the merchant.

    • Customization of Merchant Product availability and details should be allowed for specific POS locations, or even individual positions.

      • A simple customization method is preferred, where only the differences from the global product list are configured.

    • Managed by merchants, but require festival approval before sale. (In current phase the merhant products will be managed by festival merchants won't have access to the system, merchant portal will be implemented in a later phase.)

    • Usually the same across multiple event editions (this will be handled post MMP via copying configuration from earlier event edition)

  • Event Products:

    • Owned by the festival, can be soled by all Merchants that the festival assigns to the products.

    • Can be selectively made available to merchants, POS locations, or positions participating in that edition.

    • Managed by the festival, not the merchants.

• Product Properties:

  • Products have the following properties:

    • Name

    • Type:

      • Fixed price by piece (increase/decrease quantity, multiple items can be summarized into a single line item, e.g., 2x beer + 1x beer = 3x beer)

      • Fixed price by custom unit (quantity entered for each line item separately, e.g., grams, 330g Steak, 220g Steak -> keep on separate line items)

      • Custom price (price entered for each line item, keep on separate line items)

    • Price (for the two fixed price types)

    • Voucher (type, and required amount of vouchers, optional, for the two fixed price types)

    • VAT category

    • Deposit product (optional)

    • Reporting category (single)

    • Search categories (multiple optional)

    • Age restriction category (optional)

    • Barcode (optional, used for scanning at aldi)

• Deposit Item Handling:

  • Requirement to handle deposit items (e.g., reusable cups or bottles, packaging or trash).

  • Deposit Item properties:

    • Name

    • Price

    • VAT category

    • Number of tokens (physical tokens for theft prevention)

  • Deposit items are a special type of product, usable for all merchants.

  • Each product can be associated with a single deposit item, deposit is optional.

  • When selling a product, the associated deposit item should be added to the line items automatically.

  • Configurable option to sell only a deposit item at specific terminals. (e.g. additional cups for a buttle of champagne, not common)

  • Handling deposit item returns by using the same deposit product as in sale in line items with a negative quantity. Return available at all positions

2. Business Solution

All product catalog related data is handled separately for each event edition, allowing for flexibility in product management and avoids conflicts between global and event-specific data. Unified reporting will be handled post MMP via labeling or other solutions. Reuse of merchant products across multiple event editions will be supported by copying configurations from earlier event editions.

• POS Configuration:

  • Introduction of a "POS Config" entity linked to a merchant. Each mearchant can have multiple POS Configs.

  • By default, a POS Config will include all products from the associated merchant.

  • Customization options within a POS Config:

    • Override price of a merchant product.

    • Hide a merchant product.

  • The following items have to be assigned individually

    • event products

    • deposit items for sale

  • Payment methods (cashless, open loop (direct purchase))

  • Assignment levels for POS Config:

    • For a Merchant

    • To a POS Location

    • To a position under a POS location

• POS Config Snapshot:

  • Introduction of a "POS Config Snapshot" entity.

  • Represents an immutable, versioned snapshot containing all products and their properties resulting from global product lists and POS Config overrides at the time of creation, further changes won't affect a snapshot a new version have to be generated in order to apply any changes either in Products or POS Configuration.

  • Snapshot creation will be a manual process initiated by a user.

  • (Post MMP support for an approval workflow based on snapshots)

  • Optimization for terminals: Terminals will check versions of the snapshot and only download a new snapshot if it has changed, preventing constant querying of the entire product and POS config database.

• Sale Process and Terminal Interaction:

  • Sales occur at terminals assigned to Positions under POS Locations.

  • The structure for sales is: Merchant -> POS Location -> Position -> Terminal.

  • Terminal devices are assigned to positions.

  • Terminals will detect the required mode of operation (e.g., POS) from the type of location under which they are assigned.

  • Terminals should automatically download changes to products when a new POS Config Snapshot is available.

3. Technical Solution

7. Open Questions/Decisions