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 <[email protected]>

src/Booking/BookingEndpoint.php

@@ -5,12 +5,17 @@ namespace Unsupervised\Schedular\Booking;
 
 use Unsupervised\Schedular\Availability\AvailabilityRepository;
 use Unsupervised\Schedular\Auth\RoleManager;
+use Unsupervised\Schedular\Offering\OfferingRepository;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
+use Unsupervised\Schedular\Registration\RegistrationGate;
 
 class BookingEndpoint {
 
 	public function __construct(
 		private AvailabilityRepository $availability,
 		private BookingRepository $bookings,
+		private OfferingRepository $offerings,
+		private RegistrationGate $gate,
 	) {}
 
 	public function registerRoutes( string $route_namespace ): void {
@@ -28,12 +33,28 @@ class BookingEndpoint {
 					'callback'            => [ $this, 'book' ],
 					'permission_callback' => [ $this, 'canBook' ],
 					'args'                => [
-						'slot_id' => [
+						'slot_id'                     => [
 							'type'              => 'integer',
 							'required'          => true,
 							'sanitize_callback' => 'absint',
 						],
-						'notes'   => [
+						'offering_id'                 => [
+							'type'    => 'integer',
+							'default' => 0,
+						],
+						'recurrence'                  => [
+							'type'    => 'string',
+							'default' => 'single',
+						],
+						'answers'                     => [
+							'type'    => 'object',
+							'default' => [],
+						],
+						'accepted_policy_version_ids' => [
+							'type'    => 'array',
+							'default' => [],
+						],
+						'notes'                       => [
 							'type'              => 'string',
 							'default'           => '',
 							'sanitize_callback' => 'sanitize_textarea_field',
@@ -84,26 +105,83 @@ class BookingEndpoint {
 			return new \WP_Error( 'slot_taken', __( 'This slot is already booked.', 'unsupervised-schedular' ), [ 'status' => 409 ] );
 		}
 
-		$notes  = (string) $request->get_param( 'notes' );
-		$lesson = new Lesson(
+		$offeringId = absint( $request->get_param( 'offering_id' ) );
+		if ( 0 === $offeringId ) {
+			$offeringId = (int) ( $slot->offeringId ?? 0 );
+		}
+		if ( $offeringId > 0 && null === $this->offerings->findById( $offeringId ) ) {
+			return new \WP_Error( 'invalid_offering', __( 'Offering not found.', 'unsupervised-schedular' ), [ 'status' => 400 ] );
+		}
+
+		$answers            = $this->answers( $request );
+		$acceptedVersionIds = array_map( 'absint', (array) $request->get_param( 'accepted_policy_version_ids' ) );
+
+		$gateError = $this->gate->validate( $offeringId, $answers, $acceptedVersionIds );
+		if ( $gateError instanceof \WP_Error ) {
+			return $gateError;
+		}
+
+		$studentId  = get_current_user_id();
+		$notes      = (string) $request->get_param( 'notes' );
+		$recurrence = Lesson::RECURRENCE_WEEKLY === $request->get_param( 'recurrence' )
+			? Lesson::RECURRENCE_WEEKLY
+			: Lesson::RECURRENCE_SINGLE;
+
+		$template = new Lesson(
 			slotId:       $slotId,
-			studentId:    get_current_user_id(),
+			studentId:    $studentId,
 			instructorId: $slot->instructorId,
+			offeringId:   $offeringId > 0 ? $offeringId : null,
+			recurrence:   $recurrence,
 			notes:        '' !== $notes ? $notes : null,
 		);
 
-		$id = $this->bookings->insert( $lesson );
-		$this->availability->markBooked( $slotId );
+		// Weekly reservation across the slot's recurring group; otherwise a single lesson.
+		if ( Lesson::RECURRENCE_WEEKLY === $recurrence && null !== $slot->recurrenceGroup ) {
+			$slotIds = array_map( static fn( $s ): int => (int) $s->id, $this->availability->findUnbookedInGroup( $slot->recurrenceGroup ) );
+			$ids     = $this->bookings->insertSeries( $template, $slotIds );
+			foreach ( $slotIds as $reservedSlotId ) {
+				$this->availability->markBooked( $reservedSlotId );
+			}
+			$anchorId = $ids[0] ?? 0;
+		} else {
+			$anchorId = $this->bookings->insert( $template );
+			$this->availability->markBooked( $slotId );
+			$ids = [ $anchorId ];
+		}
+
+		$this->gate->record( PolicyAcceptance::REG_LESSON, $anchorId, $studentId, $offeringId, $answers, $acceptedVersionIds, $this->clientIp() );
 
 		return new \WP_REST_Response(
 			[
-				'id'     => $id,
+				'ids'    => $ids,
 				'status' => Lesson::STATUS_PENDING,
 			],
 			201
 		);
 	}
 
+	/**
+	 * Extract a question_id => value map from the request.
+	 *
+	 * @return array<int, string>
+	 */
+	private function answers( \WP_REST_Request $request ): array {
+		$out = [];
+		foreach ( (array) $request->get_param( 'answers' ) as $questionId => $value ) {
+			$out[ (int) $questionId ] = sanitize_text_field( (string) $value );
+		}
+
+		return $out;
+	}
+
+	private function clientIp(): ?string {
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- IP stored verbatim for audit.
+		$ip = sanitize_text_field( wp_unslash( $_SERVER['REMOTE_ADDR'] ?? '' ) );
+
+		return '' !== $ip ? $ip : null;
+	}
+
 	public function updateStatus( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
 		$id     = absint( $request->get_param( 'id' ) );
 		$lesson = $this->bookings->findById( $id );

src/Booking/BookingRepository.php

@@ -16,18 +16,68 @@ class BookingRepository {
 			$this->table,
 			[
 				'slot_id'       => $lesson->slotId,
+				'offering_id'   => $lesson->offeringId,
 				'student_id'    => $lesson->studentId,
 				'instructor_id' => $lesson->instructorId,
+				'recurrence'    => $lesson->recurrence,
+				'series_id'     => $lesson->seriesId,
 				'status'        => $lesson->status,
+				'payment_id'    => $lesson->paymentId,
 				'notes'         => $lesson->notes,
 				'created_at'    => current_time( 'mysql' ),
 			],
-			[ '%d', '%d', '%d', '%s', '%s', '%s' ]
+			[ '%d', '%d', '%d', '%d', '%s', '%d', '%s', '%d', '%s', '%s' ]
 		);
 
 		return $this->db->insert_id;
 	}
 
+	/**
+	 * Create a weekly lesson series — one lesson per slot, all sharing a
+	 * `series_id` (the id of the first lesson row).
+	 *
+	 * @param list<int> $slotIds Availability slot IDs to reserve, in order.
+	 * @return list<int> Inserted lesson IDs.
+	 */
+	public function insertSeries( Lesson $template, array $slotIds ): array {
+		$ids      = [];
+		$seriesId = 0;
+
+		foreach ( $slotIds as $slotId ) {
+			$id = $this->insert(
+				new Lesson(
+					slotId:       $slotId,
+					studentId:    $template->studentId,
+					instructorId: $template->instructorId,
+					offeringId:   $template->offeringId,
+					recurrence:   Lesson::RECURRENCE_WEEKLY,
+					seriesId:     $seriesId > 0 ? $seriesId : null,
+					status:       $template->status,
+					notes:        $template->notes,
+				)
+			);
+
+			if ( 0 === $seriesId ) {
+				$seriesId = $id;
+				$this->setSeriesId( $id, $seriesId );
+			}
+
+			$ids[] = $id;
+		}
+
+		return $ids;
+	}
+
+	private function setSeriesId( int $id, int $seriesId ): void {
+		$this->db->update(
+			$this->table,
+			[ 'series_id' => $seriesId ],
+			[ 'id' => $id ],
+			[ '%d' ],
+			[ '%d' ]
+		);
+	}
+
 	public function findById( int $id ): ?Lesson {
 		$row = $this->db->get_row(
 			$this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id )

src/Booking/Lesson.php

@@ -16,11 +16,25 @@ class Lesson {
 	 */
 	public const VALID_STATUSES = [ self::STATUS_PENDING, self::STATUS_CONFIRMED, self::STATUS_CANCELLED ];
 
+	public const RECURRENCE_SINGLE = 'single';
+	public const RECURRENCE_WEEKLY = 'weekly';
+
+	/**
+	 * All valid recurrence values.
+	 *
+	 * @var list<string>
+	 */
+	public const VALID_RECURRENCES = [ self::RECURRENCE_SINGLE, self::RECURRENCE_WEEKLY ];
+
 	public function __construct(
 		public readonly int $slotId,
 		public readonly int $studentId,
 		public readonly int $instructorId,
+		public readonly ?int $offeringId = null,
+		public readonly string $recurrence = self::RECURRENCE_SINGLE,
+		public readonly ?int $seriesId = null,
 		public readonly string $status = self::STATUS_PENDING,
+		public readonly ?int $paymentId = null,
 		public readonly ?string $notes = null,
 		public readonly ?int $id = null,
 	) {}
@@ -30,7 +44,11 @@ class Lesson {
 			slotId:       (int) $row->slot_id,
 			studentId:    (int) $row->student_id,
 			instructorId: (int) $row->instructor_id,
+			offeringId:   null !== $row->offering_id ? (int) $row->offering_id : null,
+			recurrence:   $row->recurrence,
+			seriesId:     null !== $row->series_id ? (int) $row->series_id : null,
 			status:       $row->status,
+			paymentId:    null !== $row->payment_id ? (int) $row->payment_id : null,
 			notes:        $row->notes,
 			id:           (int) $row->id,
 		);
@@ -45,9 +63,13 @@ class Lesson {
 		return [
 			'id'            => $this->id,
 			'slot_id'       => $this->slotId,
+			'offering_id'   => $this->offeringId,
 			'student_id'    => $this->studentId,
 			'instructor_id' => $this->instructorId,
+			'recurrence'    => $this->recurrence,
+			'series_id'     => $this->seriesId,
 			'status'        => $this->status,
+			'payment_id'    => $this->paymentId,
 			'notes'         => $this->notes,
 		];
 	}