Add HST/tax support and payment reporting with HST aggregation

Studio Settings gains a default HST rate; the rate is frozen onto each
payment at booking and computed against the pre-tax subtotal, with the
total billed as subtotal + tax. The rate is overridable per booking on
My Lessons while unpaid (recomputing the tax amount), comped
registrations are never taxed, and receipts break out subtotal/HST/total.

Builds the payments report (roadmap #8) from us_payments: a monthly
per-instructor view with subtotal, HST collected, and grand-total
aggregation, plus a nonce-protected CSV export via admin-post. Studio
admins see all instructors and can filter; instructors are scoped to
their own rows. The Payment Report menu is gated on export_payments so
instructors (who lack manage_billing) can reach it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/Unit/Payment/PaymentReportTest.php

@@ -0,0 +1,83 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Unsupervised\Schedular\Payment\PaymentReport;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PaymentReportTest extends TestCase
+{
+    /**
+     * @return list<array{date: string, student: string, instructor: string, method: string, status: string, amount: float, tax_rate: float, tax_amount: float, total: float}>
+     */
+    private function rows(): array
+    {
+        return [
+            [
+                'date'       => '2026-06-02',
+                'student'    => 'Ada',
+                'instructor' => 'Pat',
+                'method'     => 'etransfer',
+                'status'     => 'paid',
+                'amount'     => 100.00,
+                'tax_rate'   => 13.0,
+                'tax_amount' => 13.00,
+                'total'      => 113.00,
+            ],
+            [
+                'date'       => '2026-06-09',
+                'student'    => 'Grace',
+                'instructor' => 'Pat',
+                'method'     => 'card',
+                'status'     => 'paid',
+                'amount'     => 50.00,
+                'tax_rate'   => 13.0,
+                'tax_amount' => 6.50,
+                'total'      => 56.50,
+            ],
+        ];
+    }
+
+    public function testTotalsAggregateAmountsAndTax(): void
+    {
+        $report = new PaymentReport($this->rows());
+
+        self::assertSame(2, $report->count());
+        self::assertSame(150.00, $report->totalAmount());
+        self::assertSame(19.50, $report->totalTax());
+        self::assertSame(169.50, $report->grandTotal());
+    }
+
+    public function testEmptyReportHasZeroTotals(): void
+    {
+        $report = new PaymentReport([]);
+
+        self::assertSame(0, $report->count());
+        self::assertSame(0.0, $report->totalTax());
+        self::assertSame(0.0, $report->grandTotal());
+    }
+
+    public function testCsvIncludesHeaderRowsAndTotals(): void
+    {
+        $csv   = (new PaymentReport($this->rows()))->toCsv();
+        $lines = explode("\n", trim($csv));
+
+        // header + 2 data rows + totals row.
+        self::assertCount(4, $lines);
+        self::assertStringContainsString('"Date","Student","Instructor"', $lines[0]);
+        self::assertStringContainsString('"Ada"', $lines[1]);
+        self::assertStringContainsString('"Totals"', $lines[3]);
+        self::assertStringContainsString('"19.50"', $lines[3]);
+        self::assertStringContainsString('"169.50"', $lines[3]);
+    }
+
+    public function testCsvEscapesEmbeddedQuotes(): void
+    {
+        $rows    = $this->rows();
+        $rows[0]['student'] = 'Ada "The Great"';
+        $csv     = (new PaymentReport($rows))->toCsv();
+
+        self::assertStringContainsString('"Ada ""The Great"""', $csv);
+    }
+}

tests/Unit/Payment/PaymentRepositoryTest.php

@@ -62,6 +62,42 @@ class PaymentRepositoryTest extends TestCase
         self::assertTrue($this->repo->markPaid(50, 'USC-50'));
     }
 
+    public function testUpdateTaxRecomputesAmountFromRate(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/tax_amount = ROUND\( amount \* %f \/ 100, 2 \)/'), 13.0, 13.0, 50)
+            ->andReturn('UPDATE ...');
+
+        $this->db->shouldReceive('query')->once()->with('UPDATE ...')->andReturn(1);
+
+        self::assertTrue($this->repo->updateTax(50, 13.0));
+    }
+
+    public function testFindPaidBetweenFiltersByInstructor(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/status = %s AND paid_at >= %s AND paid_at < %s AND instructor_id = %d/'), ['paid', '2026-06-01 00:00:00', '2026-07-01 00:00:00', 3])
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([$this->row()]);
+
+        self::assertCount(1, $this->repo->findPaidBetween('2026-06-01 00:00:00', '2026-07-01 00:00:00', 3));
+    }
+
+    public function testFindPaidBetweenWithoutInstructorOmitsFilter(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::on(static fn (string $sql): bool => ! str_contains($sql, 'instructor_id')), ['paid', '2026-06-01 00:00:00', '2026-07-01 00:00:00'])
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([]);
+
+        self::assertCount(0, $this->repo->findPaidBetween('2026-06-01 00:00:00', '2026-07-01 00:00:00'));
+    }
+
     public function testFindByRegistrationReturnsPayment(): void
     {
         $this->db->shouldReceive('prepare')
@@ -98,6 +134,8 @@ class PaymentRepositoryTest extends TestCase
             'currency'                 => 'CAD',
             'method'                   => Payment::METHOD_ETRANSFER,
             'status'                   => Payment::STATUS_PENDING,
+            'tax_rate'                 => '0.00',
+            'tax_amount'               => '0.00',
             'etransfer_email'          => null,
             'stripe_payment_intent_id' => null,
             'receipt_number'           => null,

tests/Unit/Payment/PaymentServiceTest.php

@@ -37,6 +37,7 @@ class PaymentServiceTest extends TestCase
         $this->enrollments = Mockery::mock(EnrollmentRepository::class);
         $this->settings    = Mockery::mock(StudioSettings::class);
         $this->settings->shouldReceive('etransferEmail')->andReturn('');
+        $this->settings->shouldReceive('hstRate')->andReturn(0.0)->byDefault();
 
         $this->service = new PaymentService(
             $this->payments,
@@ -91,6 +92,37 @@ class PaymentServiceTest extends TestCase
         );
     }
 
