thatguygriffandClaude Opus 5
4a41ba96fb
CI / Tests (PHP 8.2) (pull_request) Successful in 42s
CI / Tests (PHP 8.3) (pull_request) Successful in 2m45s
CI / Build Plugin Zip (pull_request) Skipped
CI / Tests (PHP 8.1) (pull_request) Failing after 52s
CI / No Debug Code (pull_request) Successful in 2s
CI / PHPStan (pull_request) Successful in 2m52s
CI / Coding Standards (pull_request) Successful in 2m57s
A parent registers once and manages lessons for one or more children, who need no login of their own. A child is a real wp_users row with the student role but no usable login — so student_id keeps meaning "a WordPress user" on every table, and booking, credits, policies and enrolments work unchanged. A us_guardians link table maps guardian to child. The signup form gains a parent/guardian tick that reveals a block per child, with the account-signup questions asked per child rather than per guardian — they describe the student, not the account holder. Signup policies are recorded once per child with the guardian as the acceptor, which is the record that actually means something. A family that half-creates is rolled back entirely rather than leaving a guardian who cannot re-register. The booking and enrolment forms gain a "Who is this for?" picker listing children first, so the default selection is never the parent — booking for the wrong child is correctable, quietly billing a parent for their kid's lesson is not. POST /bookings and POST /enrollments take an optional student_id honoured only for that child's guardian; anything else is a 403. That check is the authorisation boundary of the feature. Payments and credits gain a payer: the charge names the child it was for and the guardian who owes it, so per-child reporting is unchanged while notices, receipts and the payment step reach the parent. Credit is held by the payer, so one child's cancellation can settle a sibling's charge, and the daily billing scan sends a guardian one notice covering every child. Closes #132 Co-Authored-By: Claude Opus 5 <[email protected]>
93 lines
7.5 KiB
Markdown
93 lines
7.5 KiB
Markdown
# Feature: Policies
|
|
|
|
## Overview
|
|
The studio admin drafts, versions, and publishes policies (e.g. cancellation, payment, code of conduct). Registrants must read and accept the current published version of every policy before they can book. Acceptance is recorded against the specific version, so when a policy is updated students must re-accept it at their next booking.
|
|
|
|
## Data Model — `{prefix}us_policies`
|
|
|
|
| Column | Type | Notes |
|
|
|----------------------|------------------|------------------------------------------------|
|
|
| `id` | BIGINT UNSIGNED | Primary key |
|
|
| `title` | VARCHAR(191) | Display name |
|
|
| `slug` | VARCHAR(191) | Unique key, e.g. `cancellation` |
|
|
| `current_version_id` | BIGINT UNSIGNED | Nullable FK → `us_policy_versions.id` (published) |
|
|
| `acceptance_scope` | VARCHAR(20) | `signup` / `booking` / `both` — when it must be accepted |
|
|
| `created_at` | DATETIME | Insertion time |
|
|
|
|
## Data Model — `{prefix}us_policy_versions`
|
|
|
|
| Column | Type | Notes |
|
|
|------------------|------------------|----------------------------------------------------|
|
|
| `id` | BIGINT UNSIGNED | Primary key |
|
|
| `policy_id` | BIGINT UNSIGNED | FK → `us_policies.id` |
|
|
| `version_number` | INT | Increments per policy, starting at 1 |
|
|
| `body` | LONGTEXT | The policy text (HTML/markdown) |
|
|
| `status` | VARCHAR(20) | `draft` / `published` / `archived` |
|
|
| `published_at` | DATETIME | When published; NULL for drafts |
|
|
| `created_at` | DATETIME | Insertion time |
|
|
|
|
## Data Model — `{prefix}us_policy_acceptances`
|
|
|
|
| Column | Type | Notes |
|
|
|---------------------|------------------|--------------------------------------------------------|
|
|
| `id` | BIGINT UNSIGNED | Primary key |
|
|
| `policy_version_id` | BIGINT UNSIGNED | FK → `us_policy_versions.id` (the exact version accepted) |
|
|
| `student_id` | BIGINT UNSIGNED | WordPress user ID |
|
|
| `registration_type` | VARCHAR(20) | `lesson` or `enrollment` |
|
|
| `registration_id` | BIGINT UNSIGNED | FK → `us_lessons.id` or `us_group_enrollments.id` |
|
|
| `accepted_at` | DATETIME | Timestamp of acceptance |
|
|
| `ip_address` | VARCHAR(45) | IP captured at acceptance (audit trail) |
|
|
|
|
## Versioning & Acceptance Rules
|
|
- Editing a published policy creates a new `draft` version; the old version stays `published` until the draft is published.
|
|
- Editing a `draft` version rewrites it in place — nobody has accepted it yet, so there is nothing to preserve and no new version is created. `PATCH /policies/{id}/versions/{vid}` allows only this case; the admin page also accepts an edit to a `published` or `archived` version and branches a new draft from it.
|
|
- Publishing a draft sets it `published`, stamps `published_at`, archives the prior version, and points `us_policies.current_version_id` at it.
|
|
- The registration gate requires acceptance of the `current_version_id` of every policy. Because acceptance is tied to `policy_version_id`, a newly published version is unaccepted and must be re-accepted at the student's next booking.
|
|
|
|
## Admin Interface
|
|
**Policies** in wp-admin (`manage_policies`, studio admin only):
|
|
- Create a policy; draft version bodies
|
|
- View the content of any version (`?page=us-policies&policy_id={id}&version_id={vid}`), whatever its status
|
|
- Edit from the viewer: a draft is saved in place; editing a published or archived version instead saves the text as a **new draft version** (the viewer follows to it), so text students have already accepted is never rewritten
|
|
- Publish a draft version; view acceptance history per version
|
|
|
|
## Rendering a Policy Body
|
|
Bodies are typed into a plain textarea, so most are written as blank-line-separated prose with no markup. `PolicyVersion::bodyHtml()` is the single render path — `wp_kses_post()` then `wpautop()`, the same treatment WordPress gives post content — so unmarked-up text arrives as real paragraphs and bodies that do carry markup are left alone. It feeds the booking/enrolment JSON (`GET /policies`), the signup form, and the admin version viewer, which therefore previews exactly what students see.
|
|
|
|
The acceptance markup (`.us-policy` / `.us-policy-body`) is styled in `assets/css/frontend.css` as a bounded, vertically scrolling reading box with `overflow-wrap: break-word`, so a long policy or a pasted URL cannot force a horizontal scrollbar or push the accept checkbox out of view. `RegistrationPage` enqueues that stylesheet for the signup gate; `BookingPage` and `GroupClassPage` already did.
|
|
|
|
## REST API
|
|
| Method | Endpoint | Permission |
|
|
|----------|-----------------------------------------------------------------|-------------------|
|
|
| `GET` | `/wp-json/us-scheduler/v1/policies` | Public (current published versions) |
|
|
| `POST` | `/wp-json/us-scheduler/v1/policies` | `manage_policies` |
|
|
| `POST` | `/wp-json/us-scheduler/v1/policies/{id}/versions` | `manage_policies` |
|
|
| `PATCH` | `/wp-json/us-scheduler/v1/policies/{id}/versions/{vid}` | `manage_policies` |
|
|
| `POST` | `/wp-json/us-scheduler/v1/policies/{id}/versions/{vid}/publish` | `manage_policies` |
|
|
|
|
Acceptances are not posted directly — they are written as part of `POST /bookings`
|
|
and `POST /enrollments` via the `accepted_policy_version_ids[]` field, which must
|
|
cover every policy's current version or the registration is rejected.
|
|
|
|
## Implementation
|
|
- Repositories: `Unsupervised\Schedular\Policy\PolicyRepository`, `Unsupervised\Schedular\Policy\PolicyVersionRepository`, `Unsupervised\Schedular\Policy\AcceptanceRepository`
|
|
- Models: `Unsupervised\Schedular\Policy\Policy`, `Unsupervised\Schedular\Policy\PolicyVersion`, `Unsupervised\Schedular\Policy\PolicyAcceptance`
|
|
- Service: `Unsupervised\Schedular\Policy\PolicyService` — orchestrates create / add-draft / publish across the policies and versions tables (archive prior current version, stamp `published_at`, repoint `current_version_id`)
|
|
- Admin controller: `Unsupervised\Schedular\Policy\PolicyController`
|
|
- REST endpoint: `Unsupervised\Schedular\Policy\PolicyEndpoint`
|
|
|
|
## Tests
|
|
- `tests/Unit/Policy/PolicyValueObjectsTest.php`
|
|
- `tests/Unit/Policy/PolicyRepositoryTest.php`
|
|
- `tests/Unit/Policy/PolicyVersionRepositoryTest.php`
|
|
- `tests/Unit/Policy/AcceptanceRepositoryTest.php`
|
|
- `tests/Unit/Policy/PolicyServiceTest.php`
|
|
- `tests/Unit/Policy/PolicyControllerTest.php`
|
|
- `tests/Unit/Policy/PolicyEndpointTest.php`
|
|
|
|
## Who Accepted
|
|
`us_policy_acceptances.accepted_by` records the person who actually ticked the
|
|
box, where that differs from `student_id` — a guardian agreeing on a child's
|
|
behalf. It defaults to 0, read back as "the student agreed for themselves"
|
|
(`PolicyAcceptance::acceptorOrStudent()`). See `parent-guardian-accounts.md`.
|