feat: CalendarGroup models, querysets, and admin

Author: hugobessa

calendar_integration/admin.py

@@ -9,7 +9,14 @@
 from django.utils.html import format_html
 
 from calendar_integration.constants import IncomingWebhookProcessingStatus
-from calendar_integration.models import CalendarWebhookEvent, CalendarWebhookSubscription
+from calendar_integration.models import (
+    CalendarEventGroupSelection,
+    CalendarGroup,
+    CalendarGroupSlot,
+    CalendarGroupSlotMembership,
+    CalendarWebhookEvent,
+    CalendarWebhookSubscription,
+)
 
 
 class CalendarWebhookEventInline(admin.TabularInline):
@@ -298,6 +305,99 @@ def reprocess_events(self, request: HttpRequest, queryset):
         self.message_user(request, f"Reset {count} events for reprocessing.")
 
 
+class CalendarGroupSlotMembershipInline(admin.TabularInline):
+    """Inline admin for memberships within a CalendarGroupSlot."""
+
+    model = CalendarGroupSlotMembership
+    fk_name = "slot_fk"
+    fields = ("calendar_fk",)
+    extra = 1
+
+
+class CalendarGroupSlotInline(admin.TabularInline):
+    """Inline admin for slots within a CalendarGroup."""
+
+    model = CalendarGroupSlot
+    fk_name = "group_fk"
+    fields = ("name", "order", "required_count", "description")
+    extra = 1
+
+
+@admin.register(CalendarGroup)
+class CalendarGroupAdmin(admin.ModelAdmin):
+    """Admin interface for CalendarGroup."""
+
+    list_display = ("id", "name", "organization", "slot_count", "created")
+    list_filter = ("organization", "created")
+    search_fields = ("name", "description")
+    readonly_fields = ("created", "modified")
+    fields = ("organization", "name", "description", "created", "modified")
+    inlines: ClassVar = [CalendarGroupSlotInline]
+
+    def get_queryset(self, request: HttpRequest):
+        return (
+            super()
+            .get_queryset(request)
+            .select_related("organization")
+            .annotate(_slot_count=Count("slots"))
+        )
+
+    @admin.display(description="Slots", ordering="_slot_count")
+    def slot_count(self, obj: CalendarGroup) -> int:
+        return getattr(obj, "_slot_count", obj.slots.count())
+
+
+@admin.register(CalendarGroupSlot)
+class CalendarGroupSlotAdmin(admin.ModelAdmin):
+    """Admin interface for CalendarGroupSlot."""
+
+    list_display = ("id", "name", "group", "order", "required_count", "calendar_count")
+    list_filter = ("group_fk", "organization")
+    search_fields = ("name", "group_fk__name")
+    readonly_fields = ("created", "modified")
+    fields = (
+        "organization",
+        "group_fk",
+        "name",
+        "description",
+        "order",
+        "required_count",
+        "created",
+        "modified",
+    )
+    inlines: ClassVar = [CalendarGroupSlotMembershipInline]
+
+    def get_queryset(self, request: HttpRequest):
+        return (
+            super()
+            .get_queryset(request)
+            .select_related("organization", "group_fk")
+            .annotate(_calendar_count=Count("memberships"))
+        )
+
+    @admin.display(description="Calendars", ordering="_calendar_count")
+    def calendar_count(self, obj: CalendarGroupSlot) -> int:
+        return getattr(obj, "_calendar_count", obj.memberships.count())
+
+
+@admin.register(CalendarEventGroupSelection)
+class CalendarEventGroupSelectionAdmin(admin.ModelAdmin):
+    """Admin interface for CalendarEventGroupSelection."""
+
+    list_display = ("id", "event", "slot", "calendar", "created")
+    list_filter = ("organization", "created")
+    search_fields = ("event_fk__title", "slot_fk__name", "calendar_fk__name")
+    readonly_fields = ("created", "modified")
+    fields = ("organization", "event_fk", "slot_fk", "calendar_fk", "created", "modified")
+
+    def get_queryset(self, request: HttpRequest):
+        return (
+            super()
+            .get_queryset(request)
+            .select_related("organization", "event_fk", "slot_fk", "calendar_fk")
+        )
+
+
 class WebhookHealthDashboard:
     """Dashboard widget for webhook health overview."""
 

calendar_integration/managers.py

