Let parents register once and book for their children

A parent registers once and manages lessons for one or more children, who need no login of their own. A child is a real wp_users row with the student role but no usable login — so student_id keeps meaning "a WordPress user" on every table, and booking, credits, policies and enrolments work unchanged. A us_guardians link table maps guardian to child. The signup form gains a parent/guardian tick that reveals a block per child, with the account-signup questions asked per child rather than per guardian — they describe the student, not the account holder. Signup policies are recorded once per child with the guardian as the acceptor, which is the record that actually means something. A family that half-creates is rolled back entirely rather than leaving a guardian who cannot re-register. The booking and enrolment forms gain a "Who is this for?" picker listing children first, so the default selection is never the parent — booking for the wrong child is correctable, quietly billing a parent for their kid's lesson is not. POST /bookings and POST /enrollments take an optional student_id honoured only for that child's guardian; anything else is a 403. That check is the authorisation boundary of the feature. Payments and credits gain a payer: the charge names the child it was for and the guardian who owes it, so per-child reporting is unchanged while notices, receipts and the payment step reach the parent. Credit is held by the payer, so one child's cancellation can settle a sibling's charge, and the daily billing scan sends a guardian one notice covering every child. Closes #132 Co-Authored-By: Claude Opus 5 <[email protected]>
2026-07-29 16:07:52 -03:00
parent c25260a367
commit b772e1811e
71 changed files with 4192 additions and 191 deletions
@@ -42,7 +42,7 @@ class CreditRepositoryTest extends TestCase
            );
        $this->db->insert_id = 300;

-        $credit = new Credit(5, 33.0, 33.0, 'CAD', 12, 77, 'Credit for cancelled lesson #77');
+        $credit = new Credit(5, 33.0, 33.0, currency: 'CAD', sourcePaymentId: 12, sourceLessonId: 77, reason: 'Credit for cancelled lesson #77');
        self::assertSame(300, $this->repo->insert($credit));
    }

@@ -108,4 +108,67 @@ class CreditRepositoryTest extends TestCase

        $this->repo->consume(5, 0.0);
    }
+
+    /**
+     * The balance is keyed on the payer, not the student, so a guardian's
+     * account carries the credits every one of their children earned.
+     */
+    public function testAvailableBalanceQueriesThePayer(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::on(static fn (string $sql): bool => str_contains($sql, 'payer_id = %d')), 'wp_us_credits', 5, Credit::STATUS_AVAILABLE)
+            ->andReturn('sql');
+        $this->db->shouldReceive('get_var')->once()->with('sql')->andReturn('60.00');
+
+        self::assertSame(60.0, $this->repo->availableBalance(5));
+    }
+
+    public function testFindAvailableByPayerReturnsCreditsOldestFirst(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::on(static fn (string $sql): bool => str_contains($sql, 'payer_id = %d')), 'wp_us_credits', 5, Credit::STATUS_AVAILABLE)
+            ->andReturn('sql');
+        $this->db->shouldReceive('get_results')->once()->with('sql')->andReturn([
+            (object) ['id' => '1', 'student_id' => '42', 'payer_id' => '5', 'amount' => '10.00', 'remaining' => '10.00', 'currency' => 'CAD', 'source_payment_id' => null, 'source_lesson_id' => null, 'reason' => null, 'status' => Credit::STATUS_AVAILABLE, 'created_at' => '2026-07-01 09:00:00', 'updated_at' => null],
+        ]);
+
+        $credits = $this->repo->findAvailableByPayer(5);
+
+        self::assertCount(1, $credits);
+        self::assertSame(42, $credits[0]->studentId);
+        self::assertSame(5, $credits[0]->payerId);
+    }
+
+    /**
+     * Rows written before guardian accounts existed carry payer_id 0; the
+     * installer points them at the student who was always the payer.
+     */
+    public function testBackfillPayerIdsPointsLegacyRowsAtTheStudent(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with('UPDATE %i SET payer_id = student_id WHERE payer_id = 0', 'wp_us_credits')
+            ->andReturn('sql');
+        $this->db->shouldReceive('query')->once()->with('sql');
+
+        $this->repo->backfillPayerIds();
+    }
+
+    public function testInsertDefaultsThePayerToTheStudent(): void
+    {
+        Functions\when('current_time')->justReturn('2026-06-08 12:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_credits',
+                Mockery::on(static fn (array $d): bool => $d['student_id'] === 5 && $d['payer_id'] === 5),
+                Mockery::type('array')
+            );
+        $this->db->insert_id = 301;
+
+        self::assertSame(301, $this->repo->insert(new Credit(5, 10.0, 10.0)));
+    }
 }
