Purchase order approvals and "ready" state

src/backend/InvenTree/InvenTree/api_version.py

@@ -1,12 +1,26 @@
 """InvenTree API version information."""
 
 # InvenTree API version
-INVENTREE_API_VERSION = 201
+INVENTREE_API_VERSION = 202
 
 """Increment this API version number whenever there is a significant change to the API that any clients need to know about."""
 
 INVENTREE_API_TEXT = """
 
+v202 - 2024-05-23 : https://github.com/inventree/InvenTree/pull/6989
+    - Adds new API endpoints for PurchaseOrder state transitions
+        - Request Approval
+        - User allowed to Approve
+        - Reject order
+        - Order Ready to issue
+        - User allowed to Issue
+        - Recall order to Pending
+    - Adds fields to PurchaseOrder PAI calls:
+        - reject_reason
+        - created_by
+        - approved_by
+        - placed_by
+
 v201 - 2024-05-21 : https://github.com/inventree/InvenTree/pull/7074
     - Major refactor of the report template / report printing interface
     - This is a *breaking change* to the report template API

src/backend/InvenTree/InvenTree/helpers_model.py

@@ -319,6 +319,7 @@ def notify_users(
     sender,
     content: NotificationBody = InvenTreeNotificationBodies.NewOrder,
     exclude=None,
+    delta=None,
 ):
     """Notify all passed users or groups.
 