@@ -2,7 +2,11 @@
 from collections.abc import Iterable
 
 from calendar_integration.querysets import (
+    CalendarEventGroupSelectionQuerySet,
     CalendarEventQuerySet,
+    CalendarGroupQuerySet,
+    CalendarGroupSlotMembershipQuerySet,
+    CalendarGroupSlotQuerySet,
     CalendarQuerySet,
     CalendarSyncQuerySet,
     RecurringQuerySetMixin,
@@ -156,3 +160,40 @@ def get_queryset(self):
         from calendar_integration.querysets import AvailableTimeQuerySet
 
         return AvailableTimeQuerySet(self.model, using=self._db)
+
+
+class CalendarGroupManager(BaseOrganizationModelManager):
+    """Custom manager for CalendarGroup model to handle specific queries."""
+
+    def get_queryset(self) -> CalendarGroupQuerySet:
+        return CalendarGroupQuerySet(self.model, using=self._db)
+
+    def only_groups_bookable_in_ranges(
+        self, ranges: Iterable[tuple[datetime.datetime, datetime.datetime]]
+    ):
+        """
+        Returns groups where every slot has at least `required_count` calendars
+        from its pool available in every requested range.
+        """
+        return self.get_queryset().only_groups_bookable_in_ranges(ranges=ranges)
+
+
+class CalendarGroupSlotManager(BaseOrganizationModelManager):
+    """Custom manager for CalendarGroupSlot model to handle specific queries."""
+
+    def get_queryset(self) -> CalendarGroupSlotQuerySet:
+        return CalendarGroupSlotQuerySet(self.model, using=self._db)
+
+
+class CalendarGroupSlotMembershipManager(BaseOrganizationModelManager):
+    """Custom manager for CalendarGroupSlotMembership model to handle specific queries."""
+
+    def get_queryset(self) -> CalendarGroupSlotMembershipQuerySet:
+        return CalendarGroupSlotMembershipQuerySet(self.model, using=self._db)
+
+
+class CalendarEventGroupSelectionManager(BaseOrganizationModelManager):
+    """Custom manager for CalendarEventGroupSelection model to handle specific queries."""
+
+    def get_queryset(self) -> CalendarEventGroupSelectionQuerySet:
+        return CalendarEventGroupSelectionQuerySet(self.model, using=self._db)

calendar_integration/migrations/0010_calendargroup_calendarevent_calendar_group_and_more.py

@@ -0,0 +1,109 @@
+# Generated by Django 5.2.2 on 2026-04-20 23:23
+
+import django.db.models.deletion
+import django.utils.timezone
+import model_utils.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('calendar_integration', '0009_fix_webhook_unique_constraint'),
+        ('organizations', '0003_organizationinvitation'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='CalendarGroup',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('meta', models.JSONField(blank=True, default=dict, verbose_name='meta')),
+                ('name', models.CharField(max_length=255)),
+                ('description', models.TextField(blank=True)),
+                ('organization', models.ForeignKey(help_text='The organization this model is associated with. Queries should use the `organization` field.', on_delete=django.db.models.deletion.CASCADE, related_name='+', to='organizations.organization')),
+            ],
+        ),
+        migrations.AddField(
+            model_name='calendarevent',
+            name='calendar_group',
+            field=models.ForeignObject(editable=False, from_fields=['calendar_group_fk', 'organization_id'], null=True, on_delete=django.db.models.deletion.PROTECT, related_name='events', to='calendar_integration.calendargroup', to_fields=['id', 'organization_id']),
+        ),
+        migrations.AddField(
+            model_name='calendarevent',
+            name='calendar_group_fk',
+            field=models.ForeignKey(blank=True, help_text='If this event was booked through a CalendarGroup, references it', null=True, on_delete=django.db.models.deletion.PROTECT, related_name='events_fk_rel', to='calendar_integration.calendargroup'),
+        ),
+        migrations.CreateModel(
+            name='CalendarGroupSlot',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('meta', models.JSONField(blank=True, default=dict, verbose_name='meta')),
+                ('name', models.CharField(max_length=255)),
+                ('description', models.TextField(blank=True)),
+                ('order', models.PositiveSmallIntegerField(default=0)),
+                ('required_count', models.PositiveSmallIntegerField(default=1, help_text='How many calendars from the pool must be selected when booking. Default 1; use larger values when a slot needs multiple calendars (e.g. two nurses).')),
+                ('group', models.ForeignObject(editable=False, from_fields=['group_fk', 'organization_id'], on_delete=django.db.models.deletion.CASCADE, related_name='slots', to='calendar_integration.calendargroup', to_fields=['id', 'organization_id'])),
+                ('group_fk', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='slots_fk_rel', to='calendar_integration.calendargroup')),
+                ('organization', models.ForeignKey(help_text='The organization this model is associated with. Queries should use the `organization` field.', on_delete=django.db.models.deletion.CASCADE, related_name='+', to='organizations.organization')),
+            ],
+            options={
+                'ordering': ('order', 'id'),
+            },
+        ),
+        migrations.CreateModel(
+            name='CalendarEventGroupSelection',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('meta', models.JSONField(blank=True, default=dict, verbose_name='meta')),
+                ('calendar', models.ForeignObject(editable=False, from_fields=['calendar_fk', 'organization_id'], on_delete=django.db.models.deletion.PROTECT, related_name='group_selections', to='calendar_integration.calendar', to_fields=['id', 'organization_id'])),
+                ('calendar_fk', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='group_selections_fk_rel', to='calendar_integration.calendar')),
+                ('event', models.ForeignObject(editable=False, from_fields=['event_fk', 'organization_id'], on_delete=django.db.models.deletion.CASCADE, related_name='group_selections', to='calendar_integration.calendarevent', to_fields=['id', 'organization_id'])),
+                ('event_fk', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='group_selections_fk_rel', to='calendar_integration.calendarevent')),
+                ('organization', models.ForeignKey(help_text='The organization this model is associated with. Queries should use the `organization` field.', on_delete=django.db.models.deletion.CASCADE, related_name='+', to='organizations.organization')),
+                ('slot', models.ForeignObject(editable=False, from_fields=['slot_fk', 'organization_id'], on_delete=django.db.models.deletion.PROTECT, related_name='selections', to='calendar_integration.calendargroupslot', to_fields=['id', 'organization_id'])),
+                ('slot_fk', models.ForeignKey(on_delete=django.db.models.deletion.PROTECT, related_name='selections_fk_rel', to='calendar_integration.calendargroupslot')),
+            ],
+        ),
+        migrations.CreateModel(
+            name='CalendarGroupSlotMembership',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created', model_utils.fields.AutoCreatedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='created')),
+                ('modified', model_utils.fields.AutoLastModifiedField(db_index=True, default=django.utils.timezone.now, editable=False, verbose_name='modified')),
+                ('meta', models.JSONField(blank=True, default=dict, verbose_name='meta')),
+                ('calendar', models.ForeignObject(editable=False, from_fields=['calendar_fk', 'organization_id'], on_delete=django.db.models.deletion.CASCADE, related_name='group_slot_memberships', to='calendar_integration.calendar', to_fields=['id', 'organization_id'])),
+                ('calendar_fk', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='group_slot_memberships_fk_rel', to='calendar_integration.calendar')),
+                ('organization', models.ForeignKey(help_text='The organization this model is associated with. Queries should use the `organization` field.', on_delete=django.db.models.deletion.CASCADE, related_name='+', to='organizations.organization')),
+                ('slot', models.ForeignObject(editable=False, from_fields=['slot_fk', 'organization_id'], on_delete=django.db.models.deletion.CASCADE, related_name='memberships', to='calendar_integration.calendargroupslot', to_fields=['id', 'organization_id'])),
+                ('slot_fk', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='memberships_fk_rel', to='calendar_integration.calendargroupslot')),
+            ],
+        ),
+        migrations.AddField(
+            model_name='calendargroupslot',
+            name='calendars',
+            field=models.ManyToManyField(related_name='group_slots', through='calendar_integration.CalendarGroupSlotMembership', through_fields=('slot', 'calendar'), to='calendar_integration.calendar'),
+        ),
+        migrations.AddConstraint(
+            model_name='calendargroup',
+            constraint=models.UniqueConstraint(fields=('organization', 'name'), name='calendargroup_unique_name_per_org'),
+        ),
+        migrations.AddConstraint(
+            model_name='calendareventgroupselection',
+            constraint=models.UniqueConstraint(fields=('event_fk', 'slot_fk', 'calendar_fk'), name='calendareventgroupselection_unique'),
+        ),
+        migrations.AddConstraint(
+            model_name='calendargroupslotmembership',
+            constraint=models.UniqueConstraint(fields=('slot_fk', 'calendar_fk'), name='calendargroupslotmembership_unique_slot_calendar'),
+        ),
+        migrations.AddConstraint(
+            model_name='calendargroupslot',
+            constraint=models.UniqueConstraint(fields=('group_fk', 'name'), name='calendargroupslot_unique_name_per_group'),
+        ),
+    ]