Add lesson booking registration flow (offering, questions, policies)

Implements #3: students register for a private lesson by picking a slot,
answering the offering's intake questions, and accepting booking-scoped
policies. Payment is a clean seam for #7 (lessons land pending; payment_id
null; instructor confirms via PATCH /bookings/{id}/status).

- Schema: us_lessons += offering_id, recurrence, series_id, payment_id.
- Lesson: new fields + recurrence constants.
- BookingRepository::insertSeries() builds a weekly series sharing a
  series_id; AvailabilityRepository::findUnbookedInGroup() reserves a group.
- RegistrationGate (src/Registration/): validate + record intake answers and
  booking-scoped policy acceptances. Reused by group enrolment (#4).
- BookingEndpoint::book(): offering_id, recurrence, answers,
  accepted_policy_version_ids; single or weekly; records answers/acceptances
  (type lesson).
- GET /policies?scope=booking filter.
- Front-end booking.js: slot -> questions + policies -> submit.
- Wiring: RegistrationGate built in Plugin, passed via RestRegistrar.
- Test-only WP_Error stub in tests/bootstrap.php for gate testing.

Refs #3

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/Unit/Booking/BookingRepositoryTest.php

@@ -34,19 +34,43 @@ class BookingRepositoryTest extends TestCase
                 Mockery::on(static function (array $data): bool {
                     return $data['slot_id'] === 10
                         && $data['student_id'] === 5
+                        && $data['offering_id'] === 7
+                        && $data['recurrence'] === Lesson::RECURRENCE_SINGLE
                         && $data['status'] === Lesson::STATUS_PENDING;
                 }),
-                ['%d', '%d', '%d', '%s', '%s', '%s']
+                ['%d', '%d', '%d', '%d', '%s', '%d', '%s', '%d', '%s', '%s']
             );
 
         $this->db->insert_id = 77;
 
-        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3);
+        $lesson = new Lesson(slotId: 10, studentId: 5, instructorId: 3, offeringId: 7);
         $result = $this->repo->insert($lesson);
 
         self::assertSame(77, $result);
     }
 
+    public function testInsertSeriesSharesSeriesIdAcrossSlots(): void
+    {
+        Functions\when('current_time')->justReturn('2026-04-01 12:00:00');
+
+        $ids = [40, 41, 42];
+        $this->db->shouldReceive('insert')
+            ->times(3)
+            ->andReturnUsing(function () use (&$ids): void {
+                $this->db->insert_id = array_shift($ids);
+            });
+
+        // The first lesson is back-filled with its own id as the series id.
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with('wp_us_lessons', ['series_id' => 40], ['id' => 40], ['%d'], ['%d']);
+
+        $template = new Lesson(slotId: 0, studentId: 5, instructorId: 3, offeringId: 7);
+        $result   = $this->repo->insertSeries($template, [100, 101, 102]);
+
+        self::assertSame([40, 41, 42], $result);
+    }
+
     public function testFindByIdReturnsNullWhenNotFound(): void
     {
         $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
@@ -60,9 +84,13 @@ class BookingRepositoryTest extends TestCase
         $row = (object) [
             'id'            => '15',
             'slot_id'       => '10',
+            'offering_id'   => null,
             'student_id'    => '5',
             'instructor_id' => '3',
+            'recurrence'    => Lesson::RECURRENCE_SINGLE,
+            'series_id'     => null,
             'status'        => 'pending',
+            'payment_id'    => null,
             'notes'         => null,
         ];
 
@@ -109,9 +137,13 @@ class BookingRepositoryTest extends TestCase
         $row = (object) [
             'id'            => '1',
             'slot_id'       => '2',
+            'offering_id'   => null,
             'student_id'    => '5',
             'instructor_id' => '3',
+            'recurrence'    => Lesson::RECURRENCE_SINGLE,
+            'series_id'     => null,
             'status'        => 'pending',
+            'payment_id'    => null,
             'notes'         => null,
         ];
 

tests/Unit/Booking/LessonTest.php

@@ -28,41 +28,52 @@ class LessonTest extends TestCase
         $lesson = new Lesson(slotId: 1, studentId: 2, instructorId: 3);
 
         self::assertSame(Lesson::STATUS_PENDING, $lesson->status);
+        self::assertNull($lesson->offeringId);
+        self::assertSame(Lesson::RECURRENCE_SINGLE, $lesson->recurrence);
+        self::assertNull($lesson->seriesId);
+        self::assertNull($lesson->paymentId);
         self::assertNull($lesson->notes);
         self::assertNull($lesson->id);
     }
 
