unsupervised-scheduler/docs/features/registration-questions.md

Feature: Registration Questions

Overview

Questions come in two scopes:

• Offering scope (scope = 'offering') — intake questions a registrant answers when booking a specific offering; authored per offering by the studio admin or the owning instructor, and stored against the resulting lesson or group enrolment.
• Account scope (scope = 'account') — studio-wide questions every new student answers once at account signup, as a required second step after choosing their name and password. Authored by the studio admin only, and stored against the new user account.

Both scopes share the us_questions / us_question_answers tables, the same field types, and the same authoring page (Offerings → Questions).

Data Model — {prefix}us_questions

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
offering_id	BIGINT UNSIGNED	FK → us_offerings.id for offering-scoped questions; NULL for account-scoped
scope	VARCHAR(20)	offering (default) or account
label	VARCHAR(255)	The question text shown to the registrant
field_type	VARCHAR(20)	text / textarea / select / checkbox
options	TEXT	JSON array of choices (for select); NULL otherwise
is_required	TINYINT(1)	1 = registrant must answer to continue
sort_order	INT	Display order within the scope
is_active	TINYINT(1)	0 = retired, 1 = shown on the form
created_at	DATETIME	Insertion time

Data Model — {prefix}us_question_answers

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
question_id	BIGINT UNSIGNED	FK → us_questions.id
registration_type	VARCHAR(20)	lesson, enrollment, or account
registration_id	BIGINT UNSIGNED	FK → us_lessons.id, us_group_enrollments.id, or the user ID (account scope)
student_id	BIGINT UNSIGNED	WordPress user ID (denormalised for fast lookup)
answer_value	TEXT	The submitted answer (checkbox stored as 0/1)
created_at	DATETIME	Insertion time

The registration_type + registration_id pair is a polymorphic reference shared with us_policy_acceptances (see policies.md), letting answers attach to a private lesson, a group enrolment, or an account signup (account + the user ID).

Offering-scope Flow

1. On the booking form, the front-end calls GET /offerings/{id}/questions.
2. Required questions block submission until answered.
3. Answers are sent in the answers[] array on POST /bookings or POST /enrollments and written to us_question_answers alongside the new registration row.

Account-scope Flow (signup step two)

1. The [us_student_register] page (Auth\RegistrationPage) loads active account-scope questions via QuestionRepository::findByScope('account').
2. The form renders as two steps: step one is email/name/password/policies, step two is the questions. assets/js/register.js reveals step two behind a "Next" button (progressive enhancement — without JS both steps show and the single submit still works). This applies to every signup path (invite, group link, self-approval).
3. On submit, required answers are validated before the user is created (a missing answer returns an error and creates no account); after creation each answered question is written to us_question_answers with registration_type = 'account', registration_id = student_id = <new user ID>.
4. A studio admin reviews the answers on the student's admin screen under Registration Information (Auth\StudentHistory::registrationInfo() lists every account question paired with the student's answer, "—" when unanswered). These rows are excluded from the offering-scope "Intake answers" table.

Admin Interface

Both scopes are edited from Offerings → Questions (Registration\QuestionController):

• Pick an offering to edit its questions, or "Account signup (all registrations)" for the account-scope questions.
• Studio admin (manage_questions + manage_instructors) edits any offering's questions and the account-scope questions.
• Instructor (manage_questions) edits questions only on their own offerings; the account-scope option is hidden.

REST API

Only offering-scope questions are exposed over REST. Account-scope questions are managed through the server-rendered admin page and read directly by RegistrationPage.

Method	Endpoint	Permission
GET	/wp-json/us-scheduler/v1/offerings/{id}/questions	Public
POST	/wp-json/us-scheduler/v1/questions	manage_questions
PATCH	/wp-json/us-scheduler/v1/questions/{id}	manage_questions + owner
DELETE	/wp-json/us-scheduler/v1/questions/{id}	manage_questions + owner

Implementation

• Repositories: Unsupervised\Schedular\Registration\QuestionRepository (findByOffering, findByScope), Unsupervised\Schedular\Registration\AnswerRepository
• Models: Unsupervised\Schedular\Registration\Question (scope, nullable offeringId), Unsupervised\Schedular\Registration\Answer (REG_ACCOUNT)
• Admin controller: Unsupervised\Schedular\Registration\QuestionController
• REST endpoint: Unsupervised\Schedular\Registration\QuestionEndpoint (offering scope only)
• Signup step two: Unsupervised\Schedular\Auth\RegistrationPage, templates/frontend/register-page.php, assets/js/register.js
• Admin review: Unsupervised\Schedular\Auth\StudentHistory::registrationInfo(), templates/admin/student-detail.php
• Schema: us_questions.scope + nullable us_questions.offering_id (requires a plugin version bump so dbDelta runs)
• Nullability repair: dbDelta does not reliably relax a column from NOT NULL to NULL, so sites created before account-scope questions kept offering_id NOT NULL and rejected account inserts. QuestionRepository::ensureOfferingNullable() re-applies the nullable definition (idempotent ALTER … MODIFY); Plugin::boot() runs it once, guarded by the us_questions_offering_nullable option rather than the version gate (affected sites may already be on the current version)

Tests

• tests/Unit/Registration/QuestionRepositoryTest.php
• tests/Unit/Registration/AnswerRepositoryTest.php
• tests/Unit/Registration/QuestionTest.php
• tests/Unit/Registration/AnswerTest.php
• tests/Unit/Auth/RegistrationPageTest.php
• tests/Unit/Auth/StudentHistoryTest.php