Add Registration Questions domain (per-offering intake forms)

Implements #5: studio admin / instructors author intake questions scoped
per offering; answers are stored against a lesson or group enrolment via a
polymorphic registration reference.

- src/Registration/: Question + Answer value objects, QuestionRepository
  and AnswerRepository, QuestionEndpoint (REST), QuestionController +
  templates/admin/questions.php (Offerings -> Questions submenu)
- us_questions and us_question_answers tables in Schema.php
- REST: public GET /offerings/{id}/questions; POST/PATCH/DELETE /questions
  gated by manage_questions + offering ownership (owner or studio admin)
- Field types text/textarea/select/checkbox; select options stored as JSON
- Wiring in Plugin, RestRegistrar, AdminMenu

AnswerRepository is built now and consumed by the booking/enrolment flow
in #3/#4.

Tests: tests/Unit/Registration/ (19 tests). composer test (63 total), cs,
and PHPStan level 6 all pass.

Refs #5

Co-Authored-By: Claude Opus 4.8 <[email protected]>

src/Registration/QuestionEndpoint.php

@@ -0,0 +1,198 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Registration;
+
+use Unsupervised\Schedular\Auth\RoleManager;
+use Unsupervised\Schedular\Offering\OfferingRepository;
+
+class QuestionEndpoint {
+
+	public function __construct(
+		private QuestionRepository $questions,
+		private OfferingRepository $offerings,
+	) {}
+
+	public function registerRoutes( string $route_namespace ): void {
+		register_rest_route(
+			$route_namespace,
+			'/offerings/(?P<id>\d+)/questions',
+			[
+				[
+					'methods'             => \WP_REST_Server::READABLE,
+					'callback'            => [ $this, 'index' ],
+					'permission_callback' => '__return_true',
+				],
+			]
+		);
+
+		register_rest_route(
+			$route_namespace,
+			'/questions',
+			[
+				[
+					'methods'             => \WP_REST_Server::CREATABLE,
+					'callback'            => [ $this, 'create' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+
+		register_rest_route(
+			$route_namespace,
+			'/questions/(?P<id>\d+)',
+			[
+				[
+					'methods'             => \WP_REST_Server::EDITABLE,
+					'callback'            => [ $this, 'update' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+				[
+					'methods'             => \WP_REST_Server::DELETABLE,
+					'callback'            => [ $this, 'delete' ],
+					'permission_callback' => [ $this, 'canManage' ],
+				],
+			]
+		);
+	}
+
+	public function index( \WP_REST_Request $request ): \WP_REST_Response {
+		$questions = $this->questions->findByOffering( absint( $request->get_param( 'id' ) ), activeOnly: true );
+
+		return new \WP_REST_Response( array_map( fn( Question $q ) => $q->toArray(), $questions ), 200 );
+	}
+
+	public function create( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$offeringId = absint( $request->get_param( 'offering_id' ) );
+		$ownerCheck = $this->requireOfferingOwner( $offeringId );
+		if ( $ownerCheck instanceof \WP_Error ) {
+			return $ownerCheck;
+		}
+
+		$label = sanitize_text_field( (string) $request->get_param( 'label' ) );
+		if ( '' === $label ) {
+			return $this->invalid( __( 'A question label is required.', 'unsupervised-schedular' ) );
+		}
+
+		$fieldType = (string) ( $request->get_param( 'field_type' ) ?? Question::FIELD_TEXT );
+		if ( ! in_array( $fieldType, Question::VALID_FIELD_TYPES, true ) ) {
+			return $this->invalid( __( 'Invalid field type.', 'unsupervised-schedular' ) );
+		}
+
+		$question = new Question(
+			offeringId: $offeringId,
+			label:      $label,
+			fieldType:  $fieldType,
+			options:    $this->sanitizeOptions( $request->get_param( 'options' ) ),
+			isRequired: (bool) $request->get_param( 'is_required' ),
+			sortOrder:  (int) $request->get_param( 'sort_order' ),
+			isActive:   null === $request->get_param( 'is_active' ) ? true : (bool) $request->get_param( 'is_active' ),
+		);
+
+		$id = $this->questions->insert( $question );
+
+		return new \WP_REST_Response( [ 'id' => $id ], 201 );
+	}
+
+	public function update( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$id       = absint( $request->get_param( 'id' ) );
+		$existing = $this->questions->findById( $id );
+
+		if ( null === $existing ) {
+			return new \WP_Error( 'not_found', __( 'Question not found.', 'unsupervised-schedular' ), [ 'status' => 404 ] );
+		}
+
+		$ownerCheck = $this->requireOfferingOwner( $existing->offeringId );
+		if ( $ownerCheck instanceof \WP_Error ) {
+			return $ownerCheck;
+		}
+
+		$fieldType = $request->has_param( 'field_type' ) ? (string) $request->get_param( 'field_type' ) : $existing->fieldType;
+		if ( ! in_array( $fieldType, Question::VALID_FIELD_TYPES, true ) ) {
+			return $this->invalid( __( 'Invalid field type.', 'unsupervised-schedular' ) );
+		}
+
+		$question = new Question(
+			offeringId: $existing->offeringId,
+			label:      $request->has_param( 'label' ) ? sanitize_text_field( (string) $request->get_param( 'label' ) ) : $existing->label,
+			fieldType:  $fieldType,
+			options:    $request->has_param( 'options' ) ? $this->sanitizeOptions( $request->get_param( 'options' ) ) : $existing->options,
+			isRequired: $request->has_param( 'is_required' ) ? (bool) $request->get_param( 'is_required' ) : $existing->isRequired,
+			sortOrder:  $request->has_param( 'sort_order' ) ? (int) $request->get_param( 'sort_order' ) : $existing->sortOrder,
+			isActive:   $request->has_param( 'is_active' ) ? (bool) $request->get_param( 'is_active' ) : $existing->isActive,
+			id:         $id,
+		);
+
+		$this->questions->update( $id, $question );
+
+		return new \WP_REST_Response( $question->toArray(), 200 );
+	}
+
+	public function delete( \WP_REST_Request $request ): \WP_REST_Response|\WP_Error {
+		$id       = absint( $request->get_param( 'id' ) );
+		$existing = $this->questions->findById( $id );
+
+		if ( null === $existing ) {
+			return new \WP_Error( 'not_found', __( 'Question not found.', 'unsupervised-schedular' ), [ 'status' => 404 ] );
+		}
+
+		$ownerCheck = $this->requireOfferingOwner( $existing->offeringId );
+		if ( $ownerCheck instanceof \WP_Error ) {
+			return $ownerCheck;
+		}
+
+		$this->questions->delete( $id );
+
+		return new \WP_REST_Response( null, 204 );
+	}
+
+	public function canManage(): bool {
+		return is_user_logged_in() && current_user_can( RoleManager::CAP_MANAGE_QUESTIONS );
+	}
+
+	/**
+	 * Ensure the offering exists and the caller owns it (or is a studio admin).
+	 */
+	private function requireOfferingOwner( int $offeringId ): ?\WP_Error {
+		$offering = $this->offerings->findById( $offeringId );
+
+		if ( null === $offering ) {
+			return new \WP_Error( 'not_found', __( 'Offering not found.', 'unsupervised-schedular' ), [ 'status' => 404 ] );
+		}
+
+		$ownsOrManagesAll = get_current_user_id() === $offering->instructorId
+			|| current_user_can( RoleManager::CAP_MANAGE_INSTRUCTORS );
+
+		if ( ! $ownsOrManagesAll ) {
+			return new \WP_Error( 'forbidden', __( 'You cannot manage questions for this offering.', 'unsupervised-schedular' ), [ 'status' => 403 ] );
+		}
+
+		return null;
+	}
+
+	/**
+	 * Normalise a submitted options array into a clean list of strings.
+	 *
+	 * @return list<string>|null
+	 */
+	private function sanitizeOptions( mixed $value ): ?array {
+		if ( ! is_array( $value ) || [] === $value ) {
+			return null;
+		}
+
+		$options = array_values(
+			array_filter(
+				array_map(
+					static fn( $option ): string => sanitize_text_field( (string) $option ),
+					$value
+				)
+			)
+		);
+
+		return [] === $options ? null : $options;
+	}
+
+	private function invalid( string $message ): \WP_Error {
+		return new \WP_Error( 'invalid_question', $message, [ 'status' => 400 ] );
+	}
+}