Approval

.github/CODEOWNERS

@@ -5,6 +5,9 @@
 /InvenTree/plugin/      @SchrodingersGat @matmair
 /InvenTree/plugins/     @SchrodingersGat @matmair
 
+# specialised modules
+/InvenTree/approvals    @matmair
+
 # Installer functions
 .pkgr.yml               @matmair
 Procfile                @matmair

InvenTree/InvenTree/settings.py

@@ -208,6 +208,7 @@
     'users.apps.UsersConfig',
     'web',
     'generic',
+    'approval.apps.ApprovalConfig',
     'InvenTree.apps.InvenTreeConfig',       # InvenTree app runs last
 
     # Core django modules

InvenTree/InvenTree/status_codes.py

@@ -10,6 +10,8 @@ class PurchaseOrderStatus(StatusCode):
 
     # Order status codes
     PENDING = 10, _("Pending"), 'secondary'     # Order is pending (not yet placed)
+    PENDING_PLACING = 15, _("Pending placing"), 'secondary'  # Order is pending an action for being placed
+    PENDING_APPROVAL = 16, _("Pending approval"), 'secondary'  # Order is pending approval
     PLACED = 20, _("Placed"), 'primary'         # Order has been placed with supplier
     COMPLETE = 30, _("Complete"), 'success'     # Order has been completed
     CANCELLED = 40, _("Cancelled"), 'danger'    # Order was cancelled
@@ -23,6 +25,7 @@ class PurchaseOrderStatusGroups:
     # Open orders
     OPEN = [
         PurchaseOrderStatus.PENDING.value,
+        PurchaseOrderStatus.PENDING_PLACING.value,
         PurchaseOrderStatus.PLACED.value,
     ]
 

InvenTree/InvenTree/urls.py

@@ -16,6 +16,7 @@
 from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView
 from sesame.views import LoginView
 
+from approval.api import approval_api_urls
 from build.api import build_api_urls
 from build.urls import build_urls
 from common.api import admin_api_urls, common_api_urls, settings_api_urls
@@ -66,6 +67,7 @@
     re_path(r'^report/', include(report_api_urls)),
     re_path(r'^user/', include(user_urls)),
     re_path(r'^admin/', include(admin_api_urls)),
+    re_path(r'^approval/', include(approval_api_urls)),
 
     # Plugin endpoints
     path('', include(plugin_api_urls)),

InvenTree/approval/__init__.py

@@ -0,0 +1 @@
+"""Approvals can be used to implement apprival or voting processes based on sets of rules."""

InvenTree/approval/admin.py

@@ -0,0 +1,45 @@
+"""Admin class definitions for approval app"""
+
+from django.contrib import admin
+
+from .models import Approval, ApprovalDecision
+
+
+class ApprovalDecisionInline(admin.TabularInline):
+    """Inline for ApprovalDecision."""
+
+    model = ApprovalDecision
+
+
+@admin.register(Approval)
+class ApprovalAdmin(admin.ModelAdmin):
+    """Admin class for Approval model."""
+
+    resource_class = ApprovalDecisionInline
+
+    list_display = ('name', 'description', 'reference', 'finalised', 'status')
+
+    list_filter = [
+        'status',
+        'finalised',
+        'created_by',
+        'creation_date',
+        'modified_by',
+        'modified_date',
+        'finalised_by',
+        'finalised_date',
+    ]
+
+    search_fields = [
+        'name',
+        'description',
+        'reference',
+        'created_by',
+        'creation_date',
+        'modified_by',
+        'modified_date',
+        'finalised_by',
+        'finalised_date',
+    ]
+
+    inlines = [ApprovalDecisionInline,]

InvenTree/approval/api.py

