inventree-component-shortfall 0.1.0__tar.gz

inventree_component_shortfall-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Oliver Walters <oliver.henry.walters@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

inventree_component_shortfall-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include component_shortfall/static *
+recursive-include component_shortfall/templates *

inventree_component_shortfall-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: inventree-component-shortfall
+Version: 0.1.0
+Summary: Generate component shortfall reports
+Author-email: Oliver Walters <oliver.henry.walters@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SchrodingersGat/inventree-shortfall-report
+Keywords: inventree,plugin
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: InvenTree
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ComponentShortfall
+
+Generate component shortfall reports
+
+## Installation
+
+### InvenTree Plugin Manager
+
+... todo ...
+
+### Command Line 
+
+To install manually via the command line, run the following command:
+
+```bash
+pip install inventree-component-shortfall
+```
+
+## Configuration
+
+... todo ...
+
+## Usage
+
+... todo ...

inventree_component_shortfall-0.1.0/README.md

@@ -0,0 +1,25 @@
+# ComponentShortfall
+
+Generate component shortfall reports
+
+## Installation
+
+### InvenTree Plugin Manager
+
+... todo ...
+
+### Command Line 
+
+To install manually via the command line, run the following command:
+
+```bash
+pip install inventree-component-shortfall
+```
+
+## Configuration
+
+... todo ...
+
+## Usage
+
+... todo ...

inventree_component_shortfall-0.1.0/component_shortfall/__init__.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+
+PLUGIN_VERSION = "0.1.0"

inventree_component_shortfall-0.1.0/component_shortfall/core.py

@@ -0,0 +1,183 @@
+"""Generate component shortfall reports"""
+
+from plugin import InvenTreePlugin
+
+from plugin.mixins import ScheduleMixin, SettingsMixin, UrlsMixin, UserInterfaceMixin
+
+from . import PLUGIN_VERSION
+
+
+class ComponentShortfall(
+    ScheduleMixin, SettingsMixin, UrlsMixin, UserInterfaceMixin, InvenTreePlugin
+):
+    """ComponentShortfall - custom InvenTree plugin."""
+
+    # Plugin metadata
+    TITLE = "Component Shortfall"
+    NAME = "ComponentShortfall"
+    SLUG = "component-shortfall"
+    DESCRIPTION = "Generate component shortfall reports"
+    VERSION = PLUGIN_VERSION
+
+    # Additional project information
+    AUTHOR = "Oliver Walters"
+    WEBSITE = "https://github.com/SchrodingersGat/inventree-shortfall-report"
+    LICENSE = "MIT"
+
+    # Optionally specify supported InvenTree versions
+    # MIN_VERSION = '0.18.0'
+    # MAX_VERSION = '2.0.0'
+
+    SCHEDULED_TASKS = {
+        "shortfall_report": {"func": "periodic_shortfall_report", "schedule": "D"}
+    }
+
+    # Plugin settings (from SettingsMixin)
+    # Ref: https://docs.inventree.org/en/latest/plugins/mixins/settings/
+    SETTINGS = {
+        "HIDE_NO_SHORTFALL": {
+            "name": "Hide No Shortfall",
+            "description": "Hide results for parts which have no shortfall",
+            "default": True,
+            "validator": bool,
+        },
+        "SHORTFALL_REPORT_DAYS": {
+            "name": "Shortfall Report Days",
+            "description": "Number of days between automatic shortfall report generation (set to 0 to disable)",
+            "default": 7,
+            "validator": int,
+        },
+        "SHORTFALL_REPORT_GROUP": {
+            "name": "Shortfall Report Group",
+            "description": "User group to send periodic shortfall reports",
+            "model": "auth.group",
+        },
+    }
+
+    # Custom URL endpoints (from UrlsMixin)
+    # Ref: https://docs.inventree.org/en/latest/plugins/mixins/urls/
+    def setup_urls(self):
+        """Configure custom URL endpoints for this plugin."""
+        from django.urls import path
+        from .views import ShortfallReportView
+
+        return [
+            # Provide path to a simple custom view - replace this with your own views
+            path(
+                "shortfall/",
+                ShortfallReportView.as_view(),
+                name="shortfall-report-view",
+            ),
+        ]
+
+    # User interface elements (from UserInterfaceMixin)
+    # Ref: https://docs.inventree.org/en/latest/plugins/mixins/ui/
+
+    # Custom dashboard items
+    def get_ui_dashboard_items(self, request, context: dict, **kwargs):
+        """Return a list of custom dashboard items to be rendered in the InvenTree user interface."""
+
+        # Example: only display for 'staff' users
+        if not request.user or not request.user.is_staff:
+            return []
+
+        items = []
+
+        items.append({
+            "key": "component-shortfall-dashboard",
+            "title": "Shortfall Report",
+            "description": "Generate a component shortfall report",
+            "icon": "ti:clipboard-check:outline",
+            "source": self.plugin_static_file(
+                "Dashboard.js:renderComponentShortfallDashboardItem"
+            ),
+        })
+
+        return items
+
+    def get_ui_spotlight_actions(self, request, context, **kwargs):
+        """Return a list of custom spotlight actions to be made available."""
+        return [
+            {
+                "key": "shortfall-action",
+                "title": "Shortfall Report",
+                "description": "Generate a component shortfall report",
+                "icon": "ti:clipboard-check:outline",
+                "source": self.plugin_static_file(
+                    "Spotlight.js:ComponentShortfallSpotlightAction"
+                ),
+            }
+        ]
+
+    def periodic_shortfall_report(self):
+        """Scheduled task to periodically generate a shortfall report.
+
+        This task is called daily, but uses the SHORTFALL_REPORT_DAYS setting to determine how often to actually generate the report.
+        """
+
+        import InvenTree.helpers_email
+        import InvenTree.tasks
+        from common.models import DataOutput
+        from .shortfall import calculate_shortfall, format_shortfall_report_html
+        from django.contrib.auth.models import Group
+
+        report_period = int(self.get_setting("SHORTFALL_REPORT_DAYS"))
+
+        if report_period <= 0:
+            return
+
+        if not InvenTree.tasks.check_daily_holdoff(
+            "component_shortfall_report", report_period
+        ):
+            return
+
+        # Run the report generation task here
+        data_output = DataOutput.objects.create(
+            user=None,
+            total=0,
+            progress=0,
+            output_type="shortfall_report",
+            plugin=self.SLUG,
+        )
+
+        hide_no_shortfall = self.get_setting("HIDE_NO_SHORTFALL")
+
+        # Calculate shortfall report with default settings
+        requirements = calculate_shortfall(data_output.pk)
+
+        data_output.refresh_from_db()
+
+        # Email the report to interested users?
+        report_group_id = self.get_setting("SHORTFALL_REPORT_GROUP")
+
+        users = []
+
+        try:
+            group = Group.objects.get(pk=report_group_id)
+            users = group.user_set.filter(is_active=True)
+        except Group.DoesNotExist:
+            pass
+
+        recipients = []
+
+        for user in users:
+            if email := InvenTree.helpers_email.get_email_for_user(user):
+                if email not in recipients:
+                    recipients.append(email)
+
+        # Construct the email body
+        body = format_shortfall_report_html(
+            requirements, data_output, hide_no_shortfall=hide_no_shortfall
+        )
+
+        # Send email to users, with the report attached
+        if recipients:
+            InvenTree.helpers_email.send_email(
+                subject="[InvenTree] Component Shortfall Report",
+                body="Please find the attached component shortfall report.",
+                html_message=body,
+                recipients=recipients,
+            )
+
+        # Record success for the task
+        InvenTree.tasks.record_task_success("component_shortfall_report")

