Let the studio book lessons and record intake collected elsewhere

Two related gaps, closed together because the second is created by the first.

A private lesson could only be booked by the student or their guardian, so a
booking taken over the phone had no way in — where group classes have had "Add
students directly" all along. "Book a lesson for a student" is now a panel on
Scheduler and My Lessons: student, open time, lesson type, with weekly term
reservations and a no-charge option for make-up lessons. The booking core is
extracted to Booking\LessonBooker and shared with POST /bookings, so the two
paths cannot drift on offering rules, slot claiming, or billing.

That leaves a registration with no intake answers and no policy acceptances,
because nobody was at a keyboard to give them — already true of every directly
added group-class student. Ticking the boxes on a student's behalf would be an
audit trail that says something untrue, so instead the answers are collected
another way and recorded afterwards, from a lesson's or an enrolment's detail
page. Every recording must say how it was collected, which is stamped on each
row along with who typed it and shown in a new "How it was given" column: a
policy ticked online and one transcribed from paper must never look alike.

Only staff-made registrations qualify (us_lessons.booked_by,
us_group_enrollments.enrolled_by) — one the student made already holds their
own answers. Only what is still missing can be recorded, re-checked at write
time, so a stale or double-posted form cannot duplicate or overwrite. No IP is
stored for a transcription, and accepted_by stays the student while recorded_by
names the staff member.

Intake is now generic over Registration\IntakeSubject, which Lesson and
Enrollment both implement; LessonDetail became Registration\IntakeAudit and is
shared by both detail views rather than duplicated.

Closes #182

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01QfHt6CyJHz6KkA4RuaS7WK

src/GroupClass/GroupClassController.php

@@ -14,6 +14,9 @@ use Unsupervised\Schedular\Offering\OfferingRepository;
 use Unsupervised\Schedular\Payment\Payment;
 use Unsupervised\Schedular\Payment\PaymentRepository;
 use Unsupervised\Schedular\Payment\PaymentService;
