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
2026-08-24 14:06:16 -03:00
parent 8a34ec41e9
commit 8c21a3fa9d
46 changed files with 3020 additions and 306 deletions
@@ -0,0 +1,101 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Registration;
+
+/**
+ * Where an intake answer or policy acceptance came from, when it did not come
+ * from the student filling in the booking form.
+ *
+ * A lesson the studio booked on someone's behalf has no answers and no
+ * acceptances — nobody was at a keyboard to give them — so they are collected
+ * some other way and typed in afterwards. What makes that record worth keeping
+ * is knowing *how*: "accepted on 24 Aug" means one thing when a student ticked a
+ * box and quite another when a staff member read it off a signed form, and an
+ * audit trail that cannot tell them apart is worse than no audit trail, because
+ * it looks like one.
+ *
+ * Absent (null) provenance is therefore meaningful in its own right: it is the
+ * ordinary case of the student answering online.
+ */
+class IntakeProvenance {
+
+	public const VIA_PAPER     = 'paper';
+	public const VIA_IN_PERSON = 'in_person';
+	public const VIA_PHONE     = 'phone';
+	public const VIA_EMAIL     = 'email';
+	public const VIA_OTHER     = 'other';
+
+	/**
+	 * How the answers can have reached the studio. `other` exists so the list
+	 * never forces a lie, and is the one option that must be explained.
+	 *
+	 * @var list<string>
+	 */
+	public const VALID_METHODS = [ self::VIA_PAPER, self::VIA_IN_PERSON, self::VIA_PHONE, self::VIA_EMAIL, self::VIA_OTHER ];
+
+	/** Longest note the `collected_note` VARCHAR(191) column holds. */
+	public const MAX_NOTE_LENGTH = 191;
+
+	public function __construct(
+		public readonly string $collectedVia,
+		public readonly ?string $collectedNote = null,
+		public readonly int $recordedBy = 0,
+	) {}
+
+	/**
+	 * Build from submitted values, or explain what is wrong with them. A method
+	 * outside the vocabulary is rejected rather than stored: a column that can say
+	 * anything says nothing. `other` requires the note, since "other" on its own
+	 * answers the question with the question.
+	 */
+	public static function fromInput( string $collectedVia, string $collectedNote, int $recordedBy ): self|\WP_Error {
+		if ( ! in_array( $collectedVia, self::VALID_METHODS, true ) ) {
+			return new \WP_Error( 'invalid_collection_method', __( 'Choose how these were collected.', 'unsupervised-schedular' ) );
+		}
+
+		$note = trim( $collectedNote );
+
+		if ( self::VIA_OTHER === $collectedVia && '' === $note ) {
+			return new \WP_Error( 'collection_note_required', __( 'Say how these were collected.', 'unsupervised-schedular' ) );
+		}
+
+		return new self(
+			collectedVia:  $collectedVia,
+			collectedNote: '' !== $note ? mb_substr( $note, 0, self::MAX_NOTE_LENGTH ) : null,
+			recordedBy:    $recordedBy,
+		);
+	}
+
+	/**
+	 * The methods as `value => label`, for the form's picker and for reading a
+	 * stored value back on screen.
+	 *
+	 * @return array<string, string>
+	 */
+	public static function choices(): array {
+		return [
+			self::VIA_PAPER     => __( 'On a signed paper form', 'unsupervised-schedular' ),
+			self::VIA_IN_PERSON => __( 'In person', 'unsupervised-schedular' ),
+			self::VIA_PHONE     => __( 'Over the phone', 'unsupervised-schedular' ),
+			self::VIA_EMAIL     => __( 'By email', 'unsupervised-schedular' ),
+			self::VIA_OTHER     => __( 'Some other way', 'unsupervised-schedular' ),
+		];
+	}
+
+	/**
+	 * How a stored row reads on screen: the method's label, plus its note. An
+	 * empty method is the ordinary case — the student answered online — and says
+	 * so rather than showing a blank cell.
+	 */
+	public static function describe( ?string $collectedVia, ?string $collectedNote = null ): string {
+		if ( null === $collectedVia || '' === $collectedVia ) {
+			return __( 'Given online when booking', 'unsupervised-schedular' );
+		}
+
+		$label = self::choices()[ $collectedVia ] ?? $collectedVia;
+		$note  = null !== $collectedNote ? trim( $collectedNote ) : '';
+
+		return '' !== $note ? $label . ' — ' . $note : $label;
+	}
+}