# Logic

## Definitions

- User has one 'active Cart' at a time. The Cart remains active until a paid Invoice is attached to it.

- A 'paid Cart' is a Cart with a paid Invoice attached to it, where the Invoice has not been voided.

- An unpaid Cart is 'reserved' if

 - CURRENT_TIME - "Time last updated" <= max(reservation duration of Products in Cart),

 - A Voucher was added and CURRENT_TIME - "Time last updated" < VOUCHER_RESERVATION_TIME (15 minutes?)

- An Item is 'reserved' if:

  - it belongs to a reserved Cart

  - it belongs to a paid Cart

- A Cart can have any number of Items added to it, subject to limits.

## Entering Vouchers

- Vouchers are attached to Carts

- A user can enter codes for as many different Vouchers as they like.

- A Voucher is added to the Cart if the number of paid or reserved Carts containing the Voucher is less than the "total available" for the voucher.

- A cart is invalid if it contains a voucher that has been overused

## Are products available?

- Availability is determined by the number of items we want to add to the cart: items_to_add

- If items_to_add + count(Product in their active and paid Carts) > "Limit per user" for the Product, the Product is "unavailable".

- If the Product belongs to an exhausted Ceiling, the Product is "unavailable".

- Otherwise, the product is available

## Displaying Products:

- If there is at least one mandatory EnablingCondition attached to the Product, display it only if all EnablingConditions are met

- If there is at least one EnablingCondition attached to the Product, display it only if at least one EnablingCondition is met

- If there are zero EnablingConditions attached to the Product, display it

- If the product is not available for items_to_add=0, mark it as "unavailable"

- If the Product is displayed and available, its price is the price for the Product, minus the greatest Discount available to this Cart and Product

- The product is displayed per the rendering characteristics of the Category it belongs to

## Displaying Categories

- If the Category contains only "unavailable" Products, mark it as "unavailable"

- If the Category contains no displayed Products, do not display the Category

- If the Category contains at least one EnablingCondition, display it only if at least one EnablingCondition is met

- If the Category contains no EnablingConditions, display it

## Exhausting Ceilings

- Exhaustion is determined by the number of items we want to add to the cart: items_to_add

- A ceiling is exhausted if:

 - Its start date has not yet been reached

 - Its end date has been exceeded

 - items_to_add + sum(paid and reserved Items for each Product in the ceiling) > Total available

## Applying Discounts

- Discounts only apply to the current cart

- Discounts can be applied to multiple carts until the user has exhausted the quantity for each product attached to the discount.

- Only one discount discount can be applied to each single item. Discounts are applied as follows:

 - All non-exhausted discounts for the product or its category are ordered by value

 - The highest discount is applied for the lower of the quantity of the product in the cart, or the remaining quantity from this discount

 - If the quantity remaining is non-zero, apply the next available discount

- Individual discount objects should not contain more than one DiscountForProduct for the same product

- Individual discount objects should not contain more than one DiscountForCategory for the same category

- Individual discount objects should not contain a discount for both a product and its category

## Adding Items to the Cart

- Products that are not displayed may not be added to a Cart

- The requested number of items must be available for those items to be added to a Cart

- If a different price applies to a Product when it is added to a cart, add at the new price, and display an alert to the user

- If a discount is used when adding a Product to the cart, add the discount as well

- Adding an item resets the "Time last updated" for the cart

- Each time carts have items added or removed, the revision number is updated

## Generating an invoice

- User can ask to 'check out' the active Cart. Doing so generates an Invoice. The invoice corresponds to a revision number of the cart.

- Checking out the active Cart resets the "Time last updated" for the cart.

- The invoice represents the current state of the cart.

- If the revision number for the cart is different to the cart's revision number for the invoice, the invoice is void.

- The invoice is void if

## Paying an invoice

- A payment can only be attached to an invoice if all of the items in it are available at the time payment is processed

### One-Shot

- Update the "Time last updated" for the cart based on the expected time it takes for a payment to complete

- Verify that all items are available, and if so:

- Proceed to make payment

- Apply payment record from amount received

### Authorization-based approach:

- Capture an authorization on the card

- Verify that all items are available, and if so:

- Apply payment record

- Take payment

# Registration workflow:

## User has not taken a guided registration yet:

User is shown two options:

1. Undertake guided registration ("for current user")

1. Purchase vouchers

## User has not purchased a ticket, and wishes to:

This gives the user a guided registration process.

