# 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**, on the same page as 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        |
| `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                                                  |
|---------------------|------------------|--------------------------------------------------------|
| `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)
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 — 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` — 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           |
|----------|---------------------------------------------------|----------------------|
| `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`, `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`, `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
- `tests/Unit/Registration/QuestionRepositoryTest.php`
- `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
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, under the same
`is_required_child` rule as the signup form. See `parent-guardian-accounts.md`.