feat(backend): add tipps endpoint

src/backend/InvenTree/InvenTree/api_version.py

@@ -1,11 +1,14 @@
 """InvenTree API version information."""
 
 # InvenTree API version
-INVENTREE_API_VERSION = 430
+INVENTREE_API_VERSION = 431
 """Increment this API version number whenever there is a significant change to the API that any clients need to know about."""
 
 INVENTREE_API_TEXT = """
 
+v431 -> 2025-12-04 : https://github.com/inventree/InvenTree/pull/10715
+    - Adds GuideDefinition and GuideExecution models and API endpoints to provide tipps and guides within InvenTree's web frontend.
+
 v430 -> 2025-12-04 : https://github.com/inventree/InvenTree/pull/10699
     - Removed the "PartParameter" and "PartParameterTemplate" API endpoints
     - Removed the "ManufacturerPartParameter" API endpoint

src/backend/InvenTree/InvenTree/helpers.py

@@ -1,6 +1,7 @@
 """Provides helper functions used throughout the InvenTree project."""
 
 import datetime
+import gc
 import hashlib
 import inspect
 import io
@@ -1147,6 +1148,15 @@ def inheritors(
     return subcls
 
 
+def instances_of(cls: type[Inheritors_T]) -> list[Inheritors_T]:
+    """Return instances of a class.
+
+    Args:
+        cls: The class of which type instances should be searched
+    """
+    return [k for k in gc.get_referrers(cls) if k.__class__ is cls]
+
+
 def pui_url(subpath: str) -> str:
     """Return the URL for a web subpath."""
     if not subpath.startswith('/'):

src/backend/InvenTree/InvenTree/serializers.py

@@ -210,6 +210,10 @@ class FilterableIntegerField(FilterableSerializerField, serializers.IntegerField
     """Custom IntegerField which allows filtering."""
 
 
+class FilterableJSONField(FilterableSerializerField, serializers.JSONField):
+    """Custom JSONField which allows filtering."""
+
+
 # endregion
 
 

src/backend/InvenTree/InvenTree/settings.py

@@ -293,7 +293,7 @@
     'machine.apps.MachineConfig',
     'data_exporter.apps.DataExporterConfig',
     'importer.apps.ImporterConfig',
-    'web',
+    'web.apps.WebConfig',
     'generic',
     'InvenTree.apps.InvenTreeConfig',  # InvenTree app runs last
     # Core django modules

src/backend/InvenTree/InvenTree/urls.py

@@ -27,6 +27,7 @@
 import report.api
 import stock.api
 import users.api
+import web.api
 from plugin.urls import get_plugin_urls
 from web.urls import cui_compatibility_urls
 from web.urls import urlpatterns as platform_urls
@@ -80,6 +81,7 @@
         ]),
     ),
     path('user/', include(users.api.user_urls)),
+    path('web/', include(web.api.web_urls)),
     # Plugin endpoints
     path('', include(plugin.api.plugin_api_urls)),
     # Common endpoints endpoint

src/backend/InvenTree/users/ruleset.py

@@ -192,6 +192,9 @@ def get_ruleset_ignore() -> list[str]:
         'common_selectionlist',
         'users_owner',
         'users_userprofile',  # User profile is handled in the serializer - only own user can change
+        # Web
+        'web_guidedefinition',
+        'web_guideexecution',
         # Third-party tables
         'error_report_error',
         'exchange_rate',

src/backend/InvenTree/web/admin.py

@@ -0,0 +1,23 @@
+"""Admin classes for the 'web' app."""
+
+from django.contrib import admin
+
+from web.models import GuideDefinition, GuideExecution
+
+
+class GuideExecutionInline(admin.TabularInline):
+    """Inline for guide executions."""
+
+    model = GuideExecution
+    extra = 1
+
+
+@admin.register(GuideDefinition)
+class GuideDefinitionAdmin(admin.ModelAdmin):
+    """Admin class for the GuideDefinition model."""
+
+    list_display = ('guide_type', 'name', 'slug')
+    list_filter = ('guide_type',)
+    inlines = [GuideExecutionInline]
+    fields = ('guide_type', 'name', 'slug', 'description', 'guide_data', 'metadata')
+    prepopulated_fields = {'slug': ('name',)}

src/backend/InvenTree/web/api.py

@@ -0,0 +1,122 @@
+"""DRF API definition for the 'web' app."""
+
+from datetime import datetime
+
+from django.urls import include, path
+
+import django_filters.rest_framework.filters as rest_filters
+import structlog
+
+import InvenTree.permissions
+from InvenTree.fields import InvenTreeOutputOption, OutputConfiguration
+from InvenTree.filters import SEARCH_ORDER_FILTER
+from InvenTree.helpers import str2bool
+from InvenTree.mixins import (
+    ListAPI,
+    OutputOptionsMixin,
+    RetrieveAPI,
+    SerializerContextMixin,
+    UpdateAPI,
+)
+from web.models import GuideDefinition
+from web.serializers import EmptySerializer, GuideDefinitionSerializer
+
+logger = structlog.get_logger('inventree')
+
+
+class GuideDefinitionFilter:
+    """Filter class for GuideDefinition objects."""
+
+    all = rest_filters.BooleanFilter(
+        label='Show all definitions', method='filter_all', default=False
+    )
+
+    def filter_all(self, queryset, name, value):
+        """Filter to show all definitions."""
+        if str2bool(value):
+            return queryset
+        return queryset.filter(executions__done=False)
+
+
+class GuideDefinitionMixin(SerializerContextMixin):
+    """Mixin for GuideDefinition detail views."""
+
+    queryset = GuideDefinition.objects.all()
+    serializer_class = GuideDefinitionSerializer
+    permission_classes = [InvenTree.permissions.IsStaffOrReadOnlyScope]
+    filter_backends = SEARCH_ORDER_FILTER
+    filterclass = GuideDefinitionFilter
+
+    def get_queryset(self):
+        """Return queryset for this endpoint."""
+        return super().get_queryset().prefetch_related('executions')
+
+
+class GuideDefinitionDetailOptions(OutputConfiguration):
+    """Holds all available output options for Group views."""
+
+    OPTIONS = [
+        InvenTreeOutputOption(
+            'description',
+            description='Include description field (optional, may be large)',
+        ),
+        InvenTreeOutputOption(
+            'guide_data',
+            description='Include data field (optional, may be large JSON object and is only meant for machines)',
+        ),
+    ]
+
+
+class GuideDefinitionDetail(GuideDefinitionMixin, OutputOptionsMixin, RetrieveAPI):
+    """Detail for a particular guide definition."""
+
+    output_options = GuideDefinitionDetailOptions
+
+
+class GuideDefinitionList(GuideDefinitionMixin, OutputOptionsMixin, ListAPI):
+    """List of guide definitions."""
+
+    output_options = GuideDefinitionDetailOptions
+    filter_backends = SEARCH_ORDER_FILTER
+    search_fields = ['name', 'slug', 'description']
+    ordering_fields = ['guide_type', 'slug', 'name']
+
+
+class GuideDismissal(UpdateAPI):
+    """Dismissing a guide for the current user."""
+
+    queryset = GuideDefinition.objects.all()
+    serializer_class = EmptySerializer
+    permission_classes = [InvenTree.permissions.IsAuthenticatedOrReadScope]
+    lookup_field = 'slug'
+
+    def get_serializer_context(self):
+        """Provide context for the serializer."""
+        context = super().get_serializer_context()
+        context['user'] = self.request.user
+        return context
+
+    def perform_update(self, serializer):
+        """Override to dismiss the guide for the user."""
+        obj: GuideDefinition = serializer.instance
+        user = self.request.user
+        items = obj.executions.filter(user__pk=user.pk, done=True)
+        if len(items) == 0:
+            obj.executions.create(user=user, done=True, completed_at=datetime.now())
+            logger.info('Guide dismissed', guide=obj.slug, user=user.username)
+
+
+web_urls = [
+    path(
+        'guides/',
+        include([
+            path(
+                '<str:slug>/dismiss/',
+                GuideDismissal.as_view(),
+                name='api-guide-dismiss',
+            ),
+            path('<int:pk>/', GuideDefinitionDetail.as_view(), name='api-guide-detail'),
+            path('', GuideDefinitionList.as_view(), name='api-guide-list'),
+        ]),
+    )
+]

src/backend/InvenTree/web/apps.py

@@ -0,0 +1,23 @@
+"""App config for "web" app."""
+
+from django.apps import AppConfig
+
+import structlog
+
+import InvenTree.ready
+
+logger = structlog.get_logger('inventree')
+
+
+class WebConfig(AppConfig):
+    """AppConfig for web app."""
+
+    name = 'web'
+
+    def ready(self):
+        """Initialize restart flag clearance on startup."""
+        if not InvenTree.ready.canAppAccessDatabase():  # pragma: no cover
+            return
+        from web.models import collect_guides  # pragma: no cover
+
+        collect_guides(create=True)  # Preload guide definitions  # pragma: no cover

src/backend/InvenTree/web/migrations/0001_initial.py

@@ -0,0 +1,53 @@
+# Generated by Django 5.2.8 on 2025-11-24 11:39
+
+import django.db.models.deletion
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+from web.models import GuideDefinition
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='GuideDefinition',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('metadata', models.JSONField(blank=True, help_text='JSON metadata field, for use by external plugins', null=True, verbose_name='Plugin Metadata')),
+                ('uid', models.CharField(default=uuid.uuid4, editable=False, help_text='Unique uuid4 identifier for this guide definition', max_length=255, verbose_name='Endpoint')),
+                ('name', models.CharField(help_text='Name of the guide', max_length=100, unique=True, verbose_name='Name')),
+                ('slug', models.SlugField(help_text='URL-friendly unique identifier for the guide', max_length=100, unique=True, verbose_name='Slug')),
+                ('description', models.TextField(blank=True, help_text='Optional description of the guide', verbose_name='Description')),
+                ('guide_type', models.CharField(choices=GuideDefinition.GuideType.choices, help_text='Type of the guide', max_length=20, verbose_name='Guide Type')),
+                ('guide_data', models.JSONField(blank=True, help_text='JSON data field for storing extra information', null=True, verbose_name='Data')),
+            ],
+            options={
+                'verbose_name': 'Guide Definition',
+                'verbose_name_plural': 'Guide Definitions',
+            },
+        ),
+        migrations.CreateModel(
+            name='GuideExecution',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('metadata', models.JSONField(blank=True, help_text='JSON metadata field, for use by external plugins', null=True, verbose_name='Plugin Metadata')),
+                ('uid', models.CharField(default=uuid.uuid4, editable=False, help_text='Unique identifier for this guide execution', max_length=255, verbose_name='UID')),
+                ('started_at', models.DateTimeField(auto_now_add=True, help_text='Timestamp when the guide execution started', verbose_name='Started At')),
+                ('completed_at', models.DateTimeField(blank=True, help_text='Timestamp when the guide execution was completed', null=True, verbose_name='Completed At')),
+                ('progres_data', models.JSONField(blank=True, help_text='JSON field to track progress of the guide execution', null=True, verbose_name='Progress')),
+                ('done', models.BooleanField(default=False, help_text='Indicates whether the guide execution is completed', verbose_name='Done')),
+                ('guide', models.ForeignKey(help_text='The guide definition associated with this execution', on_delete=django.db.models.deletion.CASCADE, related_name='executions', to='web.guidedefinition', verbose_name='Guide')),
+                ('user', models.ForeignKey(help_text='The user who is executing the guide', on_delete=django.db.models.deletion.CASCADE, related_name='guide_executions', to=settings.AUTH_USER_MODEL, verbose_name='User')),
+            ],
+            options={
+                'verbose_name': 'Guide Execution',
+                'verbose_name_plural': 'Guide Executions',
+            },
+        ),
+    ]