feat: renewal workflow with expiring/expired sponsorship alerts

Dashboard shows cross-year "Expiring Soon" (90-day window with color-coded
countdown) and "Recently Expired" sections with one-click "+ Renewal" buttons
that launch the Composer with sponsor pre-selected and renewal flag set.

Sponsorship list shows expiry tags in the Period column. Detail page shows
Expiring Soon/Expired tags and a "+ Renewal" button for finalized sponsorships.

Adds sponsors_manage templatetags, guide documentation, and 15 tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: JacobCoffee

apps/sponsors/manage/tests.py

@@ -2072,3 +2072,226 @@ def test_invalid_step_defaults_to_1(self):
         response = self.client.get(reverse("manage_composer") + "?step=abc")
         self.assertEqual(response.status_code, 200)
         self.assertContains(response, "Select a Sponsor")
+
+
+class DashboardExpiringSoonTests(SponsorManageTestBase):
+    """Test dashboard expiring/expired sponsorship sections."""
+
+    @classmethod
+    def setUpTestData(cls):
+        super().setUpTestData()
+        cls.sponsor = Sponsor.objects.create(name="Expiring Corp")
+
+    def setUp(self):
+        super().setUp()
+        self.client.login(username="staff", password="pass")
+
+    def test_expiring_soon_shown_on_dashboard(self):
+        """Finalized sponsorship ending within 90 days appears in Expiring Soon."""
+        today = timezone.now().date()
+        Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=self.year,
+            status=Sponsorship.FINALIZED,
+            start_date=today - datetime.timedelta(days=300),
+            end_date=today + datetime.timedelta(days=30),
+        )
+        response = self.client.get(reverse("manage_dashboard") + f"?year={self.year}")
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "Expiring Soon")
+        self.assertContains(response, "Expiring Corp")
+
+    def test_expiring_far_future_not_shown(self):
+        """Finalized sponsorship ending more than 90 days out is not in Expiring Soon."""
+        today = timezone.now().date()
+        Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=self.year,
+            status=Sponsorship.FINALIZED,
+            start_date=today - datetime.timedelta(days=100),
+            end_date=today + datetime.timedelta(days=200),
+        )
+        response = self.client.get(reverse("manage_dashboard") + f"?year={self.year}")
+        self.assertNotContains(response, "Expiring Soon")
+
+    def test_recently_expired_shown_on_dashboard(self):
+        """Finalized sponsorship with past end_date appears in Recently Expired."""
+        today = timezone.now().date()
+        Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=self.year,
+            status=Sponsorship.FINALIZED,
+            start_date=today - datetime.timedelta(days=400),
+            end_date=today - datetime.timedelta(days=10),
+        )
+        response = self.client.get(reverse("manage_dashboard") + f"?year={self.year}")
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, "Recently Expired")
+        self.assertContains(response, "Expiring Corp")
+
+    def test_overlapped_expired_not_shown(self):
+        """Expired sponsorship with overlapped_by set is excluded from Recently Expired."""
+        today = timezone.now().date()
+        renewal = Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=self.year,
+            status=Sponsorship.FINALIZED,
+            start_date=today - datetime.timedelta(days=30),
+            end_date=today + datetime.timedelta(days=335),
+        )
+        Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=self.year,
+            status=Sponsorship.FINALIZED,
+            start_date=today - datetime.timedelta(days=400),
+            end_date=today - datetime.timedelta(days=10),
+            overlapped_by=renewal,
+        )
+        response = self.client.get(reverse("manage_dashboard") + f"?year={self.year}")
+        self.assertNotContains(response, "Recently Expired")
+
+    def test_applied_sponsorship_not_in_expiring(self):
+        """Only finalized sponsorships appear in expiring sections."""
+        today = timezone.now().date()
+        Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=self.year,
+            status=Sponsorship.APPLIED,
+            start_date=today - datetime.timedelta(days=300),
+            end_date=today + datetime.timedelta(days=10),
+        )
+        response = self.client.get(reverse("manage_dashboard") + f"?year={self.year}")
+        self.assertNotContains(response, "Expiring Soon")
+
+    def test_expiring_shown_cross_year(self):
+        """Expiring sponsorships from a prior year show on the current year dashboard."""
+        today = timezone.now().date()
+        prior_year = self.year - 1
+        Sponsorship.objects.create(
+            sponsor=self.sponsor,
+            submited_by=self.staff_user,
+            package=self.package,
+            sponsorship_fee=100000,
+            year=prior_year,
+            status=Sponsorship.FINALIZED,
+            start_date=today - datetime.timedelta(days=300),
+            end_date=today + datetime.timedelta(days=30),
+        )
+        response = self.client.get(reverse("manage_dashboard") + f"?year={self.year}")
+        self.assertContains(response, "Expiring Soon")
+        self.assertContains(response, "Expiring Corp")
+
+
+class SponsorshipDetailRenewalTests(SponsorshipReviewTestBase):
+    """Test renewal-related features on sponsorship detail view."""
+
+    def test_create_renewal_button_shown_for_finalized(self):
+        """Finalized sponsorships show the + Renewal button."""
+        self.sponsorship.status = Sponsorship.FINALIZED
+        self.sponsorship.save(update_fields=["status"])
+        response = self.client.get(reverse("manage_sponsorship_detail", args=[self.sponsorship.pk]))
+        self.assertContains(response, "+ Renewal")
+        self.assertContains(response, "renewal=1")
+
+    def test_create_renewal_button_hidden_for_applied(self):
+        """Applied sponsorships do not show the + Renewal button."""
+        response = self.client.get(reverse("manage_sponsorship_detail", args=[self.sponsorship.pk]))
+        self.assertNotContains(response, "+ Renewal")
+
+    def test_expiring_soon_tag_shown(self):
+        """Finalized sponsorship with end_date within 90 days shows Expiring Soon tag."""
+        today = timezone.now().date()
+        self.sponsorship.status = Sponsorship.FINALIZED
+        self.sponsorship.start_date = today - datetime.timedelta(days=300)
+        self.sponsorship.end_date = today + datetime.timedelta(days=30)
+        self.sponsorship.save()
+        response = self.client.get(reverse("manage_sponsorship_detail", args=[self.sponsorship.pk]))
+        self.assertContains(response, "Expiring Soon")
+
+    def test_expired_tag_shown(self):
+        """Finalized sponsorship with end_date in past shows Expired tag."""
+        today = timezone.now().date()
+        self.sponsorship.status = Sponsorship.FINALIZED
+        self.sponsorship.start_date = today - datetime.timedelta(days=400)
+        self.sponsorship.end_date = today - datetime.timedelta(days=10)
+        self.sponsorship.save()
+        response = self.client.get(reverse("manage_sponsorship_detail", args=[self.sponsorship.pk]))
+        self.assertContains(response, "Expired")
+
+    def test_no_expiry_tag_when_not_near_end(self):
+        """Finalized sponsorship with distant end_date shows no expiry tags."""
+        today = timezone.now().date()
+        self.sponsorship.status = Sponsorship.FINALIZED
+        self.sponsorship.start_date = today - datetime.timedelta(days=100)
+        self.sponsorship.end_date = today + datetime.timedelta(days=200)
+        self.sponsorship.save()
+        response = self.client.get(reverse("manage_sponsorship_detail", args=[self.sponsorship.pk]))
+        self.assertNotContains(response, "Expiring Soon")
+        self.assertNotContains(response, ">Expired<")
+
+
+class SponsorshipListExpiryTagTests(SponsorshipReviewTestBase):
+    """Test expiry tags on sponsorship list view."""
+
+    def test_expired_tag_shown_in_list(self):
+        """Expired finalized sponsorship shows 'Expired' tag in list."""
+        today = timezone.now().date()
+        self.sponsorship.status = Sponsorship.FINALIZED
+        self.sponsorship.start_date = today - datetime.timedelta(days=400)
+        self.sponsorship.end_date = today - datetime.timedelta(days=10)
+        self.sponsorship.save()
+        response = self.client.get(reverse("manage_sponsorships") + "?status=finalized")
+        self.assertContains(response, "Expired")
+
+    def test_days_left_tag_shown_in_list(self):
+        """Expiring finalized sponsorship shows days-left tag in list."""
+        today = timezone.now().date()
+        self.sponsorship.status = Sponsorship.FINALIZED
+        self.sponsorship.start_date = today - datetime.timedelta(days=300)
+        self.sponsorship.end_date = today + datetime.timedelta(days=20)
+        self.sponsorship.save()
+        response = self.client.get(reverse("manage_sponsorships") + "?status=finalized")
+        self.assertContains(response, "d left")
+
+
+class ComposerRenewalPreFillTests(SponsorManageTestBase):
+    """Test that composer pre-fills renewal flag from query param."""
+
+    @classmethod
+    def setUpTestData(cls):
+        super().setUpTestData()
+        cls.sponsor = Sponsor.objects.create(name="Renewing Corp")
+
+    def setUp(self):
+        super().setUp()
+        self.client.login(username="staff", password="pass")
+
+    def test_renewal_flag_stored_in_session(self):
+        """Starting composer with renewal=1 stores renewal in session."""
+        self.client.get(reverse("manage_composer") + f"?new=1&sponsor_id={self.sponsor.pk}&renewal=1")
+        session_data = self.client.session.get("composer", {})
+        self.assertTrue(session_data.get("renewal"))
+
+    def test_renewal_flag_not_stored_without_param(self):
+        """Starting composer without renewal param does not store renewal."""
+        self.client.get(reverse("manage_composer") + f"?new=1&sponsor_id={self.sponsor.pk}")
+        session_data = self.client.session.get("composer", {})
+        self.assertNotIn("renewal", session_data)