@@ -65,7 +65,7 @@ class PaymentServiceTest extends TestCase

    private function payment(string $method, string $status, int $id): Payment
    {
-        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', $method, $status, id: $id);
+        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, currency: 'CAD', method: $method, status: $status, id: $id);
    }

    public function testFreeRegistrationCreatesNoPayment(): void
@@ -85,7 +85,7 @@ class PaymentServiceTest extends TestCase
    {
        // A scheduled (weekly/monthly) payment can cover several lessons and may be
        // collected: cancelling one lesson must never void it or trigger a rebill.
-        $scheduled = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, dueDate: '2026-07-14', id: 60);
+        $scheduled = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, dueDate: '2026-07-14', id: 60);
        $this->payments->shouldReceive('findById')->with(60)->andReturn($scheduled);
        $this->payments->shouldNotReceive('updateStatus');

@@ -252,7 +252,7 @@ class PaymentServiceTest extends TestCase

    public function testCreateIntentForEtransferReturnsDisplayDataWithoutStripe(): void
    {
-        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, etransferEmail: '[email protected]', id: 91);
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, etransferEmail: '[email protected]', id: 91);
        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 12)->andReturn($payment);

        $this->stripe->shouldNotReceive('createIntent');
@@ -348,7 +348,7 @@ class PaymentServiceTest extends TestCase
    public function testCreditForCancelledLessonCreditsWholeTotalOfSingleLessonPayment(): void
    {
        // A paid single-lesson payment: the whole total (incl. tax) is credited.
-        $paid = new Payment(5, 3, Payment::REG_LESSON, 77, 30.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PAID, taxRate: 10.0, taxAmount: 3.00, id: 12);
+        $paid = new Payment(5, 3, Payment::REG_LESSON, 77, 30.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PAID, taxRate: 10.0, taxAmount: 3.00, id: 12);
        $this->payments->shouldReceive('findById')->with(12)->andReturn($paid);
        $this->bookings->shouldReceive('countByPaymentId')->with(12)->andReturn(1);
        $this->credits->shouldReceive('existsForLesson')->with(77)->andReturn(false);
@@ -361,7 +361,7 @@ class PaymentServiceTest extends TestCase
                && $c->sourceLessonId === 77))
            ->andReturn(300);
        $this->credits->shouldReceive('findById')->with(300)->andReturn(
-            new Credit(5, 33.00, 33.00, 'CAD', 12, 77, id: 300)
+            new Credit(5, 33.00, 33.00, currency: 'CAD', sourcePaymentId: 12, sourceLessonId: 77, id: 300)
        );

        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_CANCELLED, paymentId: 12, id: 77);
@@ -371,7 +371,7 @@ class PaymentServiceTest extends TestCase
    public function testCreditForCancelledLessonSplitsSharedMonthlyPayment(): void
    {
        // A monthly scheduled charge covering 3 lessons: one cancellation credits a third.
-        $paid = new Payment(5, 3, Payment::REG_LESSON, 201, 90.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PAID, dueDate: '2026-07-01', id: 12);
+        $paid = new Payment(5, 3, Payment::REG_LESSON, 201, 90.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PAID, dueDate: '2026-07-01', id: 12);
        $this->payments->shouldReceive('findById')->with(12)->andReturn($paid);
        $this->bookings->shouldReceive('countByPaymentId')->with(12)->andReturn(3);
        $this->credits->shouldReceive('existsForLesson')->with(202)->andReturn(false);
@@ -380,7 +380,7 @@ class PaymentServiceTest extends TestCase
            ->once()
            ->with(Mockery::on(static fn (Credit $c): bool => $c->amount === 30.00))
            ->andReturn(301);
-        $this->credits->shouldReceive('findById')->with(301)->andReturn(new Credit(5, 30.00, 30.00, 'CAD', 12, 202, id: 301));
+        $this->credits->shouldReceive('findById')->with(301)->andReturn(new Credit(5, 30.00, 30.00, currency: 'CAD', sourcePaymentId: 12, sourceLessonId: 202, id: 301));

        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, status: Lesson::STATUS_CANCELLED, paymentId: 12, id: 202);
        self::assertNotNull($this->service->creditForCancelledLesson($lesson));
