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]>

tests/Unit/Booking/BookingEndpointTest.php

@@ -11,16 +11,19 @@ use Unsupervised\Schedular\Booking\BookingEndpoint;
 use Unsupervised\Schedular\Booking\BookingRepository;
 use Unsupervised\Schedular\Booking\CancellationPolicy;
 use Unsupervised\Schedular\Booking\Lesson;
+use Unsupervised\Schedular\Guardian\GuardianService;
 use Unsupervised\Schedular\Offering\Offering;
 use Unsupervised\Schedular\Offering\OfferingRepository;
 use Unsupervised\Schedular\Payment\Payment;
 use Unsupervised\Schedular\Payment\PaymentService;
 use Unsupervised\Schedular\Payment\StudioSettings;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
 use Unsupervised\Schedular\Registration\RegistrationGate;
 use Unsupervised\Schedular\Tests\Unit\TestCase;
 
 class BookingEndpointTest extends TestCase
 {
+    private GuardianService&Mockery\MockInterface $guardians;
     private AvailabilityRepository $availability;
     private BookingRepository $bookings;
     private OfferingRepository $offerings;
@@ -52,6 +55,14 @@ class BookingEndpointTest extends TestCase
         // cancellation paths simply allow the call.
         $this->payments->shouldReceive('creditForCancelledLesson')->andReturn(null)->byDefault();
 
+        $this->guardians = Mockery::mock(GuardianService::class);
+        // The default account books only for itself: no guardian link anywhere.
+        $this->guardians->shouldReceive('canActFor')
+            ->andReturnUsing(static fn (int $actor, int $student): bool => $actor === $student)->byDefault();
+        $this->guardians->shouldReceive('payerFor')->andReturnUsing(static fn (int $id): int => $id)->byDefault();
+        $this->guardians->shouldReceive('householdIds')->andReturnUsing(static fn (int $id): array => [$id])->byDefault();
+        $this->guardians->shouldReceive('studentName')->andReturn('Ada')->byDefault();
+
         $this->endpoint = new BookingEndpoint(
             $this->availability,
             $this->bookings,
@@ -59,6 +70,7 @@ class BookingEndpointTest extends TestCase
             $this->gate,
             $this->payments,
             new CancellationPolicy($this->settings),
+            $this->guardians,
         );
     }
 
@@ -182,7 +194,7 @@ class BookingEndpointTest extends TestCase
         $this->gate->shouldReceive('record')->once();
         $this->payments->shouldReceive('createForRegistration')
             ->once()
-            ->with(Payment::REG_LESSON, 77, 5, 3, 50.0, 'CAD', null)
+            ->with(Payment::REG_LESSON, 77, 5, 3, 50.0, 'CAD', null, null, null, 5)
             ->andReturn(new Payment(
                 studentId:        5,
                 instructorId:     3,
@@ -260,7 +272,7 @@ class BookingEndpointTest extends TestCase
         $this->gate->shouldReceive('record')->once();
         $this->payments->shouldReceive('createForRegistration')
             ->once()
-            ->with(Payment::REG_LESSON, 77, 5, 3, 50.0, 'CAD', null)
+            ->with(Payment::REG_LESSON, 77, 5, 3, 50.0, 'CAD', null, null, null, 5)
             ->andReturn(new Payment(
                 studentId:        5,
                 instructorId:     3,
@@ -336,8 +348,8 @@ class BookingEndpointTest extends TestCase
         // Three claimed occurrences at a per-lesson (one_time) price of 50 → 150.
         $this->payments->shouldReceive('createForRegistration')
             ->once()
-            ->with(Payment::REG_LESSON, 77, 5, 3, 150.0, 'CAD', null)
-            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 150.0, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, id: 12));
+            ->with(Payment::REG_LESSON, 77, 5, 3, 150.0, 'CAD', null, null, null, 5)
+            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 150.0, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
         $this->bookings->shouldNotReceive('updateStatus');
 
         $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'recurrence' => 'weekly']);
@@ -375,8 +387,8 @@ class BookingEndpointTest extends TestCase
         // A full_term price already covers the whole reservation.
         $this->payments->shouldReceive('createForRegistration')
             ->once()
-            ->with(Payment::REG_LESSON, 77, 5, 3, 400.0, 'CAD', null)
-            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 400.0, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, id: 12));
+            ->with(Payment::REG_LESSON, 77, 5, 3, 400.0, 'CAD', null, null, null, 5)
+            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 400.0, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
         $this->bookings->shouldNotReceive('updateStatus');
 
         $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'recurrence' => 'weekly']);
@@ -427,8 +439,8 @@ class BookingEndpointTest extends TestCase
         // Charged now, for a single lesson's fee, as a normal (non-scheduled) payment.
         $this->payments->shouldReceive('createForRegistration')
             ->once()
-            ->with(Payment::REG_LESSON, 77, 5, 3, 45.0, 'CAD', null)
-            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 45.0, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, id: 12));
+            ->with(Payment::REG_LESSON, 77, 5, 3, 45.0, 'CAD', null, null, null, 5)
+            ->andReturn(new Payment(5, 3, Payment::REG_LESSON, 77, 45.0, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
         $this->bookings->shouldNotReceive('updateStatus');
 
         $result = $this->endpoint->book(new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8]));
@@ -657,4 +669,131 @@ class BookingEndpointTest extends TestCase
         self::assertSame('Piano Lesson', $data[0]['offering_title']);
         self::assertSame(60, $data[0]['duration_minutes']);
     }