@@ -0,0 +1,251 @@
+"""API views for the Approval app."""
+from django.contrib.contenttypes.models import ContentType
+from django.urls import include, path, re_path
+
+from rest_framework import serializers
+from rest_framework.generics import get_object_or_404
+
+from InvenTree.api import MetadataView
+from InvenTree.helpers import str2bool
+from InvenTree.mixins import CreateAPI, ListCreateAPI, RetrieveUpdateDestroyAPI
+from InvenTree.serializers import InvenTreeModelSerializer, UserSerializer
+from users.serializers import OwnerSerializer
+
+from .models import Approval, ApprovalDecision
+
+
+class UserDetailApiMixin:
+    """Mixin to add extra context information regarding user/owner details to endpoint serializers."""
+
+    def get_serializer(self, *args, **kwargs):
+        """Add extra context information to the endpoint serializer."""
+        try:
+            user_detail = str2bool(self.request.GET.get('user_detail', None))
+        except AttributeError:
+            user_detail = None
+
+        kwargs['user_detail'] = user_detail
+        return super().get_serializer(*args, **kwargs)
+
+    def get_object(self):
+        """Get the object to be viewed."""
+        # Use default behaviour if no type is specified
+        if self.kwargs.get('type', None) is None:
+            return super().get_object()
+
+        # Alternatively, use the generic relationship to get the object
+        queryset = self.filter_queryset(self.get_queryset())
+        obj = get_object_or_404(queryset, **{'content_type__model': self.kwargs['type'], 'object_id': self.kwargs['pk']})
+        self.check_object_permissions(self.request, obj)
+        return obj
+
+
+class UserDetailSerializerMixin:
+    """Mixin to determine if extra serializer fields are required."""
+
+    def __init__(self, *args, **kwargs):
+        """Determine if extra serializer fields are required"""
+        user_detail = kwargs.pop('user_detail', False)
+
+        super().__init__(*args, **kwargs)
+
+        if user_detail is not True:
+            for field in self.Meta.user_detail_fields:
+                self.fields.pop(field)
+
+
+class TaggedObjectRelatedField(serializers.RelatedField):
+    """A custom field to use for the `tagged_object` generic relationship."""
+
+    def to_representation(self, value):
+        """Serialize tagged objects to a simple textual representation."""
+        if hasattr(value, 'get_api_url'):
+            return f'{value.get_api_url()}{value.id}/'
+        if hasattr(value, 'get_absolute_url'):
+            return value.get_absolute_url()
+        else:
+            return value.id
+
+
+class ApprovalDecisionSerializer(UserDetailSerializerMixin, InvenTreeModelSerializer):
+    """Serializes an ApprovalDecision object"""
+
+    user_detail = UserSerializer(source='user', read_only=True, many=False)
+
+    class Meta:
+        """Meta data for ApprovalDecisionSerializer"""
+        model = ApprovalDecision
+        exclude = [
+            'metadata',
+        ]
+        user_detail_fields = ['user_detail',]
+
+    def is_valid(self, *, raise_exception=False):
+        """Insert user to save request."""
+        request = self.context['request']
+        self.initial_data['user'] = request.user.pk
+        return super().is_valid(raise_exception=raise_exception)
+
+
+class ApprovalSerializer(UserDetailSerializerMixin, InvenTreeModelSerializer):
+    """Serializes an Approval object"""
+
+    status_text = serializers.CharField(source='get_status_display', read_only=True)
+    content_object = TaggedObjectRelatedField(read_only=True)
+    model = serializers.CharField(required=False, write_only=True)
+    decisions = ApprovalDecisionSerializer(many=True, read_only=True, user_detail=True)
+    creation_date = serializers.DateTimeField(format='iso-8601', required=False)
+    created_by_detail = UserSerializer(source='created_by', read_only=True, many=False)
+    modified_date = serializers.DateTimeField(format='iso-8601', required=False)
+    modified_by_detail = UserSerializer(source='modified_by', read_only=True, many=False)
+    finalised_date = serializers.DateTimeField(format='iso-8601', required=False)
+    finalised_by_detail = UserSerializer(source='finalised_by', read_only=True, many=False)
+    responsible_detail = OwnerSerializer(source='responsible', read_only=True)
+    owner_detail = OwnerSerializer(source='owner', read_only=True)
+
+    class Meta:
+        """Meta data for ApprovalSerializer"""
+        model = Approval
+        exclude = [
+            'reference_int',
+            'metadata',
+            'data',
+            # 'object_id',
+            # 'content_type',
+        ]
+
+        read_only_fields = [
+            'creation_date',
+            'finalised_date',
+            'modified_date',
+        ]
+
+        user_detail_fields = [
+            'created_by_detail',
+            'modified_by_detail',
+            'finalised_by_detail',
+            'responsible_detail',
+            'owner_detail',
+        ]
+
+    def is_valid(self, *, raise_exception=False):
+        """User optional field 'model' to determine content_type."""
+        if 'model' in self.initial_data:
+            model = self.initial_data.pop('model')
+            mdl_splt = model.split('.')
+            content_type = ContentType.objects.get(app_label=mdl_splt[0], model=mdl_splt[1])
+            self.initial_data['content_type'] = content_type.pk
+        return super().is_valid(raise_exception=raise_exception)
+
+
+class ApprovalList(UserDetailApiMixin, ListCreateAPI):
+    """API endpoint for listing all Approval objects"""
+
+    queryset = Approval.objects.all()
+    serializer_class = ApprovalSerializer
+    filterset_fields = [
+        "owner",
+        "status",
+        "content_type",
+        "object_id",
+    ]
+    search_fields = [
+        "name",
+        "description",
+        "reference",
+    ]
+    ordering_field_aliases = {
+        'reference': ['reference_int', 'reference'],
+    }
+    ordering_fields = [
+        "name",
+        "status",
+        "finalised_date",
+        "modified_date",
+        "created_date",
+        'reference',
+    ]
+    ordering = '-reference'
+
+    def clean_data(self, data: dict) -> dict:
+        """Custom clean_data method to add current user."""
+        data = super().clean_data(data)
+        data['created_by'] = self.request.user.pk
+        return data
+
+
+class ApprovalDetail(UserDetailApiMixin, RetrieveUpdateDestroyAPI):
+    """API endpoint for detail view of an Approval object"""
+
+    queryset = Approval.objects.all()
+    serializer_class = ApprovalSerializer
+
+
+class ApprovalDecisionList(UserDetailApiMixin, ListCreateAPI):
+    """API endpoint for listing all ApprovalDecision objects"""
+
+    queryset = ApprovalDecision.objects.all()
+    serializer_class = ApprovalDecisionSerializer
+    filterset_fields = [
+        "approval",
+        "user",
+        "status",
+    ]
+    search_fields = [
+        "comment",
+    ]
+    ordering_fields = [
+        "approval",
+        "user",
+        "status",
+        "date",
+    ]
+
+
+class ApprovalDecisionDetail(UserDetailApiMixin, RetrieveUpdateDestroyAPI):
+    """API endpoint for detail view of an ApprovalDecision object"""
+
+    queryset = ApprovalDecision.objects.all()
+    serializer_class = ApprovalDecisionSerializer
+
+
+class ApprovalApproveSerializer(InvenTreeModelSerializer):
+    """Serializes an ApprovalDecision object"""
+
+    class Meta:
+        """Meta data for ApprovalDecisionSerializer"""
+        model = ApprovalDecision
+        exclude = ['metadata',]
+
+    def is_valid(self, *, raise_exception=False):
+        """Insert data to save request."""
+        request = self.context['request']
+        self.initial_data['user'] = request.user.pk
+        self.initial_data['approval'] = request.parser_context['kwargs'].get('pk', None)
+        self.initial_data['decision'] = True
+        return super().is_valid(raise_exception=raise_exception)
+
+
+class ApproveView(CreateAPI):
+    """API endpoint to approve approval."""
+
+    queryset = ApprovalDecision.objects.all()
+    serializer_class = ApprovalApproveSerializer
+
+
+detail_api = [
+    re_path(r"^decision/", include([
+        re_path(r"^$", ApprovalDecisionList.as_view(), name="api-approval-decision-list",),
+        re_path(r"^(?P<pk>\d+)/", ApprovalDecisionDetail.as_view(), name="api-approval-decision-detail",),
+    ])),
+    re_path('approve/', ApproveView.as_view(), name='api-approval-approve'),
+    re_path(r'^metadata/', MetadataView.as_view(), {'model': Approval}, name='api-approval-metadata'),
+    re_path(r'^.*$', ApprovalDetail.as_view(), name='api-approval-detail'),
+]
+
+
+approval_api_urls = [
+    path(r'<str:type>:<int:pk>/', include(detail_api)),
+    path(r'<int:pk>/', include(detail_api)),
+    re_path(r'^.*$', ApprovalList.as_view(), name='api-approval-list'),
+]

InvenTree/approval/apps.py

@@ -0,0 +1,18 @@
+"""AppConfig for approval app."""
+
+from django.apps import AppConfig
+
+
+class ApprovalConfig(AppConfig):
+    """AppConfig for approval app."""
+    name = 'approval'
+
+    def ready(self):
+        """Run setup step when app is ready."""
+        self.collect_notification_methods()
+
+    def collect_notification_methods(self):
+        """Collect all rule definitions."""
+        from approval.rules import registry
+
+        registry.collect()