unsupervised-scheduler/src/Registration/IntakeAudit.php

<?php
declare(strict_types=1);

namespace Unsupervised\Schedular\Registration;

use Unsupervised\Schedular\Auth\UserName;
use Unsupervised\Schedular\Policy\AcceptanceRepository;
use Unsupervised\Schedular\Policy\PolicyAcceptance;
use Unsupervised\Schedular\Policy\PolicyRepository;
use Unsupervised\Schedular\Policy\PolicyVersionRepository;

/**
 * Builds the display rows for one registration's audit trail: the intake answers
 * the student gave and the policy versions they accepted. Used by the admin
 * lesson detail view and the group-class enrolment detail view alike, mirroring
 * the per-student history in {@see \Unsupervised\Schedular\Auth\StudentHistory}.
 *
 * Which rows belong to the registration is the subject's own business
 * ({@see IntakeSubject::intakeRegistrationId()}) — notably, a weekly lesson
 * series is answered for and agreed to once, against its anchor, so every
 * occurrence reads the same trail rather than only the first looking answered.
 */
class IntakeAudit {

	public function __construct(
		private AnswerRepository $answers,
		private QuestionRepository $questions,
		private AcceptanceRepository $acceptances,
		private PolicyRepository $policies,
		private PolicyVersionRepository $versions,
	) {}

	/**
	 * The intake-question answers recorded for this registration, in submission
	 * order.
	 *
	 * @return list<array{question: string, answer: string, source: string}>
	 */
	public function answers( IntakeSubject $subject ): array {
		return array_map(
			function ( Answer $answer ): array {
				$question = $this->questions->findById( $answer->questionId );
				$value    = $answer->answerValue ?? '';

				return [
					'question' => $question ? $question->label : sprintf( '#%d', $answer->questionId ),
					'answer'   => '' === $value ? '—' : $value,
					'source'   => $this->source( $answer->collectedVia, $answer->collectedNote, $answer->recordedBy ),
				];
			},
			$this->answers->findByRegistration( $subject->intakeRegistrationType(), $subject->intakeRegistrationId() )
		);
	}

	/**
	 * Where a recorded row came from: given online by the student, or collected
	 * some other way and typed in — in which case who typed it is named, since an
	 * unattributed transcription is worth much less than an attributed one.
	 */
	private function source( ?string $collectedVia, ?string $collectedNote, int $recordedBy ): string {
		$described = IntakeProvenance::describe( $collectedVia, $collectedNote );

		if ( null === $collectedVia || '' === $collectedVia || $recordedBy <= 0 ) {
			return $described;
		}

		$user = get_userdata( $recordedBy );

		return sprintf(
			/* translators: 1: how the answer was collected, 2: name of the staff member who recorded it. */
			__( '%1$s — recorded by %2$s', 'unsupervised-schedular' ),
			$described,
			UserName::format( $user instanceof \WP_User ? $user : null, $recordedBy )
		);
	}

	/**
	 * The policy versions the student accepted for this registration, with the
	 * captured acceptance time and IP for the audit trail.
	 *
	 * @return list<array{policy: string, version: string, accepted_at: string, ip: string, source: string}>
	 */
	public function acceptances( IntakeSubject $subject ): array {
		return array_map(
			function ( PolicyAcceptance $acceptance ): array {
				$version = $this->versions->findById( $acceptance->policyVersionId );
				$policy  = $version ? $this->policies->findById( $version->policyId ) : null;

				return [
					'policy'      => $policy ? $policy->title : sprintf( '#%d', $acceptance->policyVersionId ),
					'version'     => $version ? sprintf( 'v%d', $version->versionNumber ) : '—',
					'accepted_at' => $acceptance->acceptedAt ?? '',
					'ip'          => $acceptance->ipAddress ?? '',
					'source'      => $this->source( $acceptance->collectedVia, $acceptance->collectedNote, $acceptance->recordedBy ),
				];
			},
			$this->acceptances->findByRegistration( $subject->intakeRegistrationType(), $subject->intakeRegistrationId() )
		);
	}
}