@@ -388,7 +388,7 @@ class PaymentServiceTest extends TestCase

    public function testCreditForCancelledLessonSkipsUnpaidPayment(): void
    {
-        $pending = new Payment(5, 3, Payment::REG_LESSON, 77, 30.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, id: 12);
+        $pending = new Payment(5, 3, Payment::REG_LESSON, 77, 30.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12);
        $this->payments->shouldReceive('findById')->with(12)->andReturn($pending);
        $this->credits->shouldNotReceive('insert');

@@ -406,7 +406,7 @@ class PaymentServiceTest extends TestCase

    public function testCreditForCancelledLessonSkipsAlreadyCredited(): void
    {
-        $paid = new Payment(5, 3, Payment::REG_LESSON, 77, 30.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PAID, id: 12);
+        $paid = new Payment(5, 3, Payment::REG_LESSON, 77, 30.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PAID, id: 12);
        $this->payments->shouldReceive('findById')->with(12)->andReturn($paid);
        $this->bookings->shouldReceive('countByPaymentId')->with(12)->andReturn(1);
        $this->credits->shouldReceive('existsForLesson')->with(77)->andReturn(true);
@@ -420,7 +420,7 @@ class PaymentServiceTest extends TestCase
    {
        // A non-anchor series lesson has no payment_id of its own; the anchor's
        // upfront (unscheduled) payment covers the whole 4-lesson series.
-        $anchorPayment = new Payment(5, 3, Payment::REG_LESSON, 40, 120.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PAID, id: 12);
+        $anchorPayment = new Payment(5, 3, Payment::REG_LESSON, 40, 120.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PAID, id: 12);
        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 40)->andReturn($anchorPayment);
        $this->payments->shouldReceive('findById')->with(12)->andReturn($anchorPayment);
        $this->bookings->shouldReceive('countBySeries')->with(40)->andReturn(4);
@@ -430,7 +430,7 @@ class PaymentServiceTest extends TestCase
            ->once()
            ->with(Mockery::on(static fn (Credit $c): bool => $c->amount === 30.00))
            ->andReturn(302);
-        $this->credits->shouldReceive('findById')->with(302)->andReturn(new Credit(5, 30.00, 30.00, 'CAD', 12, 43, id: 302));
+        $this->credits->shouldReceive('findById')->with(302)->andReturn(new Credit(5, 30.00, 30.00, currency: 'CAD', sourcePaymentId: 12, sourceLessonId: 43, id: 302));

        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, recurrence: Lesson::RECURRENCE_WEEKLY, seriesId: 40, paymentId: null, id: 43);
        self::assertNotNull($this->service->creditForCancelledLesson($lesson));
@@ -487,7 +487,7 @@ class PaymentServiceTest extends TestCase

    private function pending(int $id, float $amount): Payment
    {
-        return new Payment(5, 3, Payment::REG_LESSON, 12, $amount, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, dueDate: '2026-07-14', id: $id);
+        return new Payment(5, 3, Payment::REG_LESSON, 12, $amount, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, dueDate: '2026-07-14', id: $id);
    }

    private function intentEvent(string $type, string $intentId): \Stripe\Event
@@ -496,4 +496,85 @@ class PaymentServiceTest extends TestCase

        return \Stripe\Event::constructFrom(['type' => $type, 'data' => ['object' => $intent]]);
    }
