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
@@ -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'));
+    }
 }
@@ -4,17 +4,26 @@ declare(strict_types=1);
 namespace Unsupervised\Schedular\Tests\Unit\Booking;

 use Brain\Monkey\Functions;
+use Mockery;
 use Unsupervised\Schedular\Booking\BookingPage;
+use Unsupervised\Schedular\Guardian\GuardianService;
 use Unsupervised\Schedular\Tests\Unit\TestCase;

 class BookingPageTest extends TestCase
 {
    private BookingPage $page;
+    private GuardianService&Mockery\MockInterface $guardians;

    protected function setUp(): void
    {
        parent::setUp();
-        $this->page = new BookingPage();
+        $this->guardians = Mockery::mock(GuardianService::class);
+        // Most cases are a single-student account: one bookable person, no picker.
+        $this->guardians->shouldReceive('bookableStudents')->andReturn(
+            [['id' => 3, 'name' => 'Ada', 'is_self' => true]]
+        )->byDefault();
+
+        $this->page = new BookingPage($this->guardians);
    }

    /**
@@ -171,4 +180,35 @@ class BookingPageTest extends TestCase

        self::assertSame('https://example.com/wp-login.php', $this->page->loginUrl(5));
    }
+
+    /**
+     * A single-student account gets a one-entry list, which the script renders
+     * as no picker at all.
+     */
+    public function testStudentListIsEmbeddedForTheScript(): void
+    {
+        $html = $this->renderForStudent([]);
+
+        self::assertStringContainsString('data-students=', $html);
+        self::assertStringContainsString('&quot;is_self&quot;:true', $html);
+    }
+
+    /**
+     * Children lead the embedded list, so the picker's default selection is a
+     * child rather than the parent.
+     */
+    public function testGuardianListLeadsWithChildren(): void
+    {
+        $this->guardians->shouldReceive('bookableStudents')->with(3)->andReturn([
+            ['id' => 42, 'name' => 'Ada', 'is_self' => false],
+            ['id' => 3, 'name' => 'Grace', 'is_self' => true],
+        ]);
+
+        $html = $this->renderForStudent([]);
+
+        $students = json_decode(html_entity_decode((string) preg_replace('/.*data-students="([^"]*)".*/s', '$1', $html)), true);
+
+        self::assertSame([42, 3], array_column((array) $students, 'id'));
+        self::assertFalse($students[0]['is_self']);
+    }
 }