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>
2026-06-08 11:29:48 -03:00
parent b73d81421f
commit 553cfafa49
21 changed files with 756 additions and 58 deletions
@@ -5,7 +5,7 @@ if (! defined('ABSPATH')) {
    exit;
 }

-/** @var list<array{student: string, instructor: string, slot_id: int, status: string, notes: string, payment_id: int, etransfer_email: string, etransfer_editable: bool}> $rows */
+/** @var list<array{student: string, instructor: string, slot_id: int, status: string, notes: string, payment_id: int, currency: string, amount: float, tax_rate: float, tax_amount: float, total: float, etransfer_email: string, etransfer_editable: bool, tax_editable: bool}> $rows */
 ?>
 <div class="wrap">
    <h1><?php esc_html_e('Lessons', 'unsupervised-schedular'); ?></h1>
@@ -20,6 +20,8 @@ if (! defined('ABSPATH')) {
                    <th><?php esc_html_e('Instructor', 'unsupervised-schedular'); ?></th>
                    <th><?php esc_html_e('Slot ID', 'unsupervised-schedular'); ?></th>
                    <th><?php esc_html_e('Status', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('HST', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Total', 'unsupervised-schedular'); ?></th>
                    <th><?php esc_html_e('E-transfer email', 'unsupervised-schedular'); ?></th>
                    <th><?php esc_html_e('Notes', 'unsupervised-schedular'); ?></th>
                </tr>
@@ -31,6 +33,21 @@ if (! defined('ABSPATH')) {
                        <td><?php echo esc_html($row['instructor']); ?></td>
                        <td><?php echo esc_html((string) $row['slot_id']); ?></td>
                        <td><?php echo esc_html($row['status']); ?></td>
+                        <td>
+                            <?php if ($row['tax_editable']) : ?>
+                                <form method="post" style="display:flex; gap:4px; align-items:center;">
+                                    <?php wp_nonce_field('usc_lesson_action'); ?>
+                                    <input type="hidden" name="usc_action" value="set_tax">
+                                    <input type="hidden" name="payment_id" value="<?php echo esc_attr((string) $row['payment_id']); ?>">
+                                    <input type="number" name="tax_rate" min="0" max="100" step="0.01" style="width:5em;" value="<?php echo esc_attr(number_format($row['tax_rate'], 2)); ?>">
+                                    <span>%</span>
+                                    <button type="submit" class="button button-small"><?php esc_html_e('Save', 'unsupervised-schedular'); ?></button>
+                                </form>
+                            <?php else : ?>
+                                <?php echo esc_html(number_format($row['tax_rate'], 2) . '% (' . $row['currency'] . ' ' . number_format($row['tax_amount'], 2) . ')'); ?>
+                            <?php endif; ?>
+                        </td>
+                        <td><?php echo $row['payment_id'] > 0 ? esc_html($row['currency'] . ' ' . number_format($row['total'], 2)) : esc_html('—'); ?></td>
                        <td>
                            <?php if ($row['etransfer_editable']) : ?>
                                <form method="post" style="display:flex; gap:4px;">
@@ -0,0 +1,99 @@
+<?php
+declare(strict_types=1);
+
+if (! defined('ABSPATH')) {
+    exit;
+}
+
+use Unsupervised\Schedular\Payment\PaymentReport;
+
+/**
+ * @var PaymentReport $report
+ * @var string $month
+ * @var int $instructorId
+ * @var bool $canExport
+ * @var bool $canFilter
+ * @var string $exportUrl
+ * @var list<\WP_User|\stdClass> $instructors
+ */
+?>
+<div class="wrap">
+    <h1><?php esc_html_e('Payment Report', 'unsupervised-schedular'); ?></h1>
+
+    <form method="get" style="margin: 1em 0; display:flex; gap:8px; align-items:flex-end; flex-wrap:wrap;">
+        <input type="hidden" name="page" value="us-reports">
+        <label>
+            <?php esc_html_e('Month', 'unsupervised-schedular'); ?><br>
+            <input type="month" name="month" value="<?php echo esc_attr($month); ?>">
+        </label>
+        <?php if ($canFilter) : ?>
+            <label>
+                <?php esc_html_e('Instructor', 'unsupervised-schedular'); ?><br>
+                <select name="instructor_id">
+                    <option value="0"><?php esc_html_e('All instructors', 'unsupervised-schedular'); ?></option>
+                    <?php foreach ($instructors as $instructor) : ?>
+                        <option value="<?php echo esc_attr((string) $instructor->ID); ?>" <?php selected($instructorId, (int) $instructor->ID); ?>>
+                            <?php echo esc_html($instructor->display_name); ?>
+                        </option>
+                    <?php endforeach; ?>
+                </select>
+            </label>
+        <?php endif; ?>
+        <button type="submit" class="button"><?php esc_html_e('Filter', 'unsupervised-schedular'); ?></button>
+        <?php if ($canExport) : ?>
+            <a class="button button-secondary" href="<?php echo esc_url($exportUrl); ?>"><?php esc_html_e('Export CSV', 'unsupervised-schedular'); ?></a>
+        <?php endif; ?>
+    </form>
+
+    <p>
+        <strong><?php esc_html_e('HST collected:', 'unsupervised-schedular'); ?></strong>
+        <?php echo esc_html(number_format($report->totalTax(), 2)); ?>
+        &nbsp;|&nbsp;
+        <strong><?php esc_html_e('Subtotal:', 'unsupervised-schedular'); ?></strong>
+        <?php echo esc_html(number_format($report->totalAmount(), 2)); ?>
+        &nbsp;|&nbsp;
+        <strong><?php esc_html_e('Total collected:', 'unsupervised-schedular'); ?></strong>
+        <?php echo esc_html(number_format($report->grandTotal(), 2)); ?>
+    </p>
+
+    <?php if (0 === $report->count()) : ?>
+        <p><?php esc_html_e('No paid payments in this period.', 'unsupervised-schedular'); ?></p>
+    <?php else : ?>
+        <table class="wp-list-table widefat fixed striped">
+            <thead>
+                <tr>
+                    <th><?php esc_html_e('Date', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Student', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Instructor', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Method', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Status', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Subtotal', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('HST', 'unsupervised-schedular'); ?></th>
+                    <th><?php esc_html_e('Total', 'unsupervised-schedular'); ?></th>
+                </tr>
+            </thead>
+            <tbody>
+                <?php foreach ($report->rows() as $row) : ?>
+                    <tr>
+                        <td><?php echo esc_html($row['date']); ?></td>
+                        <td><?php echo esc_html($row['student']); ?></td>
+                        <td><?php echo esc_html($row['instructor']); ?></td>
+                        <td><?php echo esc_html($row['method']); ?></td>
+                        <td><?php echo esc_html($row['status']); ?></td>
+                        <td><?php echo esc_html(number_format($row['amount'], 2)); ?></td>
+                        <td><?php echo esc_html(number_format($row['tax_amount'], 2) . ' (' . number_format($row['tax_rate'], 2) . '%)'); ?></td>
+                        <td><?php echo esc_html(number_format($row['total'], 2)); ?></td>
+                    </tr>
+                <?php endforeach; ?>
+            </tbody>
+            <tfoot>
+                <tr>
+                    <th colspan="5"><?php esc_html_e('Totals', 'unsupervised-schedular'); ?></th>
+                    <th><?php echo esc_html(number_format($report->totalAmount(), 2)); ?></th>
+                    <th><?php echo esc_html(number_format($report->totalTax(), 2)); ?></th>
+                    <th><?php echo esc_html(number_format($report->grandTotal(), 2)); ?></th>
+                </tr>
+            </tfoot>
+        </table>
+    <?php endif; ?>
+</div>
@@ -11,6 +11,7 @@ if (! defined('ABSPATH')) {
 * @var string $mode
 * @var string $currency
 * @var string $etransferEmail
+ * @var float  $hstRate
 * @var bool   $stripeConfigured
 */
 ?>
@@ -53,6 +54,13 @@ if (! defined('ABSPATH')) {
                <th><label for="currency"><?php esc_html_e('Default currency', 'unsupervised-schedular'); ?></label></th>
                <td><input type="text" name="currency" id="currency" class="small-text" maxlength="3" value="<?php echo esc_attr($currency); ?>"></td>
            </tr>
+            <tr>
+                <th><label for="hst_rate"><?php esc_html_e('Default HST rate (%)', 'unsupervised-schedular'); ?></label></th>
+                <td>
+                    <input type="number" name="hst_rate" id="hst_rate" class="small-text" min="0" max="100" step="0.01" value="<?php echo esc_attr(number_format($hstRate, 2)); ?>">
+                    <p class="description"><?php esc_html_e('Added to the subtotal when billing. 0 means no tax. Overridable per booking on My Lessons.', 'unsupervised-schedular'); ?></p>
+                </td>
+            </tr>
        </table>

        <h2><?php esc_html_e('E-transfer', 'unsupervised-schedular'); ?></h2>