+
+    /**
+     * The billing method resolves against the payer, so comping or card-billing a
+     * family is one setting on the guardian rather than one per child.
+     */
+    public function testCreateForRegistrationResolvesTheBillingMethodAgainstThePayer(): void
+    {
+        $this->resolver->shouldReceive('resolve')->once()->with(5)->andReturn(Payment::METHOD_ETRANSFER);
+        $this->settings->shouldReceive('etransferEmail')->andReturn('');
+        $this->settings->shouldReceive('hstRate')->andReturn(0.0);
+
+        $this->payments->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Payment $p): bool => $p->studentId === 42 && $p->payerId === 5))
+            ->andReturn(90);
+        $this->bookings->shouldReceive('setPaymentId')->once();
+        $this->payments->shouldReceive('findById')->with(90)->andReturn(
+            new Payment(42, 3, Payment::REG_LESSON, 12, 35.00, payerId: 5, id: 90)
+        );
+
+        $payment = $this->service->createForRegistration(Payment::REG_LESSON, 12, 42, 3, 35.00, 'CAD', payerId: 5);
+
+        self::assertSame(5, $payment?->payerId);
+    }
+
+    /**
+     * A credit earned by a child lands on the guardian's balance, so one child's
+     * cancellation can settle a sibling's next charge.
+     */
+    public function testCancelledChildLessonCreditsTheGuardiansBalance(): void
+    {
+        $lesson = new Lesson(slotId: 10, studentId: 42, instructorId: 3, paymentId: 12, id: 77);
+        $paid   = new Payment(42, 3, Payment::REG_LESSON, 77, 30.00, payerId: 5, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PAID, id: 12);
+
+        $this->payments->shouldReceive('findById')->with(12)->andReturn($paid);
+        $this->credits->shouldReceive('existsForLesson')->with(77)->andReturn(false);
+        $this->bookings->shouldReceive('countByPaymentId')->with(12)->andReturn(1);
+
+        $this->credits->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Credit $c): bool => $c->studentId === 42 && $c->payerId === 5 && $c->amount === 30.0))
+            ->andReturn(300);
+        $this->credits->shouldReceive('findById')->with(300)->andReturn(
+            new Credit(42, 30.00, 30.00, payerId: 5, id: 300)
+        );
+
+        self::assertNotNull($this->service->creditForCancelledLesson($lesson));
+    }
+
+    public function testApplyCreditsDrawsDownThePayersBalanceAcrossChildrensCharges(): void
+    {
+        $this->credits->shouldReceive('availableBalance')->with(5)->andReturn(60.0);
+
+        $adasCharge  = new Payment(42, 3, Payment::REG_LESSON, 12, 30.00, payerId: 5, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, dueDate: '2026-07-14', id: 91);
+        $alansCharge = new Payment(43, 3, Payment::REG_LESSON, 13, 30.00, payerId: 5, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, dueDate: '2026-07-14', id: 92);
+
+        $this->payments->shouldReceive('addCreditApplied')->once()->with(91, 30.0);
+        $this->payments->shouldReceive('addCreditApplied')->once()->with(92, 30.0);
+        $this->payments->shouldReceive('markPaid')->twice();
+        $this->bookings->shouldReceive('findById')->andReturn(null);
+        $this->bookings->shouldReceive('updateStatus')->twice();
+        $this->credits->shouldReceive('consume')->once()->with(5, 60.0);
+
+        $applied = $this->service->applyCredits(5, [$adasCharge, $alansCharge]);
+
+        self::assertSame([91 => 30.0, 92 => 30.0], $applied);
+    }
+
+    /**
+     * A guardian paying for their child's lesson must reach the payment step;
+     * anyone else must not.
+     */
+    public function testCreateIntentIsAllowedForBothTheStudentAndTheirPayer(): void
+    {
+        $payment = new Payment(42, 3, Payment::REG_LESSON, 12, 35.00, payerId: 5, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 91);
+        $this->payments->shouldReceive('findByRegistration')->andReturn($payment);
+
+        self::assertNotNull($this->service->createIntent(Payment::REG_LESSON, 12, 42));
+        self::assertNotNull($this->service->createIntent(Payment::REG_LESSON, 12, 5));
+        self::assertNull($this->service->createIntent(Payment::REG_LESSON, 12, 99));
+    }
 }
@@ -8,6 +8,7 @@ use Mockery;
 use Unsupervised\Schedular\Booking\BookingRepository;
 use Unsupervised\Schedular\GroupClass\Enrollment;
 use Unsupervised\Schedular\GroupClass\EnrollmentRepository;
+use Unsupervised\Schedular\Guardian\GuardianService;
 use Unsupervised\Schedular\Offering\Offering;
 use Unsupervised\Schedular\Offering\OfferingRepository;
 use Unsupervised\Schedular\Payment\Payment;