+    public function testRecurrenceConstants(): void
+    {
+        self::assertContains(Lesson::RECURRENCE_SINGLE, Lesson::VALID_RECURRENCES);
+        self::assertContains(Lesson::RECURRENCE_WEEKLY, Lesson::VALID_RECURRENCES);
+    }
+
     public function testFromRowMapsCorrectly(): void
     {
         $row = (object) [
             'id'            => '99',
             'slot_id'       => '10',
+            'offering_id'   => '7',
             'student_id'    => '20',
             'instructor_id' => '30',
+            'recurrence'    => Lesson::RECURRENCE_WEEKLY,
+            'series_id'     => '99',
             'status'        => 'confirmed',
+            'payment_id'    => null,
             'notes'         => 'Bring your guitar.',
         ];
 
         $lesson = Lesson::fromRow($row);
 
         self::assertSame(99, $lesson->id);
-        self::assertSame(10, $lesson->slotId);
-        self::assertSame(20, $lesson->studentId);
-        self::assertSame(30, $lesson->instructorId);
+        self::assertSame(7, $lesson->offeringId);
+        self::assertSame(Lesson::RECURRENCE_WEEKLY, $lesson->recurrence);
+        self::assertSame(99, $lesson->seriesId);
+        self::assertNull($lesson->paymentId);
         self::assertSame('confirmed', $lesson->status);
-        self::assertSame('Bring your guitar.', $lesson->notes);
     }
 
     public function testToArrayContainsExpectedKeys(): void
     {
-        $lesson = new Lesson(1, 2, 3, Lesson::STATUS_PENDING, 'Note', 5);
+        $lesson = new Lesson(slotId: 1, studentId: 2, instructorId: 3, notes: 'Note', id: 5);
         $arr    = $lesson->toArray();
 
-        self::assertArrayHasKey('id', $arr);
-        self::assertArrayHasKey('slot_id', $arr);
-        self::assertArrayHasKey('student_id', $arr);
-        self::assertArrayHasKey('instructor_id', $arr);
-        self::assertArrayHasKey('status', $arr);
-        self::assertArrayHasKey('notes', $arr);
+        foreach (['id', 'slot_id', 'offering_id', 'student_id', 'instructor_id', 'recurrence', 'series_id', 'status', 'payment_id', 'notes'] as $key) {
+            self::assertArrayHasKey($key, $arr);
+        }
     }
 }

tests/Unit/Registration/RegistrationGateTest.php

