Complete selected-customer invoice period tree (#338)

Add the authoritative revision-bound invoice collection tree and guarded cleanup, merge, price-reset, and transfer operations.

services/nginx/app/tests/Unit/Invoicing/InvoicingPeriodRouteGuardsTest.php

@@ -68,6 +68,26 @@ it('only includes invoice period flags when the list permission is granted', fun
         ->and($flagService)->toContain("unset(\$types[\$typeName][\$index]['flags']);");
 });
 
+it('advertises a server-gated selected-customer tree and fails the dedicated route closed', function (): void {
+    $route = (string)file_get_contents(app_path('routes/InvoicingPeriodRoute.php'));
+
+    expect($route)
+        ->toContain('INVOICING_PERIOD_OBJECT_TREE_V2')
+        ->toContain("module = 'InvoicingPeriod'")
+        ->toContain("'object_tree_v2_enabled'")
+        ->toContain("'object_tree_v2_superuser_allowlist'")
+        ->not->toContain("includeTreeSnapshot")
+        ->toContain("\$this->get('/superuser/invoicing/period/tree'")
+        ->toContain("Invoice-period object tree is not enabled.")
+        ->toContain('$response->error(\'Invoice-period object tree is not enabled.\', 403);')
+        ->toContain('buildInvoicePeriodTreeSnapshot(')
+        ->toContain("'complete_order_count'")
+        ->toContain("'period_total_net_amount'")
+        ->toContain("'date_from' => substr(\$dateFrom, 0, 10)")
+        ->toContain("'date_to' => substr(\$dateTo, 0, 10)")
+        ->toContain("\$period['capabilities']['object_tree_v2'] = \$enabled;");
+});
+
 it('maps batched period transaction rows to the legacy transaction response shape', function (): void {
     $reflection = new ReflectionClass(InvoicingPeriodRoute::class);
     $method = $reflection->getMethod('constructTransactionObjectFromPeriodRow');