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,255 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Registration;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Booking\Lesson;
+use Unsupervised\Schedular\GroupClass\Enrollment;
+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\IntakeProvenance;
+use Unsupervised\Schedular\Registration\IntakeRecording;
+use Unsupervised\Schedular\Registration\Question;
+use Unsupervised\Schedular\Registration\QuestionRepository;
+use Unsupervised\Schedular\Registration\RegistrationGate;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class IntakeRecordingTest extends TestCase
+{
+    private QuestionRepository&Mockery\MockInterface $questions;
+    private AnswerRepository&Mockery\MockInterface $answers;
+    private PolicyRepository&Mockery\MockInterface $policies;
+    private PolicyVersionRepository&Mockery\MockInterface $versions;
+    private AcceptanceRepository&Mockery\MockInterface $acceptances;
+    private RegistrationGate&Mockery\MockInterface $gate;
+    private IntakeRecording $intake;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        Functions\when('absint')->alias(static fn ($v): int => abs((int) $v));
+
+        $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        = Mockery::mock(RegistrationGate::class);
+
+        $this->intake = new IntakeRecording(
+            $this->questions,
+            $this->answers,
+            $this->policies,
+            $this->versions,
+            $this->acceptances,
+            $this->gate
+        );
+    }
+
+    public function testPendingListsOnlyWhatIsNotYetRecorded(): void
+    {
+        $this->questions->shouldReceive('findByOffering')->with(8, true)->andReturn([
+            new Question(offeringId: 8, label: 'Skill level', isRequired: true, id: 2),
+            new Question(offeringId: 8, label: 'Anything we should know?', id: 9),
+        ]);
+        // Question 2 was already answered; only question 9 is still outstanding.
+        $this->answers->shouldReceive('findByRegistration')->with(Answer::REG_LESSON, 1)->andReturn([
+            new Answer(questionId: 2, registrationType: Answer::REG_LESSON, registrationId: 1, studentId: 5, answerValue: 'Beginner'),
+        ]);
+
+        $this->gate->shouldReceive('requiredPolicyVersionIds')->andReturn([4, 6]);
+        $this->acceptances->shouldReceive('findByRegistration')->with(PolicyAcceptance::REG_LESSON, 1)->andReturn([
+            new PolicyAcceptance(policyVersionId: 4, studentId: 5, registrationType: PolicyAcceptance::REG_LESSON, registrationId: 1),
+        ]);
+        $this->versions->shouldReceive('findById')->with(6)->andReturn(new PolicyVersion(policyId: 3, versionNumber: 2, id: 6));
+        $this->policies->shouldReceive('findById')->with(3)->andReturn(new Policy(title: 'Cancellation', slug: 'cancellation', id: 3));
+
+        $pending = $this->intake->pending($this->lesson());
+
+        self::assertSame([['id' => 9, 'label' => 'Anything we should know?', 'required' => false]], $pending['questions']);
+        self::assertSame([['version_id' => 6, 'policy' => 'Cancellation', 'version' => 'v2']], $pending['policies']);
+    }
+
+    public function testRecordsTheAnswersAndAcceptancesWithHowTheyWereCollected(): void
+    {
+        $this->expectPending();
+
+        $this->gate->shouldReceive('record')
+            ->once()
+            ->with(
+                PolicyAcceptance::REG_LESSON,
+                1,
+                5,
+                8,
+                [9 => 'Nut allergy'],
+                [6],
+                // No IP: the student was never at a browser, and the staff member's
+                // would be a false location in the audit trail.
+                null,
+                // No acceptor override either: the student agreed, on paper.
+                0,
+                Mockery::on(static fn (IntakeProvenance $p): bool => IntakeProvenance::VIA_PAPER === $p->collectedVia
+                    && 'Filed in the studio binder' === $p->collectedNote
+                    && 3 === $p->recordedBy)
+            );
+
+        $notice = $this->intake->record(
+            $this->lesson(),
+            [9 => 'Nut allergy'],
+            [6],
+            IntakeProvenance::VIA_PAPER,
+            'Filed in the studio binder',
+            3
+        );
+
+        self::assertIsString($notice);
+        self::assertStringContainsString('1 answer', $notice);
+        self::assertStringContainsString('1 policy acceptance', $notice);
+        self::assertStringContainsString('On a signed paper form', $notice);
+        self::assertStringContainsString('Filed in the studio binder', $notice);
+    }
+
+    public function testALessonTheStudentBookedThemselvesCannotBeRecordedAgainst(): void
+    {
+        // No repository is even consulted: the guard comes first, so a student's
+        // own answers can never be added to after the fact.
+        $this->gate->shouldReceive('record')->never();
+
+        $result = $this->intake->record(
+            $this->lesson(bookedBy: 0),
+            [9 => 'Nut allergy'],
+            [],
+            IntakeProvenance::VIA_PAPER,
+            '',
+            3
+        );
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('not_recordable', $result->get_error_code());
+    }
+
+    public function testAnAlreadyRecordedAnswerOrAcceptanceIsIgnored(): void
+    {
+        $this->expectPending();
+        $this->gate->shouldReceive('record')->never();
+
+        // Question 2 and version 4 are already on file — a stale form reposting
+        // them must not duplicate or overwrite what is there.
+        $result = $this->intake->record(
+            $this->lesson(),
+            [2 => 'Advanced'],
+            [4],
+            IntakeProvenance::VIA_PAPER,
+            '',
+            3
+        );
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('nothing_to_record', $result->get_error_code());
+    }
+
+    public function testTheCollectionMethodIsRequiredAndMustBeOneOfTheKnownOnes(): void
+    {
+        $this->gate->shouldReceive('record')->never();
+
+        $result = $this->intake->record($this->lesson(), [9 => 'Nut allergy'], [], 'telepathy', '', 3);
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('invalid_collection_method', $result->get_error_code());
+    }
+
+    public function testOtherMustBeExplained(): void
+    {
+        $this->gate->shouldReceive('record')->never();
+
+        $result = $this->intake->record($this->lesson(), [9 => 'Nut allergy'], [], IntakeProvenance::VIA_OTHER, '  ', 3);
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('collection_note_required', $result->get_error_code());
+    }
+
+    public function testAWeeklySeriesRecordsAgainstItsAnchor(): void
+    {
+        // Occurrence #12 of a series anchored on lesson 1: answered for once.
+        $occurrence = new Lesson(slotId: 10, studentId: 5, instructorId: 3, offeringId: 8, seriesId: 1, bookedBy: 3, id: 12);
+
+        $this->expectPending();
+
+        // Registration id 1, not 12: the whole series shares one intake record, so
+        // opening any occurrence shows and adds to the same answers.
+        $this->gate->shouldReceive('record')
+            ->once()
+            ->with(PolicyAcceptance::REG_LESSON, 1, 5, 8, [9 => 'Nut allergy'], [], null, 0, Mockery::any());
+
+        self::assertIsString($this->intake->record($occurrence, [9 => 'Nut allergy'], [], IntakeProvenance::VIA_PHONE, '', 3));
+    }
+
+    public function testAGroupClassEnrolmentRecordsAgainstTheEnrolmentTable(): void
+    {
+        // The same recorder, a different registration type: an enrolment is its own
+        // registration, so nothing follows a series anchor here.
+        $enrollment = new Enrollment(offeringId: 8, studentId: 5, instructorId: 3, enrolledBy: 7, id: 44);
+
+        $this->questions->shouldReceive('findByOffering')->with(8, true)->andReturn([
+            new Question(offeringId: 8, label: 'Anything we should know?', id: 9),
+        ]);
+        $this->answers->shouldReceive('findByRegistration')->with(Answer::REG_ENROLLMENT, 44)->andReturn([]);
+        $this->gate->shouldReceive('requiredPolicyVersionIds')->andReturn([]);
+        $this->acceptances->shouldReceive('findByRegistration')->with(PolicyAcceptance::REG_ENROLLMENT, 44)->andReturn([]);
+
+        $this->gate->shouldReceive('record')
+            ->once()
+            ->with(Answer::REG_ENROLLMENT, 44, 5, 8, [9 => 'Nut allergy'], [], null, 0, Mockery::any());
+
+        self::assertIsString($this->intake->record($enrollment, [9 => 'Nut allergy'], [], IntakeProvenance::VIA_EMAIL, '', 7));
+    }
+
+    public function testAnEnrolmentTheStudentMadeCannotBeRecordedAgainst(): void
+    {
+        $this->gate->shouldReceive('record')->never();
+
+        $result = $this->intake->record(
+            new Enrollment(offeringId: 8, studentId: 5, instructorId: 3, id: 44),
+            [9 => 'Nut allergy'],
+            [],
+            IntakeProvenance::VIA_EMAIL,
+            '',
+            7
+        );
+
+        self::assertInstanceOf(\WP_Error::class, $result);
+        self::assertSame('not_recordable', $result->get_error_code());
+    }
+
+    /** The repository responses behind a lesson with question 9 and version 6 outstanding. */
+    private function expectPending(): void
+    {
+        $this->questions->shouldReceive('findByOffering')->with(8, true)->andReturn([
+            new Question(offeringId: 8, label: 'Skill level', id: 2),
+            new Question(offeringId: 8, label: 'Anything we should know?', id: 9),
+        ]);
+        $this->answers->shouldReceive('findByRegistration')->with(Answer::REG_LESSON, 1)->andReturn([
+            new Answer(questionId: 2, registrationType: Answer::REG_LESSON, registrationId: 1, studentId: 5, answerValue: 'Beginner'),
+        ]);
+        $this->gate->shouldReceive('requiredPolicyVersionIds')->andReturn([4, 6]);
+        $this->acceptances->shouldReceive('findByRegistration')->with(PolicyAcceptance::REG_LESSON, 1)->andReturn([
+            new PolicyAcceptance(policyVersionId: 4, studentId: 5, registrationType: PolicyAcceptance::REG_LESSON, registrationId: 1),
+        ]);
+        $this->versions->shouldReceive('findById')->with(6)->andReturn(new PolicyVersion(policyId: 3, versionNumber: 2, id: 6));
+        $this->policies->shouldReceive('findById')->with(3)->andReturn(new Policy(title: 'Cancellation', slug: 'cancellation', id: 3));
+    }
+
+    private function lesson(int $bookedBy = 3): Lesson
+    {
+        return new Lesson(slotId: 10, studentId: 5, instructorId: 3, offeringId: 8, bookedBy: $bookedBy, id: 1);
+    }
+}