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
@@ -36,9 +36,13 @@ class AnswerRepositoryTest extends TestCase
                        && $data['registration_type'] === Answer::REG_LESSON
                        && $data['registration_id'] === 12
                        && $data['student_id'] === 5
-                        && $data['answer_value'] === 'Beginner';
+                        && $data['answer_value'] === 'Beginner'
+                        // Given online: no collection provenance to record.
+                        && null === $data['collected_via']
+                        && null === $data['collected_note']
+                        && 0 === $data['recorded_by'];
                }),
-                ['%d', '%s', '%d', '%d', '%s', '%s']
+                ['%d', '%s', '%d', '%d', '%s', '%s', '%s', '%d', '%s']
            );

        $this->db->insert_id = 77;
@@ -10,7 +10,7 @@ class AnswerTest extends TestCase
 {
    public function testConstructorAndProperties(): void
    {
-        $answer = new Answer(3, Answer::REG_LESSON, 12, 5, 'Beginner', 99);
+        $answer = new Answer(3, Answer::REG_LESSON, 12, 5, 'Beginner', id: 99);

        self::assertSame(3, $answer->questionId);
        self::assertSame(Answer::REG_LESSON, $answer->registrationType);
@@ -0,0 +1,186 @@
+<?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\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\IntakeAudit;
+use Unsupervised\Schedular\Registration\IntakeProvenance;
+use Unsupervised\Schedular\Registration\AnswerRepository;
+use Unsupervised\Schedular\Registration\Question;
+use Unsupervised\Schedular\Registration\QuestionRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class IntakeAuditTest extends TestCase
+{
+    private AnswerRepository&Mockery\MockInterface $answers;
+    private QuestionRepository&Mockery\MockInterface $questions;
+    private AcceptanceRepository&Mockery\MockInterface $acceptances;
+    private PolicyRepository&Mockery\MockInterface $policies;
+    private PolicyVersionRepository&Mockery\MockInterface $versions;
+    private IntakeAudit $detail;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->answers     = Mockery::mock(AnswerRepository::class);
+        $this->questions   = Mockery::mock(QuestionRepository::class);
+        $this->acceptances = Mockery::mock(AcceptanceRepository::class);
+        $this->policies    = Mockery::mock(PolicyRepository::class);
+        $this->versions    = Mockery::mock(PolicyVersionRepository::class);
+
+        $this->detail = new IntakeAudit(
+            $this->answers,
+            $this->questions,
+            $this->acceptances,
+            $this->policies,
+            $this->versions
+        );
+    }
+
+    public function testAnswersPairEachAnswerWithItsQuestionLabel(): void
+    {
+        $this->answers->shouldReceive('findByRegistration')->once()->with(Answer::REG_LESSON, 7)->andReturn([
+            new Answer(questionId: 2, registrationType: Answer::REG_LESSON, registrationId: 7, studentId: 5, answerValue: 'Beginner'),
+            new Answer(questionId: 9, registrationType: Answer::REG_LESSON, registrationId: 7, studentId: 5, answerValue: null),
+        ]);
+
+        $this->questions->shouldReceive('findById')->with(2)->andReturn(new Question(offeringId: 1, label: 'Skill level', id: 2));
+        $this->questions->shouldReceive('findById')->with(9)->andReturn(null);
+
+        self::assertSame(
+            [
+                ['question' => 'Skill level', 'answer' => 'Beginner', 'source' => 'Given online when booking'],
+                ['question' => '#9', 'answer' => '—', 'source' => 'Given online when booking'],
+            ],
+            $this->detail->answers($this->lesson(7))
+        );
+    }
+
+    public function testAcceptancesResolvePolicyTitleVersionAndAuditTrail(): void
+    {
+        $this->acceptances->shouldReceive('findByRegistration')->once()->with(PolicyAcceptance::REG_LESSON, 7)->andReturn([
+            new PolicyAcceptance(
+                policyVersionId: 4,
+                studentId: 5,
+                registrationType: PolicyAcceptance::REG_LESSON,
+                registrationId: 7,
+                ipAddress: '1.2.3.4',
+                acceptedAt: '2026-07-01 10:00:00'
+            ),
+        ]);
+
+        $this->versions->shouldReceive('findById')->with(4)->andReturn(new PolicyVersion(policyId: 3, versionNumber: 2, id: 4));
+        $this->policies->shouldReceive('findById')->with(3)->andReturn(new Policy(title: 'Cancellation', slug: 'cancellation', id: 3));
+
+        self::assertSame(
+            [
+                [
+                    'policy'      => 'Cancellation',
+                    'version'     => 'v2',
+                    'accepted_at' => '2026-07-01 10:00:00',
+                    'ip'          => '1.2.3.4',
+                    'source'      => 'Given online when booking',
+                ],
+            ],
+            $this->detail->acceptances($this->lesson(7))
+        );
+    }
+
+    public function testACollectedElsewhereAnswerNamesItsSourceAndWhoRecordedIt(): void
+    {
+        $user               = Mockery::mock(\WP_User::class);
+        $user->ID           = 7;
+        $user->first_name   = 'Jane';
+        $user->last_name    = 'Doe';
+        $user->nickname     = 'jane';
+        $user->display_name = 'jane';
+        Functions\when('get_userdata')->justReturn($user);
+
+        $this->answers->shouldReceive('findByRegistration')->once()->with(Answer::REG_LESSON, 7)->andReturn([
+            new Answer(
+                questionId: 2,
+                registrationType: Answer::REG_LESSON,
+                registrationId: 7,
+                studentId: 5,
+                answerValue: 'Nut allergy',
+                collectedVia: IntakeProvenance::VIA_PAPER,
+                collectedNote: 'Filed in the studio binder',
+                recordedBy: 7
+            ),
+        ]);
+        $this->questions->shouldReceive('findById')->with(2)->andReturn(new Question(offeringId: 1, label: 'Allergies', id: 2));
+
+        self::assertSame(
+            [[
+                'question' => 'Allergies',
+                'answer'   => 'Nut allergy',
+                'source'   => 'On a signed paper form — Filed in the studio binder — recorded by Jane Doe',
+            ]],
+            $this->detail->answers($this->lesson(7))
+        );
+    }
+
+    public function testSeriesOccurrenceReadsTheAnchorsAnswersAndAcceptances(): void
+    {
+        // Occurrence #12 of a weekly reservation anchored on lesson 7: the intake
+        // and the agreement were recorded once, against the anchor.
+        $occurrence = $this->lesson(12, seriesId: 7);
+
+        $this->answers->shouldReceive('findByRegistration')->once()->with(Answer::REG_LESSON, 7)->andReturn([
+            new Answer(questionId: 2, registrationType: Answer::REG_LESSON, registrationId: 7, studentId: 5, answerValue: 'Beginner'),
+        ]);
+        $this->questions->shouldReceive('findById')->with(2)->andReturn(new Question(offeringId: 1, label: 'Skill level', id: 2));
+
+        $this->acceptances->shouldReceive('findByRegistration')->once()->with(PolicyAcceptance::REG_LESSON, 7)->andReturn([
+            new PolicyAcceptance(
+                policyVersionId: 4,
+                studentId: 5,
+                registrationType: PolicyAcceptance::REG_LESSON,
+                registrationId: 7,
+                ipAddress: '1.2.3.4',
+                acceptedAt: '2026-07-01 10:00:00'
+            ),
+        ]);
+        $this->versions->shouldReceive('findById')->with(4)->andReturn(new PolicyVersion(policyId: 3, versionNumber: 2, id: 4));
+        $this->policies->shouldReceive('findById')->with(3)->andReturn(new Policy(title: 'Cancellation', slug: 'cancellation', id: 3));
+
+        self::assertSame(
+            [['question' => 'Skill level', 'answer' => 'Beginner', 'source' => 'Given online when booking']],
+            $this->detail->answers($occurrence)
+        );
+        self::assertSame(
+            [[
+                'policy'      => 'Cancellation',
+                'version'     => 'v2',
+                'accepted_at' => '2026-07-01 10:00:00',
+                'ip'          => '1.2.3.4',
+                'source'      => 'Given online when booking',
+            ]],
+            $this->detail->acceptances($occurrence)
+        );
+    }
+
+    private function lesson(int $id, ?int $seriesId = null): Lesson
+    {
+        return new Lesson(
+            slotId: 1,
+            studentId: 5,
+            instructorId: 9,
+            offeringId: 1,
+            recurrence: null === $seriesId ? Lesson::RECURRENCE_SINGLE : Lesson::RECURRENCE_WEEKLY,
+            seriesId: $seriesId,
+            id: $id
+        );
+    }
+}
@@ -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);
+    }
+}