1. Take list of categories, sorted by display order, and display the next lowest enabled & available category

1. Take user to category page

1. User can click "back" to go to previous screen, or "next" to go the next lowest enabled & available category

Once all categories have been seen:

1. Ask for badge information -- badge information is *not* the same as the invoicee.

1. User is taken to the "user has purchased a ticket" workflow

## User is buying vouchers

TODO: Consider separate workflow for purchasing ticket vouchers.

## User has completed a guided registration or purchased vouchers

1. Show list of products that are pending purchase.

1. Show list of categories + badge information, as well as 'checkout' button if the user has items in their current cart

## Category page

- User can enter a voucher at any time

- User is shown the list of products that have been paid for

- User has the option to add/remove products that are in the current cart

## Checkout

1. Ask for invoicing details (pre-fill from previous invoice?)

1. Ask for payment

# User Models

- Profile:

 - User

 - Has done guided registration?

 - Badge

 -

## Transaction Models

- Cart:

 - User

 - {Items}

 - {Voucher}

 - {DiscountItems}

 - Time last updated

 - Revision Number

 - Active?

- Item

 - Product

 - Quantity

- DiscountItem

 - Product

 - Discount

 - Quantity

- Invoice:

 - Invoice number

 - User

 - Cart

 - Cart Revision

 - {Line Items}

 - (Invoice Details)

 - {Payments}

 - Voided?

- LineItem

 - Description

 - Quantity

 - Price

- Payment

 - Time

 - Amount

 - Reference

## Inventory Model

- Product:

 - Name

 - Description

 - Category

 - Price

 - Limit per user

 - Reservation duration

 - Display order

 - {Ceilings}

- Voucher

 - Description

 - Code

 - Total available

- Category?

 - Name

 - Description

 - Display Order

 - Rendering Style

## Product Modifiers

- Discount:

 - Description

 - {DiscountForProduct}

 - {DiscountForCategory}

 - Discount Types:

    - TimeOrStockLimitDiscount:

     * A discount that is available for a limited amount of time, e.g. Early Bird sales *

     - Start date

     - End date

     - Total available

    - VoucherDiscount:

     * A discount that is available to a specific voucher *

     - Voucher

    - RoleDiscount

     * A discount that is available to a specific role *

     - Role

    - IncludedProductDiscount:

     * A discount that is available because another product has been purchased *

     - {Parent Product}

- DiscountForProduct

 - Product

 - Amount

 - Percentage

 - Quantity

- DiscountForCategory

 - Category

 - Percentage

 - Quantity

- EnablingCondition:

 - Description

 - Mandatory?

 - {Products}

 - {Categories}

 - EnablingCondition Types:

   - ProductEnablingCondition:

    * Enabling because the user has purchased a specific product *

    - {Products that enable}

   - CategoryEnablingCondition:

    * Enabling because the user has purchased a product in a specific category *

    - {Categories that enable}

   - VoucherEnablingCondition:

    * Enabling because the user has entered a voucher code *

     - Voucher

   - RoleEnablingCondition:

     * Enabling because the user has a specific role *

     - Role

   - TimeOrStockLimitEnablingCondition:

    * Enabling because a time condition has been met, or a number of items underneath it have not been sold *

    - Start date

    - End date

    - Total available

__version__ = "0.1a1"

default_app_config = "registrasion.apps.RegistrasionConfig"

from django.contrib import admin

from django.utils.translation import ugettext_lazy as _

import nested_admin

from registrasion import models as rego

# Inventory admin

class ProductInline(admin.TabularInline):

    model = rego.Product

@admin.register(rego.Category)

class CategoryAdmin(admin.ModelAdmin):

    model = rego.Category

    verbose_name_plural = _("Categories")

    inlines = [

        ProductInline,

    ]

admin.site.register(rego.Product)

# Discounts

class DiscountForProductInline(admin.TabularInline):

    model = rego.DiscountForProduct

    verbose_name = _("Product included in discount")

    verbose_name_plural = _("Products included in discount")

class DiscountForCategoryInline(admin.TabularInline):

    model = rego.DiscountForCategory

    verbose_name = _("Category included in discount")

    verbose_name_plural = _("Categories included in discount")

@admin.register(

    rego.TimeOrStockLimitDiscount,

    rego.IncludedProductDiscount,

)

class DiscountAdmin(admin.ModelAdmin):

    inlines = [

        DiscountForProductInline,

        DiscountForCategoryInline,

    ]

