ordered ContractPage programs (#3079)

Author: gumaerc

b2b/admin.py

@@ -4,6 +4,7 @@
 
 from b2b.models import (
     ContractPage,
+    ContractProgramItem,
     DiscountContractAttachmentRedemption,
     OrganizationPage,
 )
@@ -46,10 +47,12 @@ class DiscountContractAttachmentRedemptionAdmin(ReadOnlyModelAdmin):
 class ContractPageProgramInline(admin.TabularInline):
     """Inline to display programs for contract pages."""
 
-    model = ContractPage.programs.through
+    model = ContractProgramItem
     extra = 0
     verbose_name = "Contract Program"
     verbose_name_plural = "Contract Programs"
+    fields = ["program", "sort_order"]
+    readonly_fields = ["program", "sort_order"]
 
     def has_add_permission(self, request, obj):  # noqa: ARG002
         """Turn off add permission. These admins are supposed to be read-only."""

b2b/management/commands/b2b_courseware.py

@@ -10,7 +10,7 @@
 from django.core.management import BaseCommand, CommandError
 
 from b2b.api import create_contract_run
-from b2b.models import ContractPage
+from b2b.models import ContractPage, ContractProgramItem
 from courses.api import resolve_courseware_object_from_id
 from courses.models import CourseRun
 
@@ -159,7 +159,6 @@ def handle_add(self, contract, coursewares, **kwargs):
                 contract.save()
                 managed += prog_add
                 skipped += prog_skip
-                contract.programs.add(courseware)
                 self.stdout.write(
                     self.style.SUCCESS(f"Added {courseware.readable_id} to {contract}.")
                 )
@@ -245,7 +244,9 @@ def handle_remove(self, contract, coursewares, **kwargs):
                         )
                     )
 
-                contract.programs.remove(courseware)
+                ContractProgramItem.objects.filter(
+                    contract=contract, program=courseware
+                ).delete()
                 self.stdout.write(
                     self.style.SUCCESS(
                         f"Removed program {courseware.readable_id} from contract {contract}."

b2b/migrations/0014_contractprogramitem.py

@@ -0,0 +1,55 @@
+# Generated by Django 4.2.25 on 2025-11-07 18:37
+
+import django.db.models.deletion
+import modelcluster.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("courses", "0074_populate_issue_date"),
+        ("b2b", "0013_fix_contract_attachment_related_names"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ContractProgramItem",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "sort_order",
+                    models.IntegerField(blank=True, editable=False, null=True),
+                ),
+                (
+                    "contract",
+                    modelcluster.fields.ParentalKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="contract_programs",
+                        to="b2b.contractpage",
+                    ),
+                ),
+                (
+                    "program",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="contract_memberships",
+                        to="courses.program",
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Contract Program Item",
+                "verbose_name_plural": "Contract Program Items",
+                "ordering": ["sort_order"],
+                "unique_together": {("contract", "program")},
+            },
+        ),
+    ]

b2b/migrations/0015_migrate_programs_to_contractprogramitem.py

@@ -0,0 +1,45 @@
+# Generated migration to move programs from M2M to ContractProgramItem
+
+from django.db import migrations
+
+
+def migrate_programs_to_items(apps, schema_editor):
+    """Migrate existing programs from M2M relationship to ContractProgramItem"""
+    ContractPage = apps.get_model("b2b", "ContractPage")
+    ContractProgramItem = apps.get_model("b2b", "ContractProgramItem")
+
+    for contract in ContractPage.objects.all():
+        # Get existing programs from the M2M relationship
+        programs = contract.programs.all()
+
+        # Create ContractProgramItem entries for each program
+        for index, program in enumerate(programs):
+            ContractProgramItem.objects.get_or_create(
+                contract=contract, program=program, defaults={"sort_order": index}
+            )
+
+
+def reverse_migration(apps, schema_editor):
+    """Reverse: copy data back from ContractProgramItem to M2M"""
+    ContractPage = apps.get_model("b2b", "ContractPage")
+    ContractProgramItem = apps.get_model("b2b", "ContractProgramItem")
+
+    for contract in ContractPage.objects.all():
+        # Get programs from ContractProgramItem
+        items = ContractProgramItem.objects.filter(contract=contract).order_by(
+            "sort_order"
+        )
+
+        # Add them back to the M2M relationship
+        for item in items:
+            contract.programs.add(item.program)
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("b2b", "0014_contractprogramitem"),
+    ]
+
+    operations = [
+        migrations.RunPython(migrate_programs_to_items, reverse_migration),
+    ]

b2b/migrations/0016_remove_contractpage_programs.py

@@ -0,0 +1,16 @@
+# Generated migration to remove old programs M2M field
+
+from django.db import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("b2b", "0015_migrate_programs_to_contractprogramitem"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="contractpage",
+            name="programs",
+        ),
+    ]

b2b/models.py

@@ -10,10 +10,11 @@
 from django.utils.text import slugify
 from mitol.common.models import TimestampedModel
 from mitol.common.utils import now_in_utc
+from modelcluster.fields import ParentalKey
 from requests.exceptions import HTTPError
