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