+use Unsupervised\Schedular\Registration\IntakeAudit;
+use Unsupervised\Schedular\Registration\IntakeProvenance;
+use Unsupervised\Schedular\Registration\IntakeRecording;
 use Unsupervised\Schedular\Val;
 
 class GroupClassController {
@@ -26,6 +29,8 @@ class GroupClassController {
 		private PaymentService $paymentService,
 		private InviteRepository $invites,
 		private RegistrationMailer $mailer,
+		private IntakeAudit $audit,
+		private IntakeRecording $intake,
 	) {}
 
 	/**
@@ -41,13 +46,18 @@ class GroupClassController {
 			wp_die( esc_html__( 'You do not have permission to view group classes.', 'unsupervised-schedular' ) );
 		}
 
+		$baseUrl = admin_url( 'admin.php?page=us-group-classes' );
+
+		if ( $this->maybeRenderEnrollmentDetail( $baseUrl, 0 ) ) {
+			return;
+		}
+
 		$notice = '';
 		if ( isset( $_POST['usc_action'] ) && check_admin_referer( 'usc_group_action' ) ) {
 			$notice = $this->handleFormAction( get_current_user_id() );
 		}
 
 		$offerings = $this->offerings->findAll( 0, Offering::KIND_GROUP_CLASS );
-		$baseUrl   = admin_url( 'admin.php?page=us-group-classes' );
 
 		// View-state query param only (which class to drill into) — nothing is
 		// mutated from it, so no nonce applies.
@@ -104,6 +114,10 @@ class GroupClassController {
 
 		$instructorId = get_current_user_id();
 
+		if ( $this->maybeRenderEnrollmentDetail( admin_url( 'admin.php?page=us-my-group-classes' ), $instructorId ) ) {
+			return;
+		}
+
 		$notice = '';
 		if ( isset( $_POST['usc_action'] ) && check_admin_referer( 'usc_group_action' ) ) {
 			$notice = $this->handleFormAction( $instructorId );
@@ -144,6 +158,138 @@ class GroupClassController {
 		include USC_PLUGIN_DIR . 'templates/admin/my-group-classes.php';
 	}
 
+	/**
+	 * When the request targets a single enrolment (`?enrollment_id=`), render its
+	 * detail view — the audit trail of what the student answered and agreed to,
+	 * and, for an enrolment the studio made, the form to record intake collected
+	 * elsewhere. Reports whether the page has been handled.
+	 *
+	 * `$onlyInstructorId` scopes it the way the pages themselves are scoped: an
+	 * instructor may only open enrolments in their own classes, while the studio
+	 * **Group Classes** page passes 0 and may open any.
+	 */
+	private function maybeRenderEnrollmentDetail( string $baseUrl, int $onlyInstructorId ): bool {
+		// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- read-only enrolment selector.
+		$enrollmentId = absint( Val::int( $_GET['enrollment_id'] ?? 0 ) );
+		if ( $enrollmentId <= 0 ) {
+			return false;
+		}
+
+		$enrollment = $this->enrollments->findById( $enrollmentId );
+		$notice     = '';
+		$error      = '';
+
+		if ( null === $enrollment || ( $onlyInstructorId > 0 && $enrollment->instructorId !== $onlyInstructorId ) ) {
+			$row     = null;
+			$answers = [];
+			$accepts = [];
+			$intake  = $this->emptyIntake();
+		} else {
+			// Recorded before the tables are read, so what was just entered appears
+			// on the page that reports it.
+			[ $notice, $error ] = $this->recordIntake( $enrollment );
+
+			$row     = $this->enrollmentRow( $enrollment );
+			$answers = $this->audit->answers( $enrollment );
+			$accepts = $this->audit->acceptances( $enrollment );
+			$intake  = $this->intakeForm( $enrollment );
+		}
+
+		include USC_PLUGIN_DIR . 'templates/admin/enrollment-detail.php';
+
+		return true;
+	}
+
+	/**
+	 * Who and what one enrolment is, for the head of its detail view.
+	 *
+	 * @return array{enrollment_id: int, student: string, class: string, instructor: string, status: string, payment: string}
+	 */
+	private function enrollmentRow( Enrollment $enrollment ): array {
+		$student  = get_userdata( $enrollment->studentId );
+		$offering = $this->offerings->findById( $enrollment->offeringId );
+		$payment  = null !== $enrollment->paymentId ? $this->payments->findById( $enrollment->paymentId ) : null;
+
+		return [
+			'enrollment_id' => (int) $enrollment->id,
+			'student'       => UserName::format( $student instanceof \WP_User ? $student : null, $enrollment->studentId ),
+			'class'         => null !== $offering ? $offering->title : '—',
+			'instructor'    => null !== $offering ? $this->instructorName( $offering ) : '—',
+			'status'        => $enrollment->status,
+			'payment'       => null !== $payment ? $payment->status : '—',
+		];
+	}
+
+	/**
+	 * Handle a submitted "record intake collected elsewhere" form.
+	 *
+	 * @return array{string, string} Success notice and error message.
+	 */
+	private function recordIntake( Enrollment $enrollment ): array {
+		if ( ! isset( $_POST['usc_action'] ) || ! check_admin_referer( 'usc_group_action' ) ) {
+			return [ '', '' ];
+		}
+
+		// phpcs:disable WordPress.Security.NonceVerification.Missing -- nonce checked above.
+		if ( 'record_intake' !== sanitize_key( Val::string( wp_unslash( $_POST['usc_action'] ) ) ) ) {
+			return [ '', '' ];
+		}
+
+		$answers = [];
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- each value is unslashed and sanitized below.
+		foreach ( (array) ( $_POST['answers'] ?? [] ) as $questionId => $value ) {
+			$answers[ absint( Val::int( $questionId ) ) ] = sanitize_textarea_field( Val::string( wp_unslash( $value ) ) );
+		}
+
+		// phpcs:ignore WordPress.Security.ValidatedSanitizedInput.InputNotSanitized, WordPress.Security.ValidatedSanitizedInput.MissingUnslash -- each element is coerced to a positive int; slashes cannot survive integer coercion.
+		$rawVersionIds = (array) ( $_POST['accepted_policy_version_ids'] ?? [] );
+		$versionIds    = array_values( array_filter( array_map( static fn( mixed $v ): int => absint( Val::int( $v ) ), $rawVersionIds ) ) );
+
+		$result = $this->intake->record(
+			$enrollment,
+			$answers,
+			$versionIds,
+			sanitize_key( Val::string( wp_unslash( $_POST['collected_via'] ?? '' ) ) ),
+			sanitize_text_field( Val::string( wp_unslash( $_POST['collected_note'] ?? '' ) ) ),
+			get_current_user_id()
+		);
+		// phpcs:enable WordPress.Security.NonceVerification.Missing
+
+		return $result instanceof \WP_Error
+			? [ '', $result->get_error_message() ]
+			: [ $result, '' ];
+	}
+
+	/**
+	 * What the detail template needs to offer the recording form: whether this
+	 * enrolment qualifies at all, what is still missing, and the collection
+	 * methods to choose between.
+	 *
+	 * @return array{recordable: bool, questions: list<array{id: int, label: string, required: bool}>, policies: list<array{version_id: int, policy: string, version: string}>, methods: array<string, string>}
+	 */
+	private function intakeForm( Enrollment $enrollment ): array {
+		if ( ! $enrollment->isStaffRegistered() ) {
+			return $this->emptyIntake();
+		}
+
+		return [ 'recordable' => true ] + $this->intake->pending( $enrollment ) + [ 'methods' => IntakeProvenance::choices() ];
+	}
+
+	/**
+	 * The form data for an enrolment that cannot be recorded against — one the
+	 * student made, or one that could not be opened at all.
+	 *
+	 * @return array{recordable: bool, questions: list<array{id: int, label: string, required: bool}>, policies: list<array{version_id: int, policy: string, version: string}>, methods: array<string, string>}
+	 */
+	private function emptyIntake(): array {
+		return [
+			'recordable' => false,
+			'questions'  => [],
+			'policies'   => [],
+			'methods'    => [],
+		];
+	}
+
 	/**
 	 * Summary row for one class in the instructor overview: its identity, when it
 	 * meets, and how many active enrolments it holds against capacity.
@@ -176,7 +322,7 @@ class GroupClassController {
 	 * invite-only classes — the list of people invited but not yet enrolled.
 	 *
 	 * @param list<Enrollment> $enrollments
-	 * @return array{id: int|null, title: string, when: string, capacity: int|null, enrolled: int, invite_only: bool, instructor: string, price: float, currency: string, duration: int|null, description: string|null, schedule_note: string|null, deadline: string, enrollment_open: bool, active: bool, roster: list<array{student: string, status: string, payment: string|null}>, invited: list<array{who: string, kind: string}>}
+	 * @return array{id: int|null, title: string, when: string, capacity: int|null, enrolled: int, invite_only: bool, instructor: string, price: float, currency: string, duration: int|null, description: string|null, schedule_note: string|null, deadline: string, enrollment_open: bool, active: bool, roster: list<array{id: int, student: string, status: string, payment: string|null}>, invited: list<array{who: string, kind: string}>}
 	 */
 	private function classDetail( Offering $offering, array $enrollments ): array {
 		$roster = [];
@@ -189,6 +335,7 @@ class GroupClassController {
 			$payment = null !== $enrollment->paymentId ? $this->payments->findById( $enrollment->paymentId ) : null;
 
 			$roster[] = [
+				'id'      => (int) $enrollment->id,
 				'student' => $student ? $student->display_name : (string) $enrollment->studentId,
 				'status'  => $enrollment->status,
 				'payment' => $payment?->status,
@@ -334,6 +481,10 @@ class GroupClassController {
 					offeringId:   (int) $offering->id,
 					studentId:    $studentId,
 					instructorId: $offering->instructorId,
+					// Stamped so this enrolment can be told apart later: only one the
+					// studio made may have its intake recorded after the fact, the
+					// student never having been asked the questions.
+					enrolledBy:   get_current_user_id(),
 				)
 			);