Add studio-defined account-registration questions

Studio admins can now define registration questions that every new student answers as a required second step during signup, with each student's answers shown under a "Registration Information" section in the admin. Extends the existing Registration domain: us_questions gains a scope column (offering | account) and a nullable offering_id, and account answers reuse us_question_answers with registration_type = 'account'. Authoring reuses the Offerings -> Questions page via an "Account signup" scope (studio-admin only). The registration form becomes two steps (progressive enhancement via assets/js/register.js; works without JS); required answers are validated before the account is created and apply to all signup paths (invite, group link, self-approval). StudentHistory::registrationInfo() powers the admin section. Bumps the plugin version to 1.1.0 so dbDelta runs the schema migration. Closes #90 Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-07-23 09:59:59 -03:00
parent 34e8f660ab
commit 49c59a950c
23 changed files with 702 additions and 98 deletions
@@ -1,19 +1,30 @@
 # Feature: Registration Questions

 ## Overview
-Each offering can carry a set of intake questions the registrant must answer when booking. Questions are authored per offering by the studio admin or the owning instructor, and answers are stored against the resulting lesson or group enrolment.
+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` — questions are scoped per offering   |
+| `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 offering                           |
+| `sort_order`  | INT              | Display order within the scope                              |
 | `is_active`   | TINYINT(1)       | 0 = retired, 1 = shown on the form                          |
 | `created_at`  | DATETIME         | Insertion time                                             |

@@ -23,27 +34,37 @@ Each offering can carry a set of intake questions the registrant must answer whe
 |---------------------|------------------|--------------------------------------------------------|
 | `id`                | BIGINT UNSIGNED  | Primary key                                            |
 | `question_id`       | BIGINT UNSIGNED  | FK → `us_questions.id`                                 |
-| `registration_type` | VARCHAR(20)      | `lesson` or `enrollment`                               |
-| `registration_id`   | BIGINT UNSIGNED  | FK → `us_lessons.id` or `us_group_enrollments.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 either a
-private lesson or a group enrolment.
+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).

-## Flow
-1. On the registration form, the front-end calls `GET /offerings/{id}/questions`.
+## 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
-Questions are edited from each offering's screen (**Offerings → Questions**).
- Studio admin (`manage_questions`) edits questions on any offering.
- Instructor (`manage_questions`) edits questions only on their own offerings.
+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               |
@@ -52,12 +73,18 @@ Questions are edited from each offering's screen (**Offerings → Questions**).
 | `DELETE` | `/wp-json/us-scheduler/v1/questions/{id}`         | `manage_questions` + owner |

 ## Implementation
- Repositories: `Unsupervised\Schedular\Registration\QuestionRepository`, `Unsupervised\Schedular\Registration\AnswerRepository`
- Models: `Unsupervised\Schedular\Registration\Question`, `Unsupervised\Schedular\Registration\Answer`
+- 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`
+- 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)

 ## 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`