apps/sponsors/manage/views.py

@@ -5,6 +5,7 @@
 
 import contextlib
 import csv
+import datetime
 import io
 import zipfile
 from tempfile import NamedTemporaryFile
@@ -16,6 +17,7 @@
 from django.http import HttpResponse
 from django.shortcuts import get_object_or_404, redirect, render
 from django.urls import reverse
+from django.utils import timezone as tz
 from django.views import View
 from django.views.generic import CreateView, DeleteView, DetailView, FormView, ListView, TemplateView, UpdateView
 
@@ -155,6 +157,31 @@ def get_context_data(self, **kwargs):
             or 0
         )
 
+        # Expiring sponsorships (finalized, end_date within 90 days from today)
+        # Cross-year: shown on every dashboard regardless of selected year
+        today = tz.now().date()
+        expiring_soon = (
+            Sponsorship.objects.filter(
+                status=Sponsorship.FINALIZED,
+                end_date__gte=today,
+                end_date__lte=today + datetime.timedelta(days=90),
+            )
+            .select_related("sponsor", "package")
+            .order_by("end_date")[:10]
+        )
+
+        # Recently expired (finalized, end_date in the past, not overlapped)
+        # Cross-year: shown on every dashboard regardless of selected year
+        recently_expired = (
+            Sponsorship.objects.filter(
+                status=Sponsorship.FINALIZED,
+                end_date__lt=today,
+                overlapped_by__isnull=True,
+            )
+            .select_related("sponsor", "package")
+            .order_by("-end_date")[:10]
+        )
+
         # Sponsors without a sponsorship for this year
         sponsors_with_sponsorship_ids = year_sponsorships.values_list("sponsor_id", flat=True) if selected_year else []
         unsponsored = (
@@ -179,7 +206,10 @@ def get_context_data(self, **kwargs):
                 "total_revenue": total_revenue,
                 "needs_review": needs_review,
                 "pending_contracts": pending_contracts,
+                "expiring_soon": expiring_soon,
+                "recently_expired": recently_expired,
                 "unsponsored": unsponsored,
+                "today": today,
             }
         )
         return context