# Vouchers

class VoucherDiscountInline(nested_admin.NestedStackedInline):

    model = rego.VoucherDiscount

    verbose_name = _("Discount")

    # TODO work out why we're allowed to add more than one?

    max_num = 1

    extra = 1

    inlines = [

        DiscountForProductInline,

        DiscountForCategoryInline,

    ]

class VoucherEnablingConditionInline(nested_admin.NestedStackedInline):

    model = rego.VoucherEnablingCondition

    verbose_name = _("Product and category enabled by voucher")

    verbose_name_plural = _("Products and categories enabled by voucher")

    # TODO work out why we're allowed to add more than one?

    max_num = 1

    extra = 1

@admin.register(rego.Voucher)

class VoucherAdmin(nested_admin.NestedAdmin):

    model = rego.Voucher

    inlines = [

        VoucherDiscountInline,

        VoucherEnablingConditionInline,

    ]

from __future__ import unicode_literals

from django.apps import AppConfig

class RegistrasionConfig(AppConfig):

    name = "registrasion"

    label = "registrasion"

    verbose_name = "Registrasion"

import datetime

import itertools

from django.core.exceptions import ObjectDoesNotExist

from django.core.exceptions import ValidationError

from django.db.models import Avg, Min, Max, Sum

from django.utils import timezone

from registrasion import models as rego

from conditions import ConditionController

from controllers import ProductController

class CartController(object):

    def __init__(self, cart):

        self.cart = cart

    @staticmethod

    def for_user(user):

        ''' Returns the user's current cart, or creates a new cart

        if there isn't one ready yet. '''

        try:

            existing = rego.Cart.objects.get(user=user, active=True)

        except ObjectDoesNotExist:

            existing = rego.Cart.objects.create(

                user=user,

                time_last_updated=timezone.now(),

                reservation_duration=datetime.timedelta(),

                 )

            existing.save()

        return CartController(existing)

    def extend_reservation(self):

        ''' Updates the cart's time last updated value, which is used to

        determine whether the cart has reserved the items and discounts it

        holds. '''

        reservations = [datetime.timedelta()]

        # If we have vouchers, we're entitled to an hour at minimum.

        if len(self.cart.vouchers.all()) >= 1:

            reservations.append(rego.Voucher.RESERVATION_DURATION)

        # Else, it's the maximum of the included products

        items = rego.ProductItem.objects.filter(cart=self.cart)

        agg = items.aggregate(Max("product__reservation_duration"))

        product_max = agg["product__reservation_duration__max"]

        if product_max is not None:

            reservations.append(product_max)

        self.cart.time_last_updated = timezone.now()

        self.cart.reservation_duration = max(reservations)

    def add_to_cart(self, product, quantity):

        ''' Adds _quantity_ of the given _product_ to the cart. Raises

        ValidationError if constraints are violated.'''

        prod = ProductController(product)

        # TODO: Check enabling conditions for product for user

        if not prod.can_add_with_enabling_conditions(self.cart.user, quantity):

            raise ValidationError("Not enough of that product left (ec)")

        if not prod.user_can_add_within_limit(self.cart.user, quantity):

            raise ValidationError("Not enough of that product left (user)")

        try:

            # Try to update an existing item within this cart if possible.

            product_item = rego.ProductItem.objects.get(

                cart=self.cart,

                product=product)

            product_item.quantity += quantity

        except ObjectDoesNotExist:

            product_item = rego.ProductItem.objects.create(

                cart=self.cart,

                product=product,

                quantity=quantity,

            )

        product_item.save()

        self.recalculate_discounts()

        self.extend_reservation()

        self.cart.revision += 1

        self.cart.save()

    def apply_voucher(self, voucher):

        ''' Applies the given voucher to this cart. '''

        # TODO: is it valid for a cart to re-add a voucher that they have?

        # Is voucher exhausted?

        active_carts = rego.Cart.reserved_carts()

        carts_with_voucher = active_carts.filter(vouchers=voucher)

        if len(carts_with_voucher) >= voucher.limit:

            raise ValidationError("This voucher is no longer available")

        # If successful...

        self.cart.vouchers.add(voucher)

        self.extend_reservation()

        self.cart.revision += 1

        self.cart.save()

    def validate_cart(self):

        ''' Determines whether the status of the current cart is valid;

        this is normally called before generating or paying an invoice '''

        is_reserved = self.cart in rego.Cart.reserved_carts()

        # TODO: validate vouchers

        items = rego.ProductItem.objects.filter(cart=self.cart)

        for item in items:

            # per-user limits are tested at add time, and are unliklely to change

            prod = ProductController(item.product)

            # If the cart is not reserved, we need to see if we can re-reserve

            quantity = 0 if is_reserved else item.quantity

            if not prod.can_add_with_enabling_conditions(self.cart.user, quantity):

                raise ValidationError("Products are no longer available")

        # Validate the discounts

        discount_items = rego.DiscountItem.objects.filter(cart=self.cart)

        seen_discounts = set()

        for discount_item in discount_items:

            discount = discount_item.discount

            if discount in seen_discounts:

                continue

            seen_discounts.add(discount)

            real_discount = rego.DiscountBase.objects.get_subclass(pk=discount.pk)

            cond = ConditionController.for_condition(real_discount)

            quantity = 0 if is_reserved else discount_item.quantity

            if not cond.is_met(self.cart.user, quantity):

                raise ValidationError("Discounts are no longer available")

    def recalculate_discounts(self):

        ''' Calculates all of the discounts available for this product.

        NB should be transactional, and it's terribly inefficient.

        '''

        # Delete the existing entries.

        rego.DiscountItem.objects.filter(cart=self.cart).delete()

        for item in self.cart.productitem_set.all():

            self._add_discount(item.product, item.quantity)

    def _add_discount(self, product, quantity):

        ''' Calculates the best available discounts for this product.

        NB this will be super-inefficient in aggregate because discounts will be

        re-tested for each product. We should work on that.'''

        prod = ProductController(product)

        discounts = prod.available_discounts(self.cart.user)

        discounts.sort(key=lambda discount: discount.value)

        for discount in reversed(discounts):

            if quantity == 0:

                break

            # Get the count of past uses of this discount condition

            # as this affects the total amount we're allowed to use now.

            past_uses = rego.DiscountItem.objects.filter(

                cart__active=False,

                discount=discount.discount,

                product=product,

            )

            agg = past_uses.aggregate(Sum("quantity"))

            past_uses = agg["quantity__sum"]

            if past_uses is None:

                past_uses = 0

            if past_uses == discount.condition.quantity:

                continue

            # Get a provisional instance for this DiscountItem

            # with the quantity set to as much as we have in the cart

            discount_item = rego.DiscountItem.objects.create(

                product=product,

                cart=self.cart,

                discount=discount.discount,

                quantity=quantity,

            )

            # Truncate the quantity for this DiscountItem if we exceed quantity

            ours = discount_item.quantity

            allowed = discount.condition.quantity - past_uses

            if ours > allowed:

                discount_item.quantity = allowed

                # Update the remaining quantity.

                quantity = ours - allowed

            else:

                quantity = 0

            discount_item.save()