@@ -18,6 +19,7 @@ use Unsupervised\Schedular\Tests\Unit\TestCase;

 class ScheduledBillingRunnerTest extends TestCase
 {
+    private GuardianService&Mockery\MockInterface $guardians;
    private PaymentService $payments;
    private BookingRepository $bookings;
    private EnrollmentRepository $enrollments;
@@ -49,12 +51,17 @@ class ScheduledBillingRunnerTest extends TestCase
        $student->user_email = '[email protected]';
        Functions\when('get_userdata')->justReturn($student);

+        $this->guardians = Mockery::mock(GuardianService::class);
+        $this->guardians->shouldReceive('payerFor')->andReturnUsing(static fn (int $id): int => $id)->byDefault();
+        $this->guardians->shouldReceive('studentName')->andReturn('Ada')->byDefault();
+
        $this->runner = new ScheduledBillingRunner(
            $this->payments,
            $this->bookings,
            $this->enrollments,
            $this->offerings,
-            $this->mailer
+            $this->mailer,
+            $this->guardians
        );
    }

@@ -65,7 +72,7 @@ class ScheduledBillingRunnerTest extends TestCase

    private function pending(int $id, string $due): Payment
    {
-        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, dueDate: $due, id: $id);
+        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, dueDate: $due, id: $id);
    }

    private function lessonRow(int $id, string $mode, string $start, float $price, int $offeringId = 9): object
@@ -92,7 +99,7 @@ class ScheduledBillingRunnerTest extends TestCase

        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_LESSON, 101, 5, 3, 35.0, 'CAD', '[email protected]', '2026-07-14', '2026-07-15')
+            ->with(Payment::REG_LESSON, 101, 5, 3, 35.0, 'CAD', '[email protected]', '2026-07-14', '2026-07-15', 5)
            ->andReturn($this->pending(500, '2026-07-14'));

        $this->mailer->shouldReceive('send')->once();
@@ -124,7 +131,7 @@ class ScheduledBillingRunnerTest extends TestCase
        // One payment for the month: 3 x 30, due on the 1st, linked to the earliest.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_LESSON, 201, 5, 3, 90.0, 'CAD', '[email protected]', '2026-07-01', '2026-07')
+            ->with(Payment::REG_LESSON, 201, 5, 3, 90.0, 'CAD', '[email protected]', '2026-07-01', '2026-07', 5)
            ->andReturn($this->pending(600, '2026-07-01'));

        // The other two lessons are pointed at the same payment so they are not re-billed.
@@ -158,11 +165,11 @@ class ScheduledBillingRunnerTest extends TestCase

        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-06', '2026-07-07')
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-06', '2026-07-07', 5)
            ->andReturn($this->pending(700, '2026-07-06'));
        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-13', '2026-07-14')
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-13', '2026-07-14', 5)
            ->andReturn($this->pending(701, '2026-07-13'));

        $this->runner->run();
@@ -181,7 +188,7 @@ class ScheduledBillingRunnerTest extends TestCase

        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-13', '2026-07-14')
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-13', '2026-07-14', 5)
            ->andReturn($this->pending(701, '2026-07-13'));

        $this->runner->run();
@@ -205,7 +212,7 @@ class ScheduledBillingRunnerTest extends TestCase
        // One payment of the monthly fee — not 4 x 20 — due on the 1st.
        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-01', '2026-07')
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-01', '2026-07', 5)
            ->andReturn($this->pending(800, '2026-07-01'));

        $this->runner->run();
@@ -227,7 +234,7 @@ class ScheduledBillingRunnerTest extends TestCase

        $this->payments->shouldReceive('createForRegistration')
            ->once()
-            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-01', '2026-07')
+            ->with(Payment::REG_ENROLLMENT, 44, 5, 3, 20.0, 'CAD', null, '2026-07-01', '2026-07', 5)
            ->andReturn($this->pending(800, '2026-07-01'));

        $this->runner->run();
@@ -240,7 +247,7 @@ class ScheduledBillingRunnerTest extends TestCase
            ->andReturn([ $this->lessonRow(101, Offering::BILLING_WEEKLY, '2026-07-15 18:00:00', 35.0) ]);

        // A comp student's payment comes back paid — no due notice should be sent.
-        $comp = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_COMP, Payment::STATUS_PAID, dueDate: '2026-07-14', id: 900);
+        $comp = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, currency: 'CAD', method: Payment::METHOD_COMP, status: Payment::STATUS_PAID, dueDate: '2026-07-14', id: 900);
        $this->payments->shouldReceive('createForRegistration')->once()->andReturn($comp);

        $this->mailer->shouldNotReceive('send');
@@ -333,4 +340,92 @@ class ScheduledBillingRunnerTest extends TestCase
            id:              9,
        );
    }
