# Feature: Payment Reporting

## Overview
A monthly view of payments per instructor, with a downloadable spreadsheet (CSV) export. The studio admin sees every instructor and can filter; each instructor sees only their own payments. The report is built entirely from `us_payments` — no additional table.

## Data Source
Reads `{prefix}us_payments` (see `payments.md`), grouped by calendar month and
instructor. Each report row joins through to the student and offering for display:

| Report Column | Source                                            |
|---------------|---------------------------------------------------|
| Date          | `us_payments.paid_at` (falls back to `created_at`) |
| Student       | `us_payments.student_id` → display name           |
| Offering      | registration → `us_offerings.title`               |
| Method        | `us_payments.method`                              |
| Status        | `us_payments.status`                              |
| Amount        | `us_payments.amount_cents` / `currency`           |

Totals are summed over `paid` rows for the selected month.

## Access Rules
- Studio admin (`view_all_payments`): all instructors; may filter by `instructor_id`.
- Instructor (`view_own_payments`): rows where `us_payments.instructor_id` is their own user ID only.
- Export requires `export_payments` and is scoped to the same rows the caller may view.

## Admin Interface
**Payments** in wp-admin:
- Month picker (defaults to the current month) and, for studio admin, an instructor filter
- A table of payments with a monthly total
- An **Export** button that downloads the filtered rows as CSV

## REST API
| Method | Endpoint                                       | Permission           |
|--------|------------------------------------------------|----------------------|
| `GET`  | `/wp-json/us-scheduler/v1/payments`            | `view_own_payments` or `view_all_payments` |
| `GET`  | `/wp-json/us-scheduler/v1/payments/export`     | `export_payments`    |

Query params: `month` (`YYYY-MM`, required), `instructor_id` (optional; ignored for
instructors, who are always scoped to themselves). `GET /payments/export` returns
`text/csv` with a `Content-Disposition` attachment header.

## Implementation
- Report controller: `Unsupervised\Schedular\Payment\PaymentReportController`
- CSV exporter: `Unsupervised\Schedular\Payment\PaymentExporter`
- Report query: `Unsupervised\Schedular\Payment\PaymentRepository::report()`

## Tests
- `tests/Unit/Payment/PaymentReportControllerTest.php`
- `tests/Unit/Payment/PaymentExporterTest.php`