Ask some registration questions of students only

Every account-signup question was asked of everybody who registered, on the
same terms: "school and grade" had to be put to an adult signing themselves
up, and a question a studio needed answered for each student could only be
made required by demanding it of everyone.

A question now carries an audience — everyone, or only the students someone
registers on behalf of — and its own required flag for each side, so optional
for you and required for every student you enrol is expressible. Both settings
are account-scope only: an offering asks its questions once, about the student
being booked, so there is no second audience to differ from, and an offering
question mirrors its single "required" into both columns.

Every caller reads askedOfSelf()/isRequiredForSelf()/isRequiredForChild()
rather than the raw flags, so a students-only question can neither block the
account holder nor have an answer filed against them by a crafted post. The
family screen, which only ever adds a student, is held to the students' rule.

is_required_child arrives from dbDelta defaulting to 0, which would quietly
stop every existing required question being required of the students a
guardian registers — the case it most likely existed for. A one-time backfill
copies is_required across, guarded by its own option so a question later made
optional for students stays that way.

Closes #163

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

docs/features/registration-questions.md

@@ -23,11 +23,32 @@ and the same authoring page (**Offerings → Questions**).
 | `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                      |
+| `audience`    | VARCHAR(20)      | `all` (default) or `child` — who the question is asked of (account scope) |
+| `is_required` | TINYINT(1)       | 1 = the **account holder** must answer to continue          |
+| `is_required_child` | TINYINT(1) | 1 = each **student being registered** 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                                             |
 
+## Audience and Required-ness (account scope)
+An account-scope question is asked in two places, and the two are configured separately:
+
+- **The account holder's own "About you" panel** — shown when they are registering
+  themselves (`self` or `both`). Governed by `audience` (a `child` question is not asked
+  here at all) and by `is_required`.
+- **Each student block** — one per person they are registering on behalf of, on the signup
+  form and on the guardian's family screen. Every question is asked here regardless of
+  `audience`; `is_required_child` decides whether it blocks submission.
+
+That split is what lets a studio ask "School and grade" of children only, or make
+"Previous experience" optional for an adult signing themselves up but required for every
+child they enrol. `audience = 'child'` leaves `is_required` moot — the question never
+reaches the account holder's panel.
+
+`audience` and `is_required_child` are ignored for offering-scope questions: booking and
+enrolment ask their intake questions once, about the student being booked, with no separate
+account-holder form to differ from.
+
 ## Data Model — `{prefix}us_question_answers`
 
 | Column              | Type             | Notes                                                  |
@@ -51,19 +72,24 @@ lesson, a group enrolment, or an account signup (`account` + the user ID).
 
 ## Account-scope Flow (signup)
 1. The `[us_student_register]` page (`Auth\RegistrationPage`) loads active account-scope questions via `QuestionRepository::findByScope('account')`.
-2. The form is a single page. The questions sit in an **About you** panel, alongside the account holder's birth year, between the "Who are you registering?" choice and the students being added. `assets/js/register.js` disables and hides that whole panel when the choice is "on behalf of students" — the questions describe a student and a pure guardian is not one — and puts the same questions in every child block instead. Progressive enhancement: without JS every panel shows 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>`.
+2. The form is a single page. The questions sit in an **About you** panel, alongside the account holder's birth year, between the "Who are you registering?" choice and the students being added — minus any `audience = 'child'` question, which is never asked of the account holder. `assets/js/register.js` disables and hides that whole panel when the choice is "on behalf of students" — the questions describe a student and a pure guardian is not one — and puts the full question set in every child block instead. Progressive enhancement: without JS every panel shows 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) — `is_required` against the account holder's panel, `is_required_child` against each student block; after creation each answered question is written to `us_question_answers` with `registration_type = 'account'`, `registration_id = student_id = <new user ID>`. An answer posted for a `child`-audience question against the account holder is discarded, not stored.
 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.
+- The account-scope form adds **Asked of** (everyone / students only) and a second **Required** checkbox for students; both are hidden for offering scope, where they have no meaning.
 - 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`.
+through the server-rendered admin page and read directly by `RegistrationPage` — a request
+naming one is turned away as not found, since the owner check has no offering to check
+against, so REST can neither read nor overwrite an `audience`. An offering question written
+over REST mirrors its single `is_required` into `is_required_child`, as the admin form and
+the upgrade backfill both do.
 
 | Method   | Endpoint                                          | Permission           |
 |----------|---------------------------------------------------|----------------------|
@@ -74,12 +100,13 @@ through the server-rendered admin page and read directly by `RegistrationPage`.
 
 ## 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`)
+- Models: `Unsupervised\Schedular\Registration\Question` (`scope`, nullable `offeringId`, `audience`, `isRequiredChild`, and the `askedOfSelf()` / `isRequiredForSelf()` / `isRequiredForChild()` readers every caller uses instead of touching `isRequired` directly), `Unsupervised\Schedular\Registration\Answer` (`REG_ACCOUNT`)
 - Admin controller: `Unsupervised\Schedular\Registration\QuestionController`
 - REST endpoint: `Unsupervised\Schedular\Registration\QuestionEndpoint` (offering scope only)
 - Signup form: `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)
+- Schema: `us_questions.scope` + nullable `us_questions.offering_id`, `us_questions.audience`, `us_questions.is_required_child` (each requires a plugin version bump so `dbDelta` runs)
+- Required-for-students backfill: `is_required_child` arrives with `DEFAULT 0`, which would quietly make every existing required question optional for students. `QuestionRepository::backfillChildRequired()` copies `is_required` into it once; `Plugin::boot()` runs it guarded by the `us_questions_child_required_backfilled` option, after the version gate has let `dbDelta` add the column
 - 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
@@ -87,8 +114,10 @@ through the server-rendered admin page and read directly by `RegistrationPage`.
 - `tests/Unit/Registration/AnswerRepositoryTest.php`
 - `tests/Unit/Registration/QuestionTest.php`
 - `tests/Unit/Registration/AnswerTest.php`
+- `tests/Unit/Registration/QuestionFieldTest.php`
 - `tests/Unit/Auth/RegistrationPageTest.php`
 - `tests/Unit/Auth/StudentHistoryTest.php`
+- `tests/Unit/Guardian/FamilyPageTest.php`
 
 ## Per-Child Answers
 For a parent/guardian signup, **account-scope** questions are asked **once per
@@ -96,5 +125,5 @@ child** rather than once per guardian — in practice they describe the student
 (instrument, level, school), not the account holder. Each answer's `student_id`
 and `registration_id` are the child's user ID, so a studio admin reading a
 child's screen sees the information that describes them. The guardian's family
-screen asks the same questions when a child is added later. See
-`parent-guardian-accounts.md`.
+screen asks the same questions when a child is added later, under the same
+`is_required_child` rule as the signup form. See `parent-guardian-accounts.md`.