@@ -354,11 +355,16 @@ def notify_users(
     if content.template:
         context['template']['html'] = content.template.format(**content_context)
 
+    excluded = exclude
+    if not isinstance(exclude, list):
+        excluded = [exclude]
+
     # Create notification
     trigger_notification(
         instance,
         content.slug.format(**content_context),
         targets=users,
-        target_exclude=[exclude],
+        target_exclude=excluded,
         context=context,
+        delta=delta,
     )

src/backend/InvenTree/InvenTree/status_codes.py

@@ -15,13 +15,20 @@ class PurchaseOrderStatus(StatusCode):
     CANCELLED = 40, _('Cancelled'), 'danger'  # Order was cancelled
     LOST = 50, _('Lost'), 'warning'  # Order was lost
     RETURNED = 60, _('Returned'), 'warning'  # Order was returned
+    IN_APPROVAL = 70, _('Approval needed'), 'warning'  # Order waiting for approval
+    READY = 80, _('Ready'), 'primary'  # Order is ready to be issued
 
 
 class PurchaseOrderStatusGroups:
     """Groups for PurchaseOrderStatus codes."""
 
     # Open orders
-    OPEN = [PurchaseOrderStatus.PENDING.value, PurchaseOrderStatus.PLACED.value]
+    OPEN = [
+        PurchaseOrderStatus.PENDING.value,
+        PurchaseOrderStatus.PLACED.value,
+        PurchaseOrderStatus.IN_APPROVAL.value,
+        PurchaseOrderStatus.READY.value,
+    ]
 
     # Failed orders
     FAILED = [

src/backend/InvenTree/InvenTree/templatetags/inventree_extras.py

@@ -663,3 +663,25 @@
             pass
 
     return url
+
+
+@register.simple_tag()
+def approval_allowed(user, order):
+    """Check that the given user is allowed to approve the order."""
+    return order.approval_allowed(user)
+
+
+@register.simple_tag()
+def can_issue_order(user):
+    """Check if purchasing is limited to a group.
+
+    Checks if the user is part of the purchaser group
+    """
+    purchaser_group = common.models.InvenTreeSetting.get_setting(
+        'PURCHASE_ORDER_PURCHASER_GROUP'
+    )
+
+    if purchaser_group:
+        return user.groups.filter(name=purchaser_group).exists()
+    else:
+        return True

src/backend/InvenTree/common/models.py

@@ -55,6 +55,13 @@
 logger = logging.getLogger('inventree')
 
 
+def all_groups():
+    """Make a choice set of all groups, including an empty string for 'no group'."""
+    groups = [(x.name, x.name) for x in Group.objects.all()]
+    groups.insert(0, ('', '(No group)'))
+    return groups
+
+
 class MetaMixin(models.Model):
     """A base class for InvenTree models to include shared meta fields.
 
@@ -2079,6 +2086,32 @@ def save(self, *args, **kwargs):
             'default': False,
             'validator': bool,
         },
+        'ENABLE_PURCHASE_ORDER_READY_STATUS': {
+            'name': _('Enable Ready Status'),
+            'description': _(
+                'Enable a "Ready" state, indicating an order is ready for issuing. This setting is implicitly active when approvals are active.'
+            ),
+            'default': False,
+            'validator': bool,
+        },
+        'PURCHASE_ORDER_PURCHASER_GROUP': {
+            'name': _('Purchaser Group'),
+            'description': _(
+                'Limit issuing of orders to a purchaser group. If set, orders can only be issued by members of this group.'
+            ),
+            'choices': all_groups,
+        },
+        'ENABLE_PURCHASE_ORDER_APPROVAL': {
+            'name': _('Purchase Order Approvals'),
+            'description': _('Add a required approval step to purchase orders'),
+            'default': False,
+            'validator': bool,
+        },
+        'PURCHASE_ORDER_APPROVE_ALL_GROUP': {
+            'name': _('Master approval group'),
+            'description': _('Set a permission group that can approve ALL orders'),
+            'choices': all_groups,
+        },
     }
 
     typ = 'inventree'
@@ -2926,7 +2959,7 @@ class Meta:
     @classmethod
     def check_recent(cls, key: str, uid: int, delta: timedelta):
         """Test if a particular notification has been sent in the specified time period."""
-        since = InvenTree.helpers.current_date() - delta
+        since = InvenTree.helpers.current_time() - delta
 
         entries = cls.objects.filter(key=key, uid=uid, updated__gte=since)
 

src/backend/InvenTree/common/notifications.py

@@ -340,6 +340,34 @@ class InvenTreeNotificationBodies:
         template='email/return_order_received.html',
     )
 
+    PurchaseOrderApprovalRequested = NotificationBody(
+        name=_('Approval requested'),
+        slug=_('purchase_order.approval_request'),
+        message=_('You have been requested to approve a Purchase Order'),
+        template='email/new_order_assigned.html',
+    )
+
+    PurchaseOrderRejected = NotificationBody(
+        name=_('Purchase order was rejected'),
+        slug=_('purchase_order.approval_rejected'),
+        message=_('Your approval request was rejected'),
+        template='email/new_order_assigned.html',
+    )
+
+    PurchaseOrderApproved = NotificationBody(
+        name=_('Purchase order was approved'),
+        slug=_('purchase_order.approved'),
+        message=_('Your approval request was accepted'),
+        template='email/new_order_assigned.html',
+    )
+
+    PurchaseOrderReady = NotificationBody(
+        name=_('Purchase order is ready to issue'),
+        slug=_('purchase_order.ready_to_issue'),
+        message=_('A Purchase order was just marked ready to issue.'),
+        template='email/new_order_assigned.html',
+    )
+
 
 def trigger_notification(obj, category=None, obj_ref='pk', **kwargs):
     """Send out a notification."""
@@ -350,6 +378,7 @@ def trigger_notification(obj, category=None, obj_ref='pk', **kwargs):
     target_exclude = kwargs.get('target_exclude', None)
     context = kwargs.get('context', {})
     delivery_methods = kwargs.get('delivery_methods', None)
+    override_delta = kwargs.get('delta', None)
 
     # Check if data is importing currently
     if isImportingData():
@@ -369,7 +398,7 @@ def trigger_notification(obj, category=None, obj_ref='pk', **kwargs):
         )
 
     # Check if we have notified recently...
-    delta = timedelta(days=1)
+    delta = override_delta or timedelta(days=1)
 
     if common.models.NotificationEntry.check_recent(category, obj_ref_value, delta):
         logger.info(

src/backend/InvenTree/order/api.py

@@ -29,7 +29,13 @@
 from InvenTree.filters import SEARCH_ORDER_FILTER, SEARCH_ORDER_FILTER_ALIAS
 from InvenTree.helpers import DownloadFile, str2bool
 from InvenTree.helpers_model import construct_absolute_url, get_base_url
-from InvenTree.mixins import CreateAPI, ListAPI, ListCreateAPI, RetrieveUpdateDestroyAPI
+from InvenTree.mixins import (
+    CreateAPI,
+    ListAPI,
+    ListCreateAPI,
+    RetrieveAPI,
+    RetrieveUpdateDestroyAPI,
+)
 from InvenTree.status_codes import (
     PurchaseOrderStatus,
     PurchaseOrderStatusGroups,
@@ -395,6 +401,42 @@ class PurchaseOrderComplete(PurchaseOrderContextMixin, CreateAPI):
     serializer_class = serializers.PurchaseOrderCompleteSerializer
 
 
+class PurchaseOrderRequestApproval(PurchaseOrderContextMixin, CreateAPI):
+    """API endpoint to request approval a PurchaseOrder."""
+
+    serializer_class = serializers.PurchaseOrderRequestApprovalSerializer
+
+
+class PurchaseOrderApprovalAllowed(PurchaseOrderContextMixin, RetrieveAPI):
+    """API endpoint to indicate if a user is allowed to approve a PurchaseOrder."""
+
+    serializer_class = serializers.PurchaseOrderCanApproveSerializer
+
+
+class PurchaseOrderReject(PurchaseOrderContextMixin, CreateAPI):
+    """API endpoint to reject a PurchaseOrder that was requested approval for."""
+
+    serializer_class = serializers.PurchaseOrderRejectSerializer
+
+
+class PurchaseOrderReady(PurchaseOrderContextMixin, CreateAPI):
+    """API endpoint to mark a PurchaseOrder as ready to issue."""
+
+    serializer_class = serializers.PurchaseOrderReadySerializer
+
+
+class PurchaseOrderIssueAllowed(PurchaseOrderContextMixin, RetrieveAPI):
+    """API endpoint to indicate if a user is allowed to issue a PurchaseOrder."""
+
+    serializer_class = serializers.PurchaseOrderCanIssueSerializer
+
+
+class PurchaseOrderPending(PurchaseOrderContextMixin, CreateAPI):
+    """API endpoint to return a PurchaseOrder to Pending."""
+
+    serializer_class = serializers.PurchaseOrderRejectSerializer
+
+
 class PurchaseOrderIssue(PurchaseOrderContextMixin, CreateAPI):
     """API endpoint to 'issue' (place) a PurchaseOrder."""
 
@@ -1617,6 +1659,30 @@ def item_link(self, item):
             path(
                 '<int:pk>/',
                 include([
+                    path(
+                        'can_approve/',
+                        PurchaseOrderApprovalAllowed.as_view(),
+                        name='api-po-approval-allowed',
+                    ),
+                    path(
+                        'request_approval/',
+                        PurchaseOrderRequestApproval.as_view(),
+                        name='api-po-req-approval',
+                    ),
+                    path(
+                        'reject/', PurchaseOrderReject.as_view(), name='api-po-reject'
+                    ),
+                    path('ready/', PurchaseOrderReady.as_view(), name='api-po-ready'),
+                    path(
+                        'can_issue/',
+                        PurchaseOrderIssueAllowed.as_view(),
+                        name='api-po-issue-allowed',
+                    ),
+                    path(
+                        'pending/',
+                        PurchaseOrderPending.as_view(),
+                        name='api-po-pending',
+                    ),
                     path(
                         'cancel/', PurchaseOrderCancel.as_view(), name='api-po-cancel'
                     ),

src/backend/InvenTree/order/fixtures/order.yaml

@@ -66,6 +66,15 @@
     supplier: 2
     status: 10  # Pending
 
+- model: order.purchaseorder
+  pk: 8
+  fields:
+    reference: 'PO-0008'
+    reference_int: 8
+    description: 'PO awaiting approval'
+    supplier: 2
+    status: 70 #In approval
+
 # Add some line items against PO 0001
 
 # 100 x ACME0001 (M2x4 LPHS)

src/backend/InvenTree/order/migrations/0100_purchaseorder_approved_by_and_more.py

@@ -0,0 +1,41 @@
+# Generated by Django 4.2.11 on 2024-04-09 22:10
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('order', '0099_alter_salesorder_status'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='purchaseorder',
+            name='approved_by',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, to=settings.AUTH_USER_MODEL, verbose_name='Approved by'),
+        ),
+        migrations.AddField(
+            model_name='purchaseorder',
+            name='approved_date',
+            field=models.DateField(blank=True, help_text='Date order was approved', null=True, verbose_name='Approve Date'),
+        ),
+        migrations.AddField(
+            model_name='purchaseorder',
+            name='placed_by',
+            field=models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='orders_placed', to=settings.AUTH_USER_MODEL, verbose_name='Placed by'),
+        ),
+        migrations.AddField(
+            model_name='purchaseorder',
+            name='reject_reason',
+            field=models.CharField(blank=True, help_text='The reason for rejecting this order', max_length=128, verbose_name='Reason for rejection'),
+        ),
+        migrations.AlterField(
+            model_name='purchaseorder',
+            name='status',
+            field=models.PositiveIntegerField(choices=[(10, 'Pending'), (20, 'Placed'), (30, 'Complete'), (40, 'Cancelled'), (50, 'Lost'), (60, 'Returned'), (70, 'Approval needed'), (80, 'Ready')], default=10, help_text='Purchase order status'),
+        ),
+    ]