-from wagtail.admin.panels import FieldPanel, MultiFieldPanel
+from wagtail.admin.panels import FieldPanel, InlinePanel, MultiFieldPanel
 from wagtail.fields import RichTextField
-from wagtail.models import Page
+from wagtail.models import ClusterableModel, Orderable, Page
 
 from b2b.constants import (
     CONTRACT_MEMBERSHIP_AUTOS,
@@ -24,6 +25,7 @@
 )
 from b2b.exceptions import TargetCourseRunExistsError
 from b2b.tasks import queue_enrollment_code_check
+from courses.models import Program
 
 log = logging.getLogger(__name__)
 
@@ -188,7 +190,53 @@ class Meta:
         ]
 
 
-class ContractPage(Page):
+class ContractProgramItem(Orderable):
+    """Intermediate model to store programs in a contract with ordering"""
+
+    contract = ParentalKey(
+        "ContractPage", on_delete=models.CASCADE, related_name="contract_programs"
+    )
+    program = models.ForeignKey(
+        Program, on_delete=models.CASCADE, related_name="contract_memberships"
+    )
+
+    panels = [
+        FieldPanel("program"),
+    ]
+
+    class Meta:
+        ordering = ["sort_order"]
+        unique_together = ("contract", "program")
+        verbose_name = "Contract Program Item"
+        verbose_name_plural = "Contract Program Items"
+
+    def __str__(self):
+        return (
+            f"{self.contract.title} - {self.program.title} (order: {self.sort_order})"
+        )
+
+    def save(self, *args, skip_run_creation=False, **kwargs):
+        """
+        Queue async task to create contract runs for new program associations.
+
+        Args:
+            skip_run_creation: Skip task if runs are created synchronously.
+        """
+        is_new = self.pk is None
+        super().save(*args, **kwargs)
+
+        if is_new and not skip_run_creation:
+            from b2b.tasks import create_program_contract_runs
+
+            create_program_contract_runs.delay(self.contract.id, self.program.id)
+            log.info(
+                "Queued contract run creation for program %s in contract %s",
+                self.program.id,
+                self.contract.id,
+            )
+
+
+class ContractPage(Page, ClusterableModel):
     """Stores information about a contract with an organization."""
 
     parent_page_types = ["b2b.OrganizationPage"]
@@ -248,11 +296,16 @@ class ContractPage(Page):
         null=True,
         help_text="The fixed price for enrollment under this contract. (Set to zero or leave blank for free.)",
     )
-    programs = models.ManyToManyField(
-        "courses.Program",
-        help_text="The programs associated with this contract.",
-        related_name="contracts",
-    )
+
+    @property
+    def programs(self):
+        """
+        Returns programs in the contract ordered by their order field.
+        This replaces the old ManyToManyField with ordered access via ContractProgramItem.
+        """
+        return Program.objects.filter(contract_memberships__contract=self).order_by(
+            "contract_memberships__sort_order"
+        )
 
     content_panels = [
         FieldPanel("name"),
@@ -285,6 +338,11 @@ class ContractPage(Page):
             heading="Availability",
             icon="calendar-alt",
         ),
+        InlinePanel(
+            "contract_programs",
+            heading="Programs",
+            help_text="Add and order programs in this contract",
+        ),
     ]
 
     promote_panels = []
@@ -377,7 +435,7 @@ def get_discounts(self):
 
         return Discount.objects.filter(products__product__in=self.get_products()).all()
 
-    def add_program_courses(self, program):
+    def add_program_courses(self, program, order=None):
         """
         Add a program, and then queue adding all its courses.
 
@@ -414,7 +472,17 @@ def add_program_courses(self, program):
             except TargetCourseRunExistsError:  # noqa: PERF203
                 skipped_run_creation += 1
 
-        self.programs.add(program)
+        if order is None:
+            last_item = self.contract_programs.order_by("-sort_order").first()
+            order = (last_item.sort_order + 1) if last_item else 0
+
+        existing_item = ContractProgramItem.objects.filter(
+            contract=self, program=program
+        ).first()
+
+        if not existing_item:
+            item = ContractProgramItem(contract=self, program=program, sort_order=order)
+            item.save(skip_run_creation=True)
 
         return (managed, skipped_run_creation, no_source)
 

b2b/serializers/v0/__init__.py

@@ -14,6 +14,12 @@ class ContractPageSerializer(serializers.ModelSerializer):
     """
 
     membership_type = serializers.CharField()
+    programs = serializers.SerializerMethodField()
+
+    @extend_schema_field(serializers.ListField(child=serializers.IntegerField()))
+    def get_programs(self, instance):
+        """Get the ordered list of program IDs for this contract"""
+        return list(instance.programs.values_list("id", flat=True))
 
     class Meta:
         model = ContractPage
@@ -31,6 +37,7 @@ class Meta:
             "active",
             "slug",
             "organization",
+            "programs",
         ]
         read_only_fields = [
             "id",
@@ -46,6 +53,7 @@ class Meta:
             "active",
             "slug",
             "organization",
+            "programs",
         ]