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
@@ -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();
+    }
 }