inventree_component_shortfall-0.1.0/component_shortfall/serializers.py

@@ -0,0 +1,46 @@
+"""API serializers for the ComponentShortfall plugin.
+
+In practice, you would define your custom serializers here.
+
+Ref: https://www.django-rest-framework.org/api-guide/serializers/
+"""
+
+from django.utils.translation import gettext_lazy as _
+from rest_framework import serializers
+
+import common.serializers
+import part.models as part_models
+
+
+class ShortfallReportSerializer(serializers.Serializer):
+    """Serializer for shortfall report request parameters."""
+
+    category = serializers.PrimaryKeyRelatedField(
+        queryset=part_models.PartCategory.objects.all(),
+        many=False,
+        required=False,
+        allow_null=True,
+        label=_("Category"),
+        help_text=_("The category for which to retrieve shortfall data"),
+    )
+
+    output = common.serializers.DataOutputSerializer(
+        read_only=True,
+        allow_null=True,
+    )
+
+    max_bom_depth = serializers.IntegerField(
+        required=False,
+        default=50,
+        min_value=0,
+        max_value=50,
+        label=_("Maximum BOM Depth"),
+        help_text=_("The maximum depth to traverse the BOM when calculating shortfall"),
+    )
+
+    def validate(self, data):
+        """Validate the provided data."""
+
+        # TODO: Any custom data validation goes here
+
+        return data

inventree_component_shortfall-0.1.0/component_shortfall/shortfall.py