+
+    /**
+     * The authorisation boundary of guardian booking: without it any signed-in
+     * student could book — and bill — against any user id they cared to send.
+     */
+    public function testBookForAStudentTheCallerDoesNotGuardIsForbidden(): void
+    {
+        $this->guardians->shouldReceive('canActFor')->with(5, 99)->andReturn(false);
+
+        // Rejected before anything is looked up, claimed, or charged.
+        $this->availability->shouldNotReceive('findById');
+        $this->availability->shouldNotReceive('claim');
+        $this->bookings->shouldNotReceive('insert');
+        $this->payments->shouldNotReceive('createForRegistration');
+
+        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'student_id' => 99]);
+        $result  = $this->endpoint->book($request);
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('forbidden', $result->get_error_code());
+    }
+
+    public function testGuardianBooksTheLessonInTheChildsNameAndBillsThemselves(): void
+    {
+        $this->guardians->shouldReceive('canActFor')->with(5, 42)->andReturn(true);
+        $this->guardians->shouldReceive('payerFor')->with(42)->andReturn(5);
+
+        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
+        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
+            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 50.0, id: 8)
+        );
+        $this->gate->shouldReceive('validate')->andReturn(null);
+        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
+
+        // The lesson belongs to the child…
+        $this->bookings->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Lesson $l): bool => $l->studentId === 42))
+            ->andReturn(77);
+
+        // …the acceptance names the child but is attributed to the guardian…
+        $this->gate->shouldReceive('record')
+            ->once()
+            ->with(PolicyAcceptance::REG_LESSON, 77, 42, 8, Mockery::any(), Mockery::any(), Mockery::any(), 5);
+
+        // …and the charge is raised against the child but owed by the guardian.
+        $this->payments->shouldReceive('createForRegistration')
+            ->once()
+            ->with(Payment::REG_LESSON, 77, 42, 3, 50.0, 'CAD', null, null, null, 5)
+            ->andReturn(new Payment(42, 3, Payment::REG_LESSON, 77, 50.0, payerId: 5, currency: 'CAD', method: Payment::METHOD_ETRANSFER, status: Payment::STATUS_PENDING, id: 12));
+
+        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'student_id' => 42]);
+        $result  = $this->endpoint->book($request);
+
+        self::assertInstanceOf(\WP_REST_Response::class, $result);
+        self::assertSame(201, $result->get_status());
+    }
+
+    /**
+     * Sending your own id explicitly is the same as sending none — no guardian
+     * lookup is needed to book for yourself.
+     */
+    public function testBookForYourOwnIdNeedsNoGuardianLink(): void
+    {
+        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
+        $this->offerings->shouldReceive('findById')->with(8)->andReturn(
+            new Offering(instructorId: 3, kind: Offering::KIND_PRIVATE_LESSON, title: 'Lesson', price: 0.0, id: 8)
+        );
+        $this->gate->shouldReceive('validate')->andReturn(null);
+        $this->availability->shouldReceive('claim')->with(10)->once()->andReturn(true);
+        $this->bookings->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Lesson $l): bool => $l->studentId === 5))
+            ->andReturn(77);
+        $this->gate->shouldReceive('record')->once();
+        $this->bookings->shouldReceive('updateStatus')->once()->andReturn(true);
+
+        $request = new \WP_REST_Request(['slot_id' => 10, 'offering_id' => 8, 'student_id' => 5]);
+
+        self::assertInstanceOf(\WP_REST_Response::class, $this->endpoint->book($request));
+    }
+
+    public function testGuardianMayCancelTheirChildsLesson(): void
+    {
+        $this->guardians->shouldReceive('canActFor')->with(5, 42)->andReturn(true);
+
+        $lesson = new Lesson(slotId: 10, studentId: 42, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 77);
+        $this->bookings->shouldReceive('findById')->with(77)->andReturn($lesson);
+        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
+        $this->bookings->shouldReceive('updateStatus')->once()->with(77, Lesson::STATUS_CANCELLED)->andReturn(true);
+        $this->availability->shouldReceive('release')->once()->with(10)->andReturn(true);
+        $this->payments->shouldReceive('voidPending')->once();
+
+        $result = $this->endpoint->cancel(new \WP_REST_Request(['id' => 77]));
+
+        self::assertInstanceOf(\WP_REST_Response::class, $result);
+    }
+
+    public function testMyLessonsCoversTheWholeHouseholdSortedByStart(): void
+    {
+        Functions\when('current_user_can')->justReturn(false);
+
+        $this->guardians->shouldReceive('householdIds')->with(5)->andReturn([5, 42]);
+        $this->guardians->shouldReceive('studentName')->with(5)->andReturn('Grace');
+        $this->guardians->shouldReceive('studentName')->with(42)->andReturn('Ada');
+
+        $mine  = new Lesson(slotId: 11, studentId: 5, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 78);
+        $childs = new Lesson(slotId: 10, studentId: 42, instructorId: 3, status: Lesson::STATUS_CONFIRMED, id: 77);
+
+        $this->bookings->shouldReceive('findUpcomingForStudent')->with(5)->andReturn([$mine]);
+        $this->bookings->shouldReceive('findUpcomingForStudent')->with(42)->andReturn([$childs]);
+
+        // Slot 10 starts first, so the child's lesson leads the merged list.
+        $this->availability->shouldReceive('findById')->with(10)->andReturn($this->slot(10, 3, null));
+        $this->availability->shouldReceive('findById')->with(11)->andReturn(new AvailabilitySlot(
+            instructorId:    3,
+            startDt:         '2026-07-02 10:00:00',
+            endDt:           '2026-07-02 11:00:00',
+            durationMinutes: 60,
+            id:              11,
+        ));
+
+        $data = $this->endpoint->myLessons(new \WP_REST_Request([]))->get_data();
+
+        self::assertSame([77, 78], array_column($data, 'id'));
+        self::assertSame(['Ada', 'Grace'], array_column($data, 'student_name'));
+    }
 }