+
+    /**
+     * Two children billed on the same day belong to one payer, so the guardian
+     * gets a single notice covering both — not one email per child — and each
+     * line names whose lesson it is.
+     */
+    public function testAGuardiansChildrenShareOneNoticeWithNamedLines(): void
+    {
+        $this->now('2026-07-15 09:00:00');
+
+        $adas  = $this->lessonRow(101, Offering::BILLING_WEEKLY, '2026-07-15 18:00:00', 35.0);
+        $alans = $this->lessonRow(102, Offering::BILLING_WEEKLY, '2026-07-15 19:00:00', 35.0);
+        $adas->student_id  = '42';
+        $alans->student_id = '43';
+
+        $this->bookings->shouldReceive('findUnbilledScheduledLessons')->andReturn([$adas, $alans]);
+
+        $this->guardians->shouldReceive('payerFor')->with(42)->andReturn(5);
+        $this->guardians->shouldReceive('payerFor')->with(43)->andReturn(5);
+        $this->guardians->shouldReceive('studentName')->with(42)->andReturn('Ada');
+        $this->guardians->shouldReceive('studentName')->with(43)->andReturn('Alan');
+
+        $this->payments->shouldReceive('createForRegistration')
+            ->andReturn($this->pending(500, '2026-07-14'), $this->pending(501, '2026-07-14'));
+
+        // One send, two lines, each prefixed with the child it is for.
+        $this->mailer->shouldReceive('send')
+            ->once()
+            ->with(
+                Mockery::type(\WP_User::class),
+                Mockery::on(static function (array $items): bool {
+                    return count($items) === 2
+                        && str_starts_with((string) $items[0]['label'], 'Ada: ')
+                        && str_starts_with((string) $items[1]['label'], 'Alan: ');
+                }),
+                Mockery::type('string'),
+                0.0
+            );
+
+        $this->runner->run();
+    }
+
+    /**
+     * A student who pays for themselves gets the plain label — prefixing every
+     * line with their own name would be noise.
+     */
+    public function testAStudentPayingForThemselvesGetsAnUnprefixedLabel(): void
+    {
+        $this->now('2026-07-15 09:00:00');
+        $this->bookings->shouldReceive('findUnbilledScheduledLessons')
+            ->andReturn([$this->lessonRow(101, Offering::BILLING_WEEKLY, '2026-07-15 18:00:00', 35.0)]);
+
+        $this->payments->shouldReceive('createForRegistration')->andReturn($this->pending(500, '2026-07-14'));
+
+        $this->mailer->shouldReceive('send')
+            ->once()
+            ->with(
+                Mockery::type(\WP_User::class),
+                Mockery::on(static fn (array $items): bool => str_starts_with((string) $items[0]['label'], 'Piano — ')),
+                Mockery::type('string'),
+                0.0
+            );
+
+        $this->runner->run();
+    }
+
+    /**
+     * The family balance is drawn against the payer, so a credit one child
+     * earned can settle a sibling's charge.
+     */
+    public function testCreditsAreAppliedAgainstThePayerNotEachStudent(): void
+    {
+        $this->now('2026-07-15 09:00:00');
+
+        $adas = $this->lessonRow(101, Offering::BILLING_WEEKLY, '2026-07-15 18:00:00', 35.0);
+        $adas->student_id = '42';
+
+        $this->bookings->shouldReceive('findUnbilledScheduledLessons')->andReturn([$adas]);
+        $this->guardians->shouldReceive('payerFor')->with(42)->andReturn(5);
+        $this->guardians->shouldReceive('studentName')->with(42)->andReturn('Ada');
+
+        $this->payments->shouldReceive('createForRegistration')->andReturn($this->pending(500, '2026-07-14'));
+        $this->payments->shouldReceive('applyCredits')->once()->with(5, Mockery::type('array'))->andReturn([]);
+
+        $this->mailer->shouldReceive('send')->once();
+
+        $this->runner->run();
+    }
 }
@@ -29,7 +29,7 @@ class StripeGatewayTest extends TestCase

    private function payment(): Payment
    {
-        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_CARD, Payment::STATUS_PENDING, id: 90);
+        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, currency: 'CAD', method: Payment::METHOD_CARD, status: Payment::STATUS_PENDING, id: 90);
    }

    public function testCreateIntentReturnsNullWhenNotConfigured(): void