thatguygriff
f3f5c7801f
CI / No Debug Code (pull_request) Successful in 3s
CI / Tests (PHP 8.1) (pull_request) Successful in 43s
CI / Tests (PHP 8.3) (pull_request) Successful in 49s
CI / Tests (PHP 8.2) (pull_request) Successful in 59s
CI / Coding Standards (pull_request) Successful in 1m11s
CI / PHPStan (pull_request) Successful in 1m20s
CI / Build Plugin Zip (pull_request) Has been skipped
Four fixes from a security review pass: - Neutralise CSV formula injection in the payments export: fields with a leading =, +, -, @, tab, or CR (e.g. a hostile student display name) are apostrophe-prefixed in PaymentReport::csvLine() so they open as text in Excel/Google Sheets. Fixes #39. - Sanitise policy bodies with wp_kses_post at output in PolicyEndpoint::index() (the booking JS renders that HTML raw), so a future write path that forgets kses can never become stored XSS. Fixes #40. - Store invite tokens hashed (SHA-256) at rest: a database leak can no longer redeem pending invites. The registration link is shown once, at creation; the pending list shows email/invited date; lookups hash the submitted token. Existing plaintext pending invites must be re-issued. Fixes #41. - Validate availability slot datetimes on both creation paths (REST and admin form) via AvailabilitySlot::normalizeDateTime(): canonical and datetime-local forms normalise to Y-m-d H:i:s, garbage and end <= start are rejected (REST 400) instead of reaching the DATETIME column or throwing inside the weekly-series date arithmetic. Fixes #42. composer test (204 tests, 594 assertions), PHPStan L6, and PHPCS all green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
64 lines
3.8 KiB
Markdown
64 lines
3.8 KiB
Markdown
# Feature: Availability Management
|
|
|
|
## Overview
|
|
Instructors define date/time windows during which they are available for private lessons. Students book from these windows. Windows carry a lesson length and may be generated as a weekly-recurring series.
|
|
|
|
## Data Model — `{prefix}us_availability`
|
|
|
|
| Column | Type | Notes |
|
|
|--------------------|------------------|-------------------------------------------------------------|
|
|
| `id` | BIGINT UNSIGNED | Primary key |
|
|
| `instructor_id` | BIGINT UNSIGNED | WordPress user ID |
|
|
| `offering_id` | BIGINT UNSIGNED | Nullable FK → `us_offerings.id` (private-lesson type) |
|
|
| `start_dt` | DATETIME | Slot start — stored as `Y-m-d H:i:s` |
|
|
| `end_dt` | DATETIME | Slot end — stored as `Y-m-d H:i:s` |
|
|
| `duration_minutes` | SMALLINT | Lesson length the window accommodates (e.g. 30, 60) |
|
|
| `is_booked` | TINYINT(1) | 0 = available, 1 = booked |
|
|
| `recurrence_group` | BIGINT UNSIGNED | Nullable — weekly-recurring windows share one group id |
|
|
| `created_at` | DATETIME | Insertion time |
|
|
|
|
A window's `duration_minutes` is matched against the offering a student picks: a
|
|
30-minute private offering can only be booked into a window whose
|
|
`duration_minutes` accommodates it.
|
|
|
|
## Weekly-Recurring Windows
|
|
Instructors may generate a window weekly across a date range. Each occurrence is a
|
|
separate row sharing one `recurrence_group` id, so a recurring set can be added or
|
|
removed together while individual occurrences are still booked independently.
|
|
|
|
## Admin Interface
|
|
Instructors access **My Availability** in wp-admin (`?page=us-availability`).
|
|
- Add a slot: provide start/end datetime, duration, and (optionally) a linked private-lesson offering
|
|
- Add a weekly series: provide the weekday/time plus a date range
|
|
- Delete a slot: only allowed if `is_booked = 0`
|
|
|
|
## Public Calendar
|
|
The front-end booking shortcode renders a month/week calendar of open windows,
|
|
populated from `GET /availability`. Students can filter by instructor and by
|
|
offering/duration before selecting a slot to register for.
|
|
|
|
## REST API
|
|
| Method | Endpoint | Permission |
|
|
|----------|-----------------------------------------------|------------------------------------|
|
|
| `GET` | `/wp-json/us-scheduler/v1/availability` | `book_lesson` |
|
|
| `POST` | `/wp-json/us-scheduler/v1/availability` | `manage_availability` |
|
|
| `DELETE` | `/wp-json/us-scheduler/v1/availability/{id}` | `manage_availability` + slot owner |
|
|
|
|
`GET` supports query params: `instructor_id`, `offering_id`, `duration_minutes`, `from` (datetime), `to` (datetime).
|
|
|
|
`POST` validates `start_dt`/`end_dt` (admin form and REST alike) via
|
|
`AvailabilitySlot::normalizeDateTime()`: the canonical `Y-m-d H:i[:s]` and HTML
|
|
`datetime-local` (`Y-m-d\TH:i[:s]`) forms are normalised to `Y-m-d H:i:s`;
|
|
anything else — or an end not after the start — is rejected (REST responds
|
|
`400 invalid_datetime`; the admin form is a no-op).
|
|
|
|
## Implementation
|
|
- Repository: `Unsupervised\Schedular\Availability\AvailabilityRepository`
|
|
- Model: `Unsupervised\Schedular\Availability\AvailabilitySlot`
|
|
- Admin controller: `Unsupervised\Schedular\Availability\AvailabilityController`
|
|
- REST endpoint: `Unsupervised\Schedular\Availability\AvailabilityEndpoint`
|
|
|
|
## Tests
|
|
- `tests/Unit/Availability/AvailabilityRepositoryTest.php`
|
|
- `tests/Unit/Availability/AvailabilitySlotTest.php`
|