@@ -488,6 +518,7 @@ def get_context_data(self, **kwargs):
         context["filter_status"] = self.filter_status
         context["filter_year"] = self.filter_year
         context["filter_search"] = self.filter_search
+        context["today"] = tz.now().date()
         # Individual count vars for template
         context["count_applied"] = Sponsorship.objects.filter(status=Sponsorship.APPLIED).count()
         context["count_approved"] = Sponsorship.objects.filter(status=Sponsorship.APPROVED).count()
@@ -553,6 +584,16 @@ def get_context_data(self, **kwargs):
             context["historical_contracts"] = Contract.objects.none()
         # Communication history
         context["notification_logs"] = sp.notification_logs.select_related("sent_by").all()[:20]
+        # Renewal info
+        today = tz.now().date()
+        context["today"] = today
+        context["can_create_renewal"] = sp.status == Sponsorship.FINALIZED and sp.sponsor_id is not None
+        context["is_expiring_soon"] = (
+            sp.status == Sponsorship.FINALIZED
+            and sp.end_date
+            and today <= sp.end_date <= today + datetime.timedelta(days=90)
+        )
+        context["is_expired"] = sp.status == Sponsorship.FINALIZED and sp.end_date and sp.end_date < today
         return context
 
 
@@ -1775,6 +1816,8 @@ def get(self, request):
                     data["sponsor_id"] = sponsor.pk
                 except (Sponsor.DoesNotExist, TypeError, ValueError):
                     pass
+            if request.GET.get("renewal") == "1":
+                data["renewal"] = True
             self._set_composer_data(request, data)
             # Skip to step 2 if sponsor was pre-selected
             if data.get("sponsor_id"):

apps/sponsors/templates/sponsors/manage/_base.html

@@ -292,6 +292,7 @@
         height: 24px !important;
         padding: 0 8px !important;
         font-size: 11px !important;
+        white-space: nowrap !important;
     }
 
     /* ── Tags / Badges ── */