From ad0293b954d444abf4cea50dc4182d841007f1a1 Mon Sep 17 00:00:00 2001 From: Raphael Michel Date: Wed, 10 Sep 2014 00:30:47 +0200 Subject: [PATCH] Documentation: explain some basic concepts --- doc/development/concepts.rst | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/doc/development/concepts.rst b/doc/development/concepts.rst index ad89552d7..0b8166573 100644 --- a/doc/development/concepts.rst +++ b/doc/development/concepts.rst @@ -4,9 +4,12 @@ Implementation Concepts Basic terminology ----------------- -Tixl is a sofware selling **Items**, an abstract thing which is related to an **Event**. Every Event is managed by the **Organizer**, who runs the event. +Users and events +^^^^^^^^^^^^^^^^ -Tixl know two types of **Users**: +Tixl is all about **events**, which are defined as something happening somewhere. Every Event is managed by the **organizer**, an abstract entity running the event. + +Tixl is used by **users**, of which it knows two types: **Local users** Local users do only exist inside the scope of one event. They are identified by usernames, which are only valid for exactly one event. @@ -16,3 +19,31 @@ Tixl know two types of **Users**: For more information about this user concept and reasons behind it, see the docstring of the ``tixlbase.models.User`` class. +Items and flavors +^^^^^^^^^^^^^^^^^ + +The purpose of tixl is to sell **items** (which belong to **events**) to **users**. An **item** is a abstract thing, popular examples being event tickets or a piece of merchandise, like 'T-Shirt'. An **item** can have multiple **properties** with multiple **values** each. For example, the **item** 'T-Shirt' could have the **property** 'Size' with **values** 'S', 'M' and 'L' and the **property** 'Color' with **values** 'black' and 'blue'. + +Any combination of those **values** is called a **flavor**. Using the examples from above, a possible **flavor** would be 'T-Shirt S blue'. + +Restrictions +^^^^^^^^^^^^ + +The probably most powerful concepts of tixl is the very abstract concept of **restricitons**. We already know that **items** can come in very different **flavors**, but a **restriction** decides whether an item is available for sale and assign **prices** to **flavors**. There are **restriction types**, which are pieces of code implementing the restrictions and **restriction instances**, which are configurations made by the **organzier**. Although **restrictions** are a very abstract concept which can be used to do nearly anything, there are a few obvious examples: + +* One easy example is the time restriction, which allows the sale of certain item flavors only within a certain time frame. As restrictions can also assign a price to a flavor, this can also be used to implement something like 'early-bird prices' for your tickets by using multiple time restrictions with different prices. +* The most obvious example is the number restriction, which limits the sale of the tickets to a maximum number. You can use this either to stop selling tickets completely when your house is full or for creating limited 'VIP tickets'. +* A more advanced example is a restriction by user, for example reduced ticket prices for members who are members of a special group. +* Arbitrary sophisticated features like coupon codes are also possible to be implemented using this feature. + +Any number of **restrictions** can be applied to the whole of a **item** or to a specific **flavor**. The processing of the restriction follows the following set of rules: + +* **Flavor**-specific rules have precedence over **item**-specific rules. +* The restrictions are being processed in random order (there may not be any assumptions about the evaluation order). +* Multiple restriction instances of **different restriction types** are linked with *and*, so if both a time frame and a number restriction are applied to an item, the item is only avaliable for sale within the given time frame *and* only as long as items are available. +* Multiple restriction instances of the **same restriction type** are linked with *or*, so if two time frames are applied to an item, the item is available for sale in both of the time frames. (This behaviour is actually a decision of the restriction type itself, so this rule is not enforced but rather a general rule of thumb). +* If multiple restrictions apply which set the price, the *cheapest* price determines the final price. + +Restriction types can be introduced by 3rd-party code and do not require changes to the tixl codebase. + +.. note:: This pluggability of restrictions is implemented using the 'signal and receiver' pattern provided by Django. Restrictions can therefore live in seperate Django apps.