feat: enhance Voucher API with new use and disuse methods

Update key parameter naming, and add observations to voucher fields

Author: joamag

src/budy/controllers/api/voucher.py

@@ -51,10 +51,10 @@ def create(self):
         voucher = voucher.map()
         return voucher
 
-    @appier.route("/api/vouchers/<int:id>", "GET", json=True)
+    @appier.route("/api/vouchers/<int:key>", "GET", json=True)
     @appier.ensure(token="admin")
-    def show(self, id):
-        voucher = budy.Voucher.get_e(id=id, map=True)
+    def show(self, key):
+        voucher = budy.Voucher.get_e(key=key, map=True)
         return voucher
 
     @appier.route("/api/vouchers/value", "POST", json=True)
@@ -64,7 +64,7 @@ def create_value(self):
         key = object.get("key", None)
         amount = object.get("amount", None)
         currency = object.get("currency", None)
-        unlimited = object.get("unlimited", None)
+        unlimited = object.get("unlimited", False)
         key = self.field("key", key)
         amount = self.field("amount", amount, cast=float)
         currency = self.field("currency", currency, cast=str)
@@ -84,3 +84,28 @@ def create_percentage(self):
         voucher = budy.Voucher.create_percentage_s(key, percentage)
         voucher = voucher.map()
         return voucher
+
+    @appier.route("/api/vouchers/<str:key>/use", "POST", json=True)
+    @appier.ensure(token="admin")
+    def use(self, key):
+        object = appier.get_object()
+        amount = object.get("amount", None)
+        currency = object.get("currency", None)
+        justification = object.get("justification", None)
+        save_use = object.get("save_use", True)
+        voucher = budy.Voucher.get_e(key=key)
+        voucher_use = voucher.use_s(
+            amount, currency=currency, justification=justification, save_use=save_use
+        )
+        voucher = voucher.map()
+        if voucher_use:
+            voucher["use"] = voucher_use.map()
+        return voucher
+
+    @appier.route("/api/vouchers/<str:key>/disuse", "POST", json=True)
+    @appier.ensure(token="admin")
+    def disuse(self, key):
+        voucher = budy.Voucher.get_e(key=key)
+        voucher.disuse_s()
+        voucher = voucher.map()
+        return voucher

src/budy/models/__init__.py

@@ -84,5 +84,6 @@
 from .store import Store
 from .subscription import Subscription
 from .voucher import Voucher
+from .voucher_use import VoucherUse
 from .wishlist_line import WishlistLine
 from .wishlist import Wishlist

src/budy/models/voucher.py

@@ -35,21 +35,41 @@
 import appier_extras
 
 from . import base
+from . import voucher_use
 
 
 class Voucher(base.BudyBase):
-    key = appier.field(index=True, safe=True, immutable=True)
+    key = appier.field(
+        index=True,
+        safe=True,
+        immutable=True,
+        observations="""The (secret) key of the voucher, considered to be
+        the unique identifier of the voucher, this is the key that will
+        be used to identify the voucher when it is used""",
+    )
 
     amount = appier.field(
         type=commons.Decimal,
         index=True,
         initial=commons.Decimal(0.0),
         safe=True,
         immutable=True,
+        observations="""The amount of the voucher, meaning the total
+        amount of the voucher that can be used, this is the amount
+        that will be deducted from the order total when the voucher
+        is used, if this value is set to zero the voucher is considered
+        to be a percentage based voucher""",
     )
 
     used_amount = appier.field(
-        type=commons.Decimal, initial=commons.Decimal(0.0), index=True, safe=True
+        type=commons.Decimal,
+        initial=commons.Decimal(0.0),
+        index=True,
+        safe=True,
+        observations="""The amount of the voucher that has been used,
+        meaning that the remaining amount of the voucher that can be
+        used can be calculated by subtracting the used amount from the
+        amount""",
     )
 
     percentage = appier.field(
@@ -58,6 +78,8 @@ class Voucher(base.BudyBase):
         index=True,
         safe=True,
         immutable=True,
+        observations="""The percentage of discount to be applied when
+        using the voucher, meaning the voucher is percentage based""",
     )
 
     currency = appier.field(
@@ -245,13 +267,22 @@ def pre_update(self):
         if self.used and not self.is_used():
             self.used = False
 
-    def use_s(self, amount, currency=None):
+    def use_s(self, amount, currency=None, justification=None, save_use=True):
         amount_l = self.to_local(amount, currency)
         appier.verify(self.is_valid(amount=amount, currency=currency))
         if self.is_value and not self.unlimited:
             self.used_amount += commons.Decimal(amount_l)
         self.usage_count += 1
         self.save()
+        if save_use:
+            voucher_use_ = voucher_use.VoucherUse(
+                voucher=self,
+                amount=amount,
+                currency=currency,
+                justification=justification,
+            )
+            voucher_use_.save()
+            return voucher_use_
 
     def disuse_s(self, amount, currency=None):
         appier.verify(self.usage_count > 0)

src/budy/models/voucher_use.py

@@ -0,0 +1,96 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Hive Budy
+# Copyright (c) 2008-2024 Hive Solutions Lda.
+#
+# This file is part of Hive Budy.
+#
+# Hive Budy is free software: you can redistribute it and/or modify
+# it under the terms of the Apache License as published by the Apache
+# Foundation, either version 2.0 of the License, or (at your option) any
+# later version.
+#
+# Hive Budy is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# Apache License for more details.
+#
+# You should have received a copy of the Apache License along with
+# Hive Budy. If not, see <http://www.apache.org/licenses/>.
+
+__author__ = "João Magalhães <joamag@hive.pt>"
+""" The author(s) of the module """
+
+__copyright__ = "Copyright (c) 2008-2024 Hive Solutions Lda."
+""" The copyright for the module """
+
+__license__ = "Apache License, Version 2.0"
+""" The license for the module """
+
+import appier
+
+from . import base
+
+
+class VoucherUse(base.BudyBase):
+
+    USAGE_TYPE_S = dict(
+        percentage="percentage",
+        value="value",
+    )
+
+    usage_type = appier.field(
+        type=str,
+        safe=True,
+        meta="enum",
+        enum=USAGE_TYPE_S,
+        observations="""Type of usage, either value or percentage""",
+    )
+
+    amount = appier.field(
+        type=float,
+        safe=True,
+        observations="""The amount used from the voucher""",
+    )
+
+    justification = appier.field(
+        type=str,
+        safe=True,
+        observations="""Justification or reason for the usage of the voucher,m
+        may contain external ID references""",
+    )
+
+    voucher = appier.field(
+        type=appier.reference("Voucher", name="id"),
+        safe=True,
+        observations="""Reference to the voucher instance that was used.""",
+    )
+
+    account = appier.field(
+        type=appier.reference("BudyAccount", name="id"),
+        safe=True,
+        observations="""Reference to the account that used the voucher (nullable).""",
+    )
+
+    @classmethod
+    def validate(cls):
+        return super(VoucherUse, cls).validate() + [
+            appier.not_null("voucher"),
+        ]
+
+    @classmethod
+    def list_names(cls):
+        return [
+            "id",
+            "voucher",
+            "account",
+            "amount",
+            "usage_type",
+            "justification",
+            "created",
+        ]
+
+    @classmethod
+    def order_name(cls):
+        return ["id", -1]