from django.db.models import F, Q

from django.db.models import Sum

from django.utils import timezone

from registrasion import models as rego

class ConditionController(object):

    ''' Base class for testing conditions that activate EnablingCondition

    or Discount objects. '''

    def __init__(self):

        pass

    @staticmethod

    def for_condition(condition):

        CONTROLLERS = {

            rego.CategoryEnablingCondition : CategoryConditionController,

            rego.IncludedProductDiscount : ProductConditionController,

            rego.ProductEnablingCondition : ProductConditionController,

            rego.TimeOrStockLimitDiscount :

                TimeOrStockLimitConditionController,

            rego.TimeOrStockLimitEnablingCondition :

                TimeOrStockLimitConditionController,

            rego.VoucherDiscount : VoucherConditionController,

            rego.VoucherEnablingCondition : VoucherConditionController,

        }

        try:

            return CONTROLLERS[type(condition)](condition)

        except KeyError:

            return ConditionController()

    def is_met(self, user, quantity):

        return True

class CategoryConditionController(ConditionController):

    def __init__(self, condition):

        self.condition = condition

    def is_met(self, user, quantity):

        ''' returns True if the user has a product from a category that invokes

        this condition in one of their carts '''

        carts = rego.Cart.objects.filter(user=user)

        enabling_products = rego.Product.objects.filter(

            category=self.condition.enabling_category)

        products = rego.ProductItem.objects.filter(cart=carts,

            product=enabling_products)

        return len(products) > 0