@@ -0,0 +1,324 @@
+"""Functions for determining component shortfall.
+
+Process Goals:
+
+- Determine the overall "requirements" - based on outstanding Sales Orders
+- Iterate downward through the BOMs for each top-level part, to determine the requirements for each sub-component
+- Aggregate the "total" requirements for each component (based on the requirements of all parent assemblies)
+- Determine the shortfall for each component, based on the available stock, on-order quantity and in-production quantity
+
+"""
+
+from typing import Optional
+from decimal import Decimal
+import os
+import structlog
+import tablib
+
+from django.core.files.base import ContentFile
+from django.db.models import F
+
+from InvenTree.helpers_model import construct_absolute_url
+
+import common.models as common_models
+import part.models as part_models
+
+
+logger = structlog.get_logger("inventree.shortfall")
+
+
+def update_part_requirements(
+    part, required_qty: Decimal, component_data: dict
+) -> Decimal:
+    """Return requirements for the given part.
+
+    Arguments:
+        part: The part to process
+        required_qty: The additional quantity required for the part
+        component_data: A dict of part requirements (may be updated)
+
+    Returns:
+        The *additional* shortfall for this part (not cumulative)
+    """
+
+    requirements = component_data.get(part.pk, None) or {}
+
+    # Store the part information against the part
+    requirements["part"] = part
+
+    # Fetch (or calculate) the various stock values for this part
+    if "stock" not in requirements:
+        requirements["stock"] = part.get_stock_count(include_variants=False)
+
+    # TODO: What about BOM items which allow variants???
+
+    if "on_order" not in requirements:
+        requirements["on_order"] = part.on_order
+
+    # Add in the additional requirements
+    requirements["required"] = requirements.get("required", Decimal(0)) + Decimal(
+        required_qty
+    )
+
+    # TODO: Support offset for "in production" quantity
+
+    initial_shortfall = requirements.get("shortfall", Decimal(0))
+
+    # Calculate the "shortfall" for this part
+    requirements["shortfall"] = max(
+        0, requirements["required"] - requirements["stock"] - requirements["on_order"]
+    )
+
+    # Update the global dict of component data
+    component_data[part.pk] = requirements
+
+    # Return the additional shortfall for this part
+    return requirements["shortfall"] - initial_shortfall
+
+
+def get_outstanding_parts(category: Optional[part_models.PartCategory] = None) -> dict:
+    """Return a dict of outstanding parts (based on open sales orders).
+
+    Returns a dict of part requirements, with the part ID as the key.
+
+    Each element in the dict has the follow values:
+    - part: The part object
+    - required: The required quantity of the part (for sales order and build orders)
+
+    Arguments:
+        - category: Optional category to filter the parts by
+    """
+
+    from order.models import SalesOrderLineItem
+    from order.status_codes import SalesOrderStatusGroups
+
+    # Find all open sales order line items which are not completed
+    sales_order_lines = SalesOrderLineItem.objects.filter(
+        order__status__in=SalesOrderStatusGroups.OPEN,
+        part__virtual=False,
+        shipped__lt=F("quantity"),
+    ).prefetch_related(
+        "part",
+    )
+
+    # TODO: Filter by order status (e.g. exclude pending orders)
+
+    # TODO: Filter by order date (e.g. only include orders which are due within a certain time frame)
+
+    # Filter by part category (e.g. only include orders for parts within a certain category)
+    if category:
+        categories = category.get_descendants(include_self=True)
+        sales_order_lines = sales_order_lines.filter(part__category__in=categories)
+
+    outstanding_parts = {}
+
+    for line in sales_order_lines:
+        defecit = max(0, line.quantity - line.shipped)
+
+        if defecit <= 0:
+            # No outstanding quantity for this line item
+            continue
+
+        part_data = outstanding_parts.get(line.part.pk, None) or {
+            "part": line.part,
+            "required": Decimal(0),
+        }
+        part_data["required"] += line.quantity - line.shipped
+        outstanding_parts[line.part.pk] = part_data
+
+    return outstanding_parts
+
+
+def calculate_shortfall(
+    output_id: int, category_id: Optional[int] = None, max_bom_depth: int = 50
+) -> dict:
+    """Calculate the component shortfall for a given list of component IDs.
+
+    Arguments:
+        output_id: The ID of the DataOutput (where to save the results)
+        max_bom_depth: The maximum depth to traverse the BOM when calculating shortfall (default: 50)
+        category_id: The ID of the category to filter parts by (optional)
+
+    Returns:
+        A dict of part requirements, with the part ID as the key.
+
+        Each element in the dict has the follow values:
+        - part: The part object
+        - required: The required quantity of the part (for sales order and build orders)
+        - stock: The current stock on hand for this part
+        - on_order: The quantity of this part currently on order
+        - shortfall: The calculated shortfall for this part (required - stock - on_order)
+    """
+
+    logger.info("Generating component shortfall report")
+
+    try:
+        data_output = common_models.DataOutput.objects.get(pk=output_id)
+    except common_models.DataOutput.DoesNotExist:
+        logger.error(
+            f"component_shortfall: DataOutput with ID {output_id} does not exist - cannot save results"
+        )
+        return
+
+    try:
+        if category_id:
+            category = part_models.PartCategory.objects.get(pk=category_id)
+        else:
+            category = None
+    except (ValueError, part_models.PartCategory.DoesNotExist):
+        logger.warning(
+            f"component_shortfall: PartCategory with ID {category_id} does not exist - cannot filter parts"
+        )
+        category = None
+
+    # First, determine the set of components which are "on order"
+    initial_parts = get_outstanding_parts(category=category)
+
+    # Let's keep track of all the requirements, top-to-bottom, in a single dict - keyed by part ID
+    # key: part ID
+    # - part: Part instance
+    # - required: Total required quantity for this part (cumulative)
+    # - stock: Current stock on hand for this part
+    # - on_order: Quantity of this part currently on order
+    # - building: Quantity of this part currently being built
+    requirements = {}
+
+    # Keep a list of the components still required to process - start with the initial set of outstanding parts
+    # Each entry is a tuple of (part, quantity, level)
+    components_to_process = []
+
+    # Start with the initial set of outstanding parts
+    for _, data in initial_parts.items():
+        part = data["part"]
+        required_qty = data["required"]
+
+        components_to_process.append((part, required_qty, 0))
+
+    # Update initial conditions for the data output
+    data_output.progress = 0
+    data_output.total = len(components_to_process)
+    data_output.save()
+
+    while components_to_process:
+        part, quantity, level = components_to_process.pop(0)
+        data_output.progress += 1
+
+        shortfall = update_part_requirements(part, quantity, requirements)
+
+        # Update every 50 iterations
+        if data_output.progress % 50 == 0:
+            data_output.save()
+
+        if shortfall <= 0:
+            # No shortfall for this part - skip processing any sub-components
+            continue
+
+        # Prevent deep recursion into the BOM - if we have reached the maximum level, then we will not process any sub-components
+        if level >= max_bom_depth:
+            continue
+
+        # Is this an assembly?
+        if part.assembly:
+            components = (
+                part.get_bom_items(include_virtual=False)
+                .filter(consumable=False)
+                .prefetch_related(
+                    "sub_part",
+                    "sub_part__category",
+                )
+            )
+
+            for item in components:
+                sub_part = item.sub_part
+
+                # Calculate the quantity multiplier for this sub-part
+                required_qty = item.get_required_quantity(shortfall)
+
+                components_to_process.append((sub_part, required_qty, level + 1))
+                data_output.total += 1
+
+    # Generate the output data file
+    headers = [
+        "Part ID",
+        "Part Name",
+        "Part IPN",
+        "Category ID",
+        "Category Name",
+        "Current Stock",
+        "On Order",
+        "Required Quantity",
+        "Shortfall",
+    ]
+
+    dataset = tablib.Dataset(headers=headers)
+
+    for _, data in requirements.items():
+        part = data["part"]
+        url = construct_absolute_url(part.get_absolute_url())
+
+        row = [
+            f'=HYPERLINK("{url}", "{part.pk}")',
+            part.name,
+            part.IPN,
+            part.category.pk if part.category else None,
+            part.category.pathstring if part.category else None,
+            data["stock"],
+            data["on_order"],
+            data["required"],
+            data["shortfall"],
+        ]
+        dataset.append(row)
+
+    # Attach the generated file to the data output
+    datafile = dataset.export("xlsx")
+
+    data_output.mark_complete(
+        output=ContentFile(datafile, name="shortfall_report.xlsx")
+    )
+
+    return requirements
+
+
+def format_shortfall_report_html(
+    requirements: dict, output: common_models.DataOutput, hide_no_shortfall: bool = True
+) -> str:
+    """Format the shortfall report as a HTML document."""
+
+    from django.template import Template, Context
+
+    file_path = os.path.join(
+        os.path.dirname(__file__),
+        "templates",
+        "component_shortfall",
+        "shortfall_email.html",
+    )
+
+    with open(file_path, "r") as f:
+        template_content = f.read()
+
+    context_data = {}
+
+    # Add download link
+    if output and output.output:
+        context_data["download_url"] = construct_absolute_url(output.output.url)
+
+    # Add all the requirements entries
+    requirements_list = []
+
+    for entry in requirements.values():
+        if hide_no_shortfall and entry.get("shortfall", 0) <= 0:
+            continue
+
+        requirements_list.append({
+            **entry,
+            "part_url": construct_absolute_url(entry["part"].get_absolute_url()),
+        })
+
+    context_data["requirements"] = requirements_list
+
+    template = Template(template_content)
+    context = Context(context_data)
+
+    data = template.render(context)
+
+    return data

inventree_component_shortfall-0.1.0/component_shortfall/static/.vite/manifest.json

@@ -0,0 +1,8 @@
+{
+  "src/Dashboard.tsx": {
+    "file": "Dashboard.js",
+    "name": "Dashboard",
+    "src": "src/Dashboard.tsx",
+    "isEntry": true
+  }
+}