Add policy, intake, and payment history to the admin student detail view

The student-administration spec deferred three detail-view sections until Payments landed. Adds them now: policy-acceptance history (title, version, context, date), intake answers (label, answer, context), and — gated on manage_billing — payment history with HST breakdown and receipt numbers. New Auth\StudentHistory builds the display rows from per-student queries added to AcceptanceRepository, AnswerRepository, and PaymentRepository; the Payment model now carries created_at so unpaid rows still have a date. Closes #69 Co-Authored-By: Claude Fable 5 <[email protected]>
2026-07-18 18:17:20 -03:00
parent 05d1728248
commit c49171695a
15 changed files with 540 additions and 6 deletions
@@ -0,0 +1,112 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Auth;
+
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\PaymentRepository;
+use Unsupervised\Schedular\Policy\AcceptanceRepository;
+use Unsupervised\Schedular\Policy\PolicyAcceptance;
+use Unsupervised\Schedular\Policy\PolicyRepository;
+use Unsupervised\Schedular\Policy\PolicyVersionRepository;
+use Unsupervised\Schedular\Registration\Answer;
+use Unsupervised\Schedular\Registration\AnswerRepository;
+use Unsupervised\Schedular\Registration\QuestionRepository;
+
+/**
+ * Builds the display rows for the history sections of the admin student detail
+ * view: policy acceptances, intake answers, and payments.
+ */
+class StudentHistory {
+
+	public function __construct(
+		private AcceptanceRepository $acceptances,
+		private PolicyRepository $policies,
+		private PolicyVersionRepository $policyVersions,
+		private AnswerRepository $answers,
+		private QuestionRepository $questions,
+		private PaymentRepository $payments,
+	) {}
+
+	/**
+	 * Every policy acceptance the student has recorded, newest first.
+	 *
+	 * @return list<array{policy: string, version: string, context: string, accepted_at: string}>
+	 */
+	public function policyAcceptances( int $studentId ): array {
+		return array_map(
+			function ( PolicyAcceptance $acceptance ): array {
+				$version = $this->policyVersions->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 ) : '—',
+					'context'     => $this->contextLabel( $acceptance->registrationType, $acceptance->registrationId ),
+					'accepted_at' => $acceptance->acceptedAt ?? '',
+				];
+			},
+			$this->acceptances->findByStudent( $studentId )
+		);
+	}
+
+	/**
+	 * Every intake answer the student has submitted, newest registration first.
+	 *
+	 * @return list<array{question: string, answer: string, context: string}>
+	 */
+	public function intakeAnswers( int $studentId ): array {
+		return array_map(
+			function ( Answer $answer ): array {
+				$question = $this->questions->findById( $answer->questionId );
+
+				return [
+					'question' => $question ? $question->label : sprintf( '#%d', $answer->questionId ),
+					'answer'   => $answer->answerValue ?? '—',
+					'context'  => $this->contextLabel( $answer->registrationType, $answer->registrationId ),
+				];
+			},
+			$this->answers->findByStudent( $studentId )
+		);
+	}
+
+	/**
+	 * Every payment for the student, newest first.
+	 *
+	 * @return list<array{created_at: string, context: string, method: string, status: string, amount: float, tax_amount: float, total: float, currency: string, receipt: string}>
+	 */
+	public function payments( int $studentId ): array {
+		return array_map(
+			fn( Payment $payment ): array => [
+				'created_at' => $payment->createdAt ?? '',
+				'context'    => $this->contextLabel( $payment->registrationType, $payment->registrationId ),
+				'method'     => $payment->method,
+				'status'     => $payment->status,
+				'amount'     => $payment->amount,
+				'tax_amount' => $payment->taxAmount,
+				'total'      => $payment->total(),
+				'currency'   => $payment->currency,
+				'receipt'    => $payment->receiptNumber ?? '—',
+			],
+			$this->payments->findByStudent( $studentId )
+		);
+	}
+
+	/**
+	 * Human label for a polymorphic registration target.
+	 */
+	private function contextLabel( string $registrationType, int $registrationId ): string {
+		switch ( $registrationType ) {
+			case PolicyAcceptance::REG_ACCOUNT:
+				return __( 'Account signup', 'unsupervised-schedular' );
+			case PolicyAcceptance::REG_LESSON:
+				/* translators: %d: the lesson id */
+				return sprintf( __( 'Lesson #%d', 'unsupervised-schedular' ), $registrationId );
+			case PolicyAcceptance::REG_ENROLLMENT:
+				/* translators: %d: the group-class enrolment id */
+				return sprintf( __( 'Enrolment #%d', 'unsupervised-schedular' ), $registrationId );
+			default:
+				return sprintf( '%s #%d', $registrationType, $registrationId );
+		}
+	}
+}