+    public function testHstIsComputedAndFrozenOntoPayment(): void
+    {
+        $this->settings->shouldReceive('hstRate')->andReturn(13.0);
+        $this->resolver->shouldReceive('resolve')->with(5)->andReturn(Payment::METHOD_ETRANSFER);
+        $this->payments->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Payment $p): bool => $p->taxRate === 13.0 && $p->taxAmount === 13.00 && $p->total() === 113.00))
+            ->andReturn(50);
+        $this->bookings->shouldReceive('setPaymentId')->once()->with(12, 50);
+        $this->payments->shouldReceive('findById')->with(50)->andReturn($this->payment(Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, 50));
+
+        self::assertNotNull($this->service->createForRegistration(Payment::REG_LESSON, 12, 5, 3, 100.00, 'CAD'));
+    }
+
+    public function testCompIsNotTaxed(): void
+    {
+        $this->settings->shouldReceive('hstRate')->andReturn(13.0);
+        $this->resolver->shouldReceive('resolve')->with(5)->andReturn(Payment::METHOD_COMP);
+        $this->payments->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Payment $p): bool => $p->taxRate === 0.0 && $p->taxAmount === 0.0))
+            ->andReturn(61);
+        $this->bookings->shouldReceive('setPaymentId')->once()->with(12, 61);
+        $this->payments->shouldReceive('markPaid')->once()->with(61, 'USC-61')->andReturn(true);
+        $this->bookings->shouldReceive('updateStatus')->once()->with(12, Lesson::STATUS_CONFIRMED)->andReturn(true);
+        $this->payments->shouldReceive('findById')->with(61)->andReturn($this->payment(Payment::METHOD_COMP, Payment::STATUS_PAID, 61));
+        $this->mailer->shouldReceive('send')->andReturn(false);
+
+        self::assertNotNull($this->service->createForRegistration(Payment::REG_LESSON, 12, 5, 3, 100.00, 'CAD'));
+    }
+
     public function testCompIsPaidAndConfirmsImmediately(): void
     {
         $this->resolver->shouldReceive('resolve')->with(5)->andReturn(Payment::METHOD_COMP);

tests/Unit/Payment/PaymentTest.php

@@ -39,6 +39,8 @@ class PaymentTest extends TestCase
             'currency'                 => 'CAD',
             'method'                   => Payment::METHOD_COMP,
             'status'                   => Payment::STATUS_PAID,
+            'tax_rate'                 => '13.00',
+            'tax_amount'               => '15.60',
             'etransfer_email'          => null,
             'stripe_payment_intent_id' => null,
             'receipt_number'           => 'USC-7',
@@ -48,16 +50,32 @@ class PaymentTest extends TestCase
 
         self::assertSame(7, $payment->id);
         self::assertSame(120.00, $payment->amount);
+        self::assertSame(13.00, $payment->taxRate);
+        self::assertSame(15.60, $payment->taxAmount);
         self::assertSame(Payment::METHOD_COMP, $payment->method);
         self::assertTrue($payment->isPaid());
         self::assertSame('USC-7', $payment->receiptNumber);
     }
 
+    public function testTotalAddsTaxToAmount(): void
+    {
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 100.00, taxRate: 13.0, taxAmount: 13.00);
+
+        self::assertSame(113.00, $payment->total());
+    }
+
+    public function testTotalEqualsAmountWhenUntaxed(): void
+    {
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 100.00);
+
+        self::assertSame(100.00, $payment->total());
+    }
+
     public function testToArrayContainsExpectedKeys(): void
     {
         $arr = (new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, id: 7))->toArray();
 
-        foreach (['id', 'student_id', 'amount', 'currency', 'method', 'status', 'receipt_number'] as $key) {
+        foreach (['id', 'student_id', 'amount', 'tax_rate', 'tax_amount', 'total', 'currency', 'method', 'status', 'receipt_number'] as $key) {
             self::assertArrayHasKey($key, $arr);
         }
     }

tests/Unit/Payment/ReceiptMailerTest.php

@@ -32,4 +32,23 @@ class ReceiptMailerTest extends TestCase
 
         self::assertTrue((new ReceiptMailer())->send($payment, $student));
     }
+
+    public function testReceiptBreaksOutHstWhenTaxed(): void
+    {
+        Functions\expect('wp_mail')
+            ->once()
+            ->with(
+                'a@b.test',
+                Mockery::type('string'),
+                Mockery::on(static fn (string $body): bool => str_contains($body, 'HST') && str_contains($body, '113.00'))
+            )
+            ->andReturn(true);
+
+        $student             = Mockery::mock(\WP_User::class);
+        $student->user_email = 'a@b.test';
+
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 100.00, taxRate: 13.0, taxAmount: 13.00, receiptNumber: 'USC-1');
+
+        self::assertTrue((new ReceiptMailer())->send($payment, $student));
+    }
 }