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, and **Booked by**: the
    name of the parent/guardian who books and pays for this student, linked to
    their own detail page. Always rendered — a student who books for themselves
    says so in words, so an empty row can never be mistaken for a lookup that
    failed.
  - **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.

**A guardian takes their children with them.** A child account is login-less and
exists only so the guardian has somebody to book for; without the guardian nobody
can reach it, book for it, or be billed for it, so leaving it behind leaves an
unreachable student on the roster holding slots that will never be used. Each
child's bookings are released on the same terms, the `us_guardians` link row is
deleted, and the account goes. Deleting a child fires `delete_user` again and
re-enters the same handler; a `handled` set of user ids makes that a no-op and
also stops a self-referential or circular link recursing.

(This is a different rule from the family screen's **Remove**, which still refuses
a child with any lesson or enrolment history — that is a guardian tidying up, not
an admin deleting an account, and `GuardianService::removeChild()` is unchanged.)

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