unsupervised-scheduler/docs/features/student-administration.md

Feature: Student Administration

Overview

A studio-admin area to browse students, drill into one student's history and upcoming activity — lessons and group-class enrolments — and act on their behalf: cancel a lesson, withdraw them from a group class, or fix their account details.

Data Model

No new tables. The views are composed from existing data:

• Students are WordPress users with the us_student role (get_users, get_userdata).
• Lessons come from {prefix}us_lessons (with {prefix}us_availability for slot times).
• Group-class enrolments come from {prefix}us_group_enrollments.
• Policy acceptances come from {prefix}us_policy_acceptances (with the policy and version tables for titles/numbers).
• Intake answers come from {prefix}us_question_answers (with {prefix}us_questions for labels).
• Payments come from {prefix}us_payments.

Admin Interface

Students in wp-admin (manage_students, studio admin only):

• List — every us_student user: display name, email, registered date, and quick counts (upcoming lessons, active group enrolments). Each row links to the detail view.
• Detail (?student_id=):
  • Account — display name, email, registered date.
  • Upcoming lessons and Past lessons — split by the linked availability slot's start_dt; each shows date/time, offering, instructor, and status. Upcoming lessons also lists the student's upcoming group-class sessions (GroupClass\SessionSchedule, marked "group class"), so one table answers "what are they booked into next week?". Only upcoming ones: past dates would bury the lessons, and the enrolment table below already holds the history.
  • Group-class enrolments — active/past, with offering title and status.
  • Policy acceptances — every acceptance the student has recorded, newest first: policy title, version, context (account signup / lesson / enrolment), and when it was accepted.
  • Intake answers — every registration-question answer, newest first: question label, answer, and the registration it was given for.
  • Account credit (manage_billing only) — the student's available credit balance plus every credit (date, reason, amount, remaining, status). Credit comes from cancelled paid lessons and is applied automatically to upcoming scheduled billing. See credits.md.
  • Payment history (manage_billing only) — every payment, newest first: date, context, method, status, subtotal, HST, total, and receipt number.

Admin actions (detail view)

All actions are nonce-protected POSTs handled on the detail page:

• Edit account — display name and email. The email must be valid and not in use by another account.
• Cancel lesson — on any non-cancelled upcoming lesson. Uses the same path as student-initiated cancellation: the lesson is marked cancelled, the availability slot is freed for rebooking, and a still-pending payment is voided. A paid lesson is credited back to the student's account (see credits.md) rather than refunded.
• Withdraw — on an active group-class enrolment: marked cancelled (freeing its capacity seat), with the same pending-payment voiding. This is the only way to remove a class; the group-class rows in Upcoming lessons carry no Cancel action, because there is no such thing as cancelling one session of a term.

Deleting a user

Deleting a WordPress user is a core action that knows nothing about lessons, so Auth\DeletedUserCleanup hooks delete_user (and wpmu_delete_user) and gives back what the account was holding: every upcoming lesson is marked cancelled, its availability slot released for rebooking, and its still-pending payment voided; every active group-class enrolment is cancelled and its pending payment voided. Without it the slots stayed marked booked and unbookable by anyone else, the lessons stayed on the instructor's schedule under a name that no longer resolved, and a class kept a seat filled by nobody.

Past lessons are deliberately untouched: they happened, they may have been paid for, and the payment report has to keep adding up. No account credit is issued for a paid lesson either, unlike a cancellation the student asks for — a credit can only be spent on the account being deleted, so a refund owed to someone who has left is the studio's decision to make and record.

Capabilities

• manage_students — studio admin (administrators inherit it via the user_has_cap filter). No new capabilities or tables.

Implementation

• Admin controller: Unsupervised\Schedular\Auth\StudentController (list + detail)
• Templates: templates/admin/students.php, templates/admin/student-detail.php
• Reuses Booking\BookingRepository::findByStudent + countUpcomingForStudent, Availability\AvailabilityRepository::findById, Offering\OfferingRepository::findById, GroupClass\EnrollmentRepository::findByStudent + countActiveForStudent
• History sections: Auth\StudentHistory builds the display rows from Policy\AcceptanceRepository::findByStudent, Registration\AnswerRepository::findByStudent, and Payment\PaymentRepository::findByStudent, resolving policy/version titles and question labels (unit-tested with mocked repositories).
• Actions: Auth\StudentActions — cancel lesson / withdraw enrolment (both refuse records that don't belong to the student, and reuse Payment\PaymentService::voidPending) and account updates via wp_update_user (unit-tested with mocked repositories).
• Group-class sessions in the upcoming table: GroupClass\SessionSchedule::upcomingForStudent()
• Deletion cleanup: Auth\DeletedUserCleanup (hooked in Plugin::boot())
• Upcoming/past split: Auth\StudentSchedule::partition() (pure, unit-tested)
• The upcoming/past split is extracted into a small pure helper so it is unit-testable (the controller itself follows the repo convention of not being unit-tested).

Tests

• tests/Unit/Auth/StudentScheduleTest.php (the pure upcoming/past split helper)
• tests/Unit/Auth/DeletedUserCleanupTest.php (release on user deletion)
• tests/Unit/Auth/StudentHistoryTest.php (history display rows + fallbacks)
• tests/Unit/Auth/StudentActionsTest.php (cancel/withdraw guards + side effects, account validation)
• findByStudent coverage in tests/Unit/Policy/AcceptanceRepositoryTest.php, tests/Unit/Registration/AnswerRepositoryTest.php, and tests/Unit/Payment/PaymentRepositoryTest.php

Family Relationships

The students list gains a Profile column — a child links to their guardian, a guardian lists their children — and the student screen a Profile panel. A child's listed email is their guardian's, since a child's own address is an undeliverable placeholder, and the credit balance shown is the payer's, labelled with whose account holds it. See parent-guardian-accounts.md.