class ProductConditionController(ConditionController):

    ''' Condition tests for ProductEnablingCondition and

    IncludedProductDiscount. '''

    def __init__(self, condition):

        self.condition = condition

    def is_met(self, user, quantity):

        ''' returns True if the user has a product that invokes this

        condition in one of their carts '''

        carts = rego.Cart.objects.filter(user=user)

        products = rego.ProductItem.objects.filter(cart=carts,

            product=self.condition.enabling_products.all())

        return len(products) > 0

class TimeOrStockLimitConditionController(ConditionController):

    ''' Condition tests for TimeOrStockLimit EnablingCondition and

    Discount.'''

    def __init__(self, ceiling):

        self.ceiling = ceiling

    def is_met(self, user, quantity):

        ''' returns True if adding _quantity_ of _product_ will not vioilate

        this ceiling. '''

        # Test date range

        if not self.test_date_range():

            return False

        # Test limits

        if not self.test_limits(quantity):

            return False

        # All limits have been met

        return True

    def test_date_range(self):

        now = timezone.now()

        if self.ceiling.start_time is not None:

            if now < self.ceiling.start_time:

                return False

        if self.ceiling.end_time is not None:

            if now > self.ceiling.end_time:

                return False

        return True

    def _products(self):

        ''' Abstracts away the product list, becuase enabling conditions

        list products differently to discounts. '''

        if isinstance(self.ceiling, rego.TimeOrStockLimitEnablingCondition):

            category_products = rego.Product.objects.filter(

                category=self.ceiling.categories.all()

            )

            return self.ceiling.products.all() | category_products

        else:

            categories = rego.Category.objects.filter(

                discountforcategory__discount=self.ceiling

            )

            return rego.Product.objects.filter(

                Q(discountforproduct__discount=self.ceiling) |

                Q(category=categories.all())

            )

    def test_limits(self, quantity):

        if self.ceiling.limit is None:

            return True

        reserved_carts = rego.Cart.reserved_carts()

        product_items = rego.ProductItem.objects.filter(

            product=self._products().all()

        )

        product_items = product_items.filter(cart=reserved_carts)

        agg = product_items.aggregate(Sum("quantity"))

        count = agg["quantity__sum"]

        if count is None:

            count = 0

        if count + quantity > self.ceiling.limit:

            return False

        return True

class VoucherConditionController(ConditionController):

    ''' Condition test for VoucherEnablingCondition and VoucherDiscount.'''

    def __init__(self, condition):

        self.condition = condition

    def is_met(self, user, quantity):

        ''' returns True if the user has the given voucher attached. '''

        carts = rego.Cart.objects.filter(user=user,

            vouchers=self.condition.voucher)

        return len(carts) > 0

import itertools

from collections import namedtuple

from django.db.models import F, Q

from registrasion import models as rego

from conditions import ConditionController

DiscountEnabler = namedtuple("DiscountEnabler", ("discount", "condition", "value"))

class ProductController(object):

    def __init__(self, product):

        self.product = product

    def user_can_add_within_limit(self, user, quantity):

        ''' Return true if the user is able to add _quantity_ to their count of

        this Product without exceeding _limit_per_user_.'''

        carts = rego.Cart.objects.filter(user=user)

        items = rego.ProductItem.objects.filter(product=self.product, cart=carts)

        count = 0

        for item in items:

            count += item.quantity

        if quantity + count > self.product.limit_per_user:

            return False

        else:

            return True

    def can_add_with_enabling_conditions(self, user, quantity):

        ''' Returns true if the user is able to add _quantity_ to their count

        of this Product without exceeding the ceilings the product is attached

        to. '''

        conditions = rego.EnablingConditionBase.objects.filter(

            Q(products=self.product) | Q(categories=self.product.category)

        ).select_subclasses()

        mandatory_violated = False

        non_mandatory_met = False

        for condition in conditions:

            cond = ConditionController.for_condition(condition)

            met = cond.is_met(user, quantity)

            if condition.mandatory and not met:

                mandatory_violated = True

                break

            if met:

                non_mandatory_met = True

        if mandatory_violated:

            # All mandatory conditions must be met

            return False

        if len(conditions) > 0 and not non_mandatory_met:

            # If there's any non-mandatory conditions, one must be met

            return False

        return True

    def get_enabler(self, condition):

        if condition.percentage is not None:

            value = condition.percentage * self.product.price

        else:

            value = condition.price

        return DiscountEnabler(

            discount=condition.discount,

            condition=condition,

            value=value