Reconcile up-front charges when a class switches to monthly billing

A student who enrols while a group class is pay-now is charged once at
enrolment, and that charge carries no period_key. When the class is
later switched to monthly, the daily scan — which dedups scheduled
charges by period_key — does not see the up-front charge and bills the
enrolment again for the current month, double-charging students who
had already paid. The differing payer between the two rows (student vs
guardian) was a side effect of guardian links created between the two
charge dates, not the cause.

Switching a group class into monthly now adopts each active enrolment's
up-front charge into the current month (stamping period_key and
due_date) so the scan treats that month as billed and charges from the
next month on. Enrolments with no up-front charge, or already billed
for the month, are left alone; weekly and non-group offerings are not
touched. Wired into both offering-update paths (admin form and REST).

Co-authored-by: anthropic/claude-opus-4-8

tests/Unit/Offering/BillingModeReconcilerTest.php

@@ -0,0 +1,136 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Offering;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\GroupClass\Enrollment;
+use Unsupervised\Schedular\GroupClass\EnrollmentRepository;
+use Unsupervised\Schedular\Offering\BillingModeReconciler;
+use Unsupervised\Schedular\Offering\Offering;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\PaymentRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class BillingModeReconcilerTest extends TestCase
+{
+    private EnrollmentRepository&Mockery\MockInterface $enrollments;
+    private PaymentRepository&Mockery\MockInterface $payments;
+    private BillingModeReconciler $reconciler;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        Functions\when('current_time')->justReturn('2026-09-15 09:00:00');
+
+        $this->enrollments = Mockery::mock(EnrollmentRepository::class);
+        $this->payments    = Mockery::mock(PaymentRepository::class);
+        $this->reconciler  = new BillingModeReconciler($this->enrollments, $this->payments);
+    }
+
+    private function offering(string $billingMode, ?int $id = 9): Offering
+    {
+        return new Offering(
+            instructorId: 3,
+            kind:         Offering::KIND_GROUP_CLASS,
+            title:        'Ensemble',
+            price:        150.0,
+            billingMode:  $billingMode,
+            id:           $id,
+        );
+    }
+
+    private function enrollment(int $id, int $studentId = 5): Enrollment
+    {
+        return new Enrollment(offeringId: 9, studentId: $studentId, instructorId: 3, id: $id);
+    }
+
+    public function testAdoptsUpfrontChargeIntoCurrentMonthWhenClassBecomesMonthly(): void
+    {
+        $this->enrollments->shouldReceive('findActiveByOffering')->with(9)->andReturn([$this->enrollment(7)]);
+
+        $this->payments->shouldReceive('hasUnscheduledCharge')->with(Payment::REG_ENROLLMENT, 7)->andReturn(true);
+        $this->payments->shouldReceive('existsForPeriod')->with(Payment::REG_ENROLLMENT, 7, '2026-09')->andReturn(false);
+
+        // The up-front charge is stamped into 2026-09, due on the 1st, so the scan
+        // treats September as already billed for this enrolment.
+        $this->payments->shouldReceive('claimPeriodForUnscheduled')
+            ->once()
+            ->with(Payment::REG_ENROLLMENT, 7, '2026-09', '2026-09-01')
+            ->andReturn(1);
+
+        self::assertSame(1, $this->reconciler->reconcile($this->offering(Offering::BILLING_ONE_TIME), $this->offering(Offering::BILLING_MONTHLY)));
+    }
+
+    public function testDoesNothingWhenBillingModeDidNotChangeIntoMonthly(): void
+    {
+        $this->enrollments->shouldNotReceive('findActiveByOffering');
+        $this->payments->shouldNotReceive('claimPeriodForUnscheduled');
+
+        // Already monthly -> monthly (e.g. an unrelated title edit): no transition.
+        self::assertSame(0, $this->reconciler->reconcile($this->offering(Offering::BILLING_MONTHLY), $this->offering(Offering::BILLING_MONTHLY)));
+    }
+
+    public function testDoesNothingWhenSwitchingToWeekly(): void
+    {
+        $this->enrollments->shouldNotReceive('findActiveByOffering');
+        $this->payments->shouldNotReceive('claimPeriodForUnscheduled');
+
+        // Weekly bills per session as sessions come due; there is no single upfront
+        // period an enrolment charge maps onto, so it is left alone.
+        self::assertSame(0, $this->reconciler->reconcile($this->offering(Offering::BILLING_ONE_TIME), $this->offering(Offering::BILLING_WEEKLY)));
+    }
+
+    public function testSkipsEnrolmentWithoutAnUpfrontCharge(): void
+    {
+        $this->enrollments->shouldReceive('findActiveByOffering')->with(9)->andReturn([$this->enrollment(7)]);
+
+        // Enrolled after the class was already scheduled, or never charged upfront:
+        // nothing to adopt.
+        $this->payments->shouldReceive('hasUnscheduledCharge')->with(Payment::REG_ENROLLMENT, 7)->andReturn(false);
+        $this->payments->shouldNotReceive('claimPeriodForUnscheduled');
+
+        self::assertSame(0, $this->reconciler->reconcile($this->offering(Offering::BILLING_ONE_TIME), $this->offering(Offering::BILLING_MONTHLY)));
+    }
+
+    public function testSkipsEnrolmentAlreadyBilledForThisMonthByTheScan(): void
+    {
+        $this->enrollments->shouldReceive('findActiveByOffering')->with(9)->andReturn([$this->enrollment(7)]);
+
+        $this->payments->shouldReceive('hasUnscheduledCharge')->with(Payment::REG_ENROLLMENT, 7)->andReturn(true);
+        // The scan already made a 2026-09 charge: adopting the upfront one too would
+        // leave two charges for the month — the very thing we are preventing.
+        $this->payments->shouldReceive('existsForPeriod')->with(Payment::REG_ENROLLMENT, 7, '2026-09')->andReturn(true);
+        $this->payments->shouldNotReceive('claimPeriodForUnscheduled');
+
+        self::assertSame(0, $this->reconciler->reconcile($this->offering(Offering::BILLING_ONE_TIME), $this->offering(Offering::BILLING_MONTHLY)));
+    }
+
+    public function testReconcilesEveryActiveEnrolment(): void
+    {
+        $this->enrollments->shouldReceive('findActiveByOffering')->with(9)
+            ->andReturn([$this->enrollment(7, 5), $this->enrollment(8, 6)]);
+
+        $this->payments->shouldReceive('hasUnscheduledCharge')->with(Payment::REG_ENROLLMENT, 7)->andReturn(true);
+        $this->payments->shouldReceive('existsForPeriod')->with(Payment::REG_ENROLLMENT, 7, '2026-09')->andReturn(false);
+        $this->payments->shouldReceive('claimPeriodForUnscheduled')->with(Payment::REG_ENROLLMENT, 7, '2026-09', '2026-09-01')->andReturn(1);
+
+        $this->payments->shouldReceive('hasUnscheduledCharge')->with(Payment::REG_ENROLLMENT, 8)->andReturn(true);
+        $this->payments->shouldReceive('existsForPeriod')->with(Payment::REG_ENROLLMENT, 8, '2026-09')->andReturn(false);
+        $this->payments->shouldReceive('claimPeriodForUnscheduled')->with(Payment::REG_ENROLLMENT, 8, '2026-09', '2026-09-01')->andReturn(1);
+
+        self::assertSame(2, $this->reconciler->reconcile($this->offering(Offering::BILLING_ONE_TIME), $this->offering(Offering::BILLING_MONTHLY)));
+    }
+
+    public function testIgnoresNonGroupClassOfferings(): void
+    {
+        $before = new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Piano', billingMode: Offering::BILLING_ONE_TIME, id: 9);
+        $after  = new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Piano', billingMode: Offering::BILLING_MONTHLY, id: 9);
+
+        $this->enrollments->shouldNotReceive('findActiveByOffering');
+
+        self::assertSame(0, $this->reconciler->reconcile($before, $after));
+    }
+}

