thatguygriffandClaude Opus 4.8
49c59a950c
CI / Tests (PHP 8.2) (pull_request) Successful in 44s
CI / Tests (PHP 8.1) (pull_request) Successful in 45s
CI / No Debug Code (pull_request) Successful in 2s
CI / Coding Standards (pull_request) Successful in 2m46s
CI / PHPStan (pull_request) Successful in 2m58s
CI / Tests (PHP 8.3) (pull_request) Successful in 2m41s
CI / Build Plugin Zip (pull_request) Skipped
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]>
91 lines
6.9 KiB
Markdown
91 lines
6.9 KiB
Markdown
# 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)
|
|
|
|
## 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`
|