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>
74 lines
3.4 KiB
Markdown
74 lines
3.4 KiB
Markdown
# Feature: Payment Reporting
|
|
|
|
## Overview
|
|
|
|
A monthly view of paid payments with **HST aggregation** and 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`), filtered to `paid` rows whose
|
|
`paid_at` falls within the selected calendar month, optionally narrowed to one
|
|
instructor. Each report row resolves the student and instructor for display:
|
|
|
|
| Report Column | Source |
|
|
|---------------|---------------------------------------------------|
|
|
| Date | `us_payments.paid_at` (date portion) |
|
|
| Student | `us_payments.student_id` → display name |
|
|
| Instructor | `us_payments.instructor_id` → display name |
|
|
| Method | `us_payments.method` |
|
|
| Status | `us_payments.status` |
|
|
| Subtotal | `us_payments.amount` / `currency` |
|
|
| HST | `us_payments.tax_amount` (with `tax_rate` %) |
|
|
| Total | `amount + tax_amount` (`Payment::total()`) |
|
|
|
|
Three totals are summed over the selected rows: **subtotal**, **HST collected**
|
|
(the figure the studio remits), and **grand total**.
|
|
|
|
## Access Rules
|
|
|
|
- Studio admin (`view_all_payments`): all instructors; may filter by `instructor_id`.
|
|
- Instructor (`view_own_payments`): always scoped to their own user ID; the
|
|
instructor filter is hidden and any requested `instructor_id` is overridden.
|
|
- Export requires `export_payments` and is scoped to the same rows the caller may view.
|
|
|
|
## Admin Interface
|
|
|
|
**Payment Report** in wp-admin (top-level menu, gated on `export_payments` so
|
|
instructors — who lack `manage_billing` — can reach it):
|
|
|
|
- Month picker (defaults to the current month) and, for studio admin, an
|
|
instructor filter
|
|
- A summary line of HST collected / subtotal / total collected
|
|
- A table of paid payments with a totals footer
|
|
- An **Export CSV** button that downloads the filtered rows (plus a totals row)
|
|
|
|
## Export
|
|
|
|
CSV export is served by an `admin-post.php` handler
|
|
(`admin_post_usc_export_payments`) rather than a REST route, so the browser
|
|
downloads it directly with a nonce-protected link. It honours the same `month`
|
|
and `instructor_id` query params as the page and returns `text/csv` with a
|
|
`Content-Disposition: attachment` header. Instructor requests are scoped to
|
|
their own rows regardless of `instructor_id`.
|
|
|
|
Fields that a spreadsheet would interpret as a formula (leading `=`, `+`, `-`,
|
|
`@`, tab, or CR — e.g. a hostile student display name) are prefixed with an
|
|
apostrophe so the export can never carry CSV formula injection into Excel or
|
|
Google Sheets.
|
|
|
|
## Implementation
|
|
|
|
- Report aggregator (pure totals + CSV): `Unsupervised\Schedular\Payment\PaymentReport`
|
|
- Report controller (page + export): `Unsupervised\Schedular\Payment\PaymentReportController`
|
|
- Report query: `Unsupervised\Schedular\Payment\PaymentRepository::findPaidBetween()`
|
|
- Template: `templates/admin/payment-report.php`
|
|
- Menu + `admin_post` wiring: `Unsupervised\Schedular\AdminMenu`
|
|
|
|
## Tests
|
|
|
|
- `tests/Unit/Payment/PaymentReportTest.php` — totals and CSV rendering
|
|
- `tests/Unit/Payment/PaymentRepositoryTest.php` — `findPaidBetween` query
|