tests/Unit/Offering/OfferingControllerTest.php

@@ -5,6 +5,7 @@ namespace Unsupervised\Schedular\Tests\Unit\Offering;
 
 use Brain\Monkey\Functions;
 use Mockery;
+use Unsupervised\Schedular\Offering\BillingModeReconciler;
 use Unsupervised\Schedular\Offering\ClassSlotReconciler;
 use Unsupervised\Schedular\Offering\Offering;
 use Unsupervised\Schedular\Offering\OfferingController;
@@ -15,6 +16,7 @@ class OfferingControllerTest extends TestCase
 {
     private OfferingRepository&Mockery\MockInterface $repository;
     private ClassSlotReconciler&Mockery\MockInterface $reconciler;
+    private BillingModeReconciler&Mockery\MockInterface $billingModeReconciler;
     private OfferingController $controller;
 
     protected function setUp(): void
@@ -24,7 +26,9 @@ class OfferingControllerTest extends TestCase
         $this->repository = Mockery::mock(OfferingRepository::class);
         $this->reconciler = Mockery::mock(ClassSlotReconciler::class);
         $this->reconciler->shouldReceive('reconcile')->andReturn(['removed' => 0, 'conflicts' => []])->byDefault();
-        $this->controller = new OfferingController($this->repository, $this->reconciler);
+        $this->billingModeReconciler = Mockery::mock(BillingModeReconciler::class);
+        $this->billingModeReconciler->shouldReceive('reconcile')->andReturn(0)->byDefault();
+        $this->controller = new OfferingController($this->repository, $this->reconciler, $this->billingModeReconciler);
 
         $_POST = [];
         $_GET  = [];

tests/Unit/Offering/OfferingEndpointTest.php

@@ -7,6 +7,7 @@ use Brain\Monkey\Functions;
 use Mockery;
 use Unsupervised\Schedular\Auth\RoleManager;
 use Unsupervised\Schedular\GroupClass\GroupAccessRepository;
+use Unsupervised\Schedular\Offering\BillingModeReconciler;
 use Unsupervised\Schedular\Offering\Offering;
 use Unsupervised\Schedular\Offering\OfferingEndpoint;
 use Unsupervised\Schedular\Offering\OfferingRepository;
@@ -16,6 +17,7 @@ class OfferingEndpointTest extends TestCase
 {
     private OfferingRepository&Mockery\MockInterface $repository;
     private GroupAccessRepository&Mockery\MockInterface $access;
+    private BillingModeReconciler&Mockery\MockInterface $billingModeReconciler;
     private OfferingEndpoint $endpoint;
 
     protected function setUp(): void
@@ -27,7 +29,9 @@ class OfferingEndpointTest extends TestCase
 
         $this->repository = Mockery::mock(OfferingRepository::class);
         $this->access     = Mockery::mock(GroupAccessRepository::class);
-        $this->endpoint   = new OfferingEndpoint($this->repository, $this->access);
+        $this->billingModeReconciler = Mockery::mock(BillingModeReconciler::class);
+        $this->billingModeReconciler->shouldReceive('reconcile')->andReturn(0)->byDefault();
+        $this->endpoint   = new OfferingEndpoint($this->repository, $this->access, $this->billingModeReconciler);
     }
 
     private function group(int $id, string $access): Offering