@@ -0,0 +1,105 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Registration;
+
+use Mockery;
+use Unsupervised\Schedular\Policy\AcceptanceRepository;
+use Unsupervised\Schedular\Policy\Policy;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
+use Unsupervised\Schedular\Policy\PolicyRepository;
+use Unsupervised\Schedular\Policy\PolicyVersion;
+use Unsupervised\Schedular\Policy\PolicyVersionRepository;
+use Unsupervised\Schedular\Registration\Answer;
+use Unsupervised\Schedular\Registration\AnswerRepository;
+use Unsupervised\Schedular\Registration\Question;
+use Unsupervised\Schedular\Registration\QuestionRepository;
+use Unsupervised\Schedular\Registration\RegistrationGate;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class RegistrationGateTest extends TestCase
+{
+    private QuestionRepository $questions;
+    private AnswerRepository $answers;
+    private PolicyRepository $policies;
+    private PolicyVersionRepository $versions;
+    private AcceptanceRepository $acceptances;
+    private RegistrationGate $gate;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->questions   = Mockery::mock(QuestionRepository::class);
+        $this->answers     = Mockery::mock(AnswerRepository::class);
+        $this->policies    = Mockery::mock(PolicyRepository::class);
+        $this->versions    = Mockery::mock(PolicyVersionRepository::class);
+        $this->acceptances = Mockery::mock(AcceptanceRepository::class);
+
+        $this->gate = new RegistrationGate(
+            $this->questions,
+            $this->answers,
+            $this->policies,
+            $this->versions,
+            $this->acceptances
+        );
+    }
+
+    private function requiredQuestion(): Question
+    {
+        return new Question(offeringId: 7, label: 'Level?', isRequired: true, id: 3);
+    }
+
+    private function bookingPolicy(): Policy
+    {
+        return new Policy('Cancellation', 'cancellation', currentVersionId: 9, acceptanceScope: Policy::SCOPE_BOOKING, id: 1);
+    }
+
+    public function testValidatePassesWhenAnswersAndPoliciesProvided(): void
+    {
+        $this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
+        $this->policies->shouldReceive('findForScope')->with(Policy::SCOPE_BOOKING)->andReturn([$this->bookingPolicy()]);
+        $this->versions->shouldReceive('findById')->with(9)->andReturn(new PolicyVersion(1, 1, 'body', PolicyVersion::STATUS_PUBLISHED, null, 9));
+
+        self::assertNull($this->gate->validate(7, [3 => 'Beginner'], [9]));
+    }
+
+    public function testValidateFailsWhenRequiredQuestionUnanswered(): void
+    {
+        $this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
+
+        $result = $this->gate->validate(7, [3 => '   '], [9]);
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('missing_answer', $result->get_error_code());
+    }
+
+    public function testValidateFailsWhenPolicyNotAccepted(): void
+    {
+        $this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
+        $this->policies->shouldReceive('findForScope')->with(Policy::SCOPE_BOOKING)->andReturn([$this->bookingPolicy()]);
+        $this->versions->shouldReceive('findById')->with(9)->andReturn(new PolicyVersion(1, 1, 'body', PolicyVersion::STATUS_PUBLISHED, null, 9));
+
+        $result = $this->gate->validate(7, [3 => 'Beginner'], []);
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('policy_required', $result->get_error_code());
+    }
+
+    public function testRecordPersistsAnswersAndAcceptances(): void
+    {
+        $this->questions->shouldReceive('findByOffering')->with(7, true)->andReturn([$this->requiredQuestion()]);
+        $this->policies->shouldReceive('findForScope')->with(Policy::SCOPE_BOOKING)->andReturn([$this->bookingPolicy()]);
+        $this->versions->shouldReceive('findById')->with(9)->andReturn(new PolicyVersion(1, 1, 'body', PolicyVersion::STATUS_PUBLISHED, null, 9));
+
+        $this->answers->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Answer $a): bool => $a->questionId === 3 && $a->registrationId === 50 && $a->answerValue === 'Beginner'));
+
+        $this->acceptances->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (PolicyAcceptance $a): bool => $a->policyVersionId === 9 && $a->registrationType === PolicyAcceptance::REG_LESSON && $a->registrationId === 50));
+
+        $this->gate->record(PolicyAcceptance::REG_LESSON, 50, 5, 7, [3 => 'Beginner'], [9], '203.0.113.7');
+    }
+}

tests/bootstrap.php

@@ -13,3 +13,36 @@ define('USC_VERSION', '1.0.0');
 define('USC_PLUGIN_FILE', dirname(__DIR__) . '/unsupervised-schedular.php');
 define('USC_PLUGIN_DIR', dirname(__DIR__) . '/');
 define('USC_PLUGIN_URL', 'http://example.com/wp-content/plugins/unsupervised-schedular/');
+
+// Minimal WP_Error stub for code under test that returns error objects.
+if (! class_exists('WP_Error')) {
+    class WP_Error
+    {
+        /** @var array<string, list<string>> */
+        public array $errors = [];
+
+        /** @var array<string, mixed> */
+        public array $error_data = [];
+
+        public function __construct(string $code = '', string $message = '', mixed $data = '')
+        {
+            if ('' !== $code) {
+                $this->errors[$code][] = $message;
+                if ('' !== $data) {
+                    $this->error_data[$code] = $data;
+                }
+            }
+        }
+
+        public function get_error_code(): string
+        {
+            return (string) (array_key_first($this->errors) ?? '');
+        }
+
+        public function get_error_message(): string
+        {
+            $code = $this->get_error_code();
+            return '' !== $code ? ($this->errors[$code][0] ?? '') : '';
+        }
+    }
+}