Add unit tests for InvoicingPeriodDraftOverlay and reference suggestion logic, including fake DB integration and aggregation methods

- Implemented `InvoicingPeriodDraftOverlayTest` with coverage for blocking and permitting invoicing actions based on draft states, transactions, and metadata.
- Created `ReferenceSuggestionsApiTest` to validate ranked and filtered suggestions across bookings, orders, and vehicles with varied match relevance, context, and frequency.
- Added `order_reference_suggestions_service` class, including query methods, normalization utilities, and aggregation logic for reference suggestions.
- Enhanced query handling in `InvoicingPeriodDraftOverlayFakeDb` to validate SQL constraints and column cache resets in overlapping invoicing contexts.

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

@@ -60,11 +60,44 @@ it('enforces retry constraints for collected-invoice queue jobs before retry exe
     expect($content)->toContain("Collected invoice queue job can only be retried when status is FAILED', 409");
     expect($content)->toContain('private function withCollectedInvoiceQueueDetailsSummary(array $job): array');
     expect($content)->toContain('private function withCollectedInvoiceQueueDetailsSummaryList(array $jobs): array');
+    expect($content)->toContain('private function resolveCollectedInvoiceQueueCustomerSummary(array $customer, int $collected_invoice_id): array');
+    expect($content)->toContain('FROM collected_order_invoices coi');
+    expect($content)->toContain('LEFT JOIN users u ON u.customer_number = coi.customer_number');
     expect($content)->toContain('private function resolveCollectedInvoiceQueueRetryErrorStatus(string $message): int');
     expect($content)->toContain('only failed jobs can be retried');
     expect($content)->toContain('max retry attempts');
 });
 
+it('exposes collected-invoice queue monitor and per-user terminal clear routes', function (): void {
+    $content = file_get_contents(app_path('routes/orderInvoicesRoute.php'));
+
+    expect($content)->not->toBeFalse();
+    $content = (string)$content;
+
+    $monitorStart = strpos($content, "\$this->get('/collected-invoices/economic/queue/monitor'");
+    $dismissStart = strpos($content, "\$this->post('/collected-invoices/economic/queue/dismiss'");
+    $dismissTerminalStart = strpos($content, "\$this->post('/collected-invoices/economic/queue/dismiss-terminal'");
+
+    expect($monitorStart)->not->toBeFalse();
+    expect($dismissStart)->not->toBeFalse();
+    expect($dismissTerminalStart)->not->toBeFalse();
+
+    expect($content)->toContain('$limit = $this->parseCollectedInvoiceQueueMonitorLimit();');
+    expect($content)->toContain('$this->buildCollectedInvoiceQueueMonitorPayload(');
+    expect($content)->toContain('private function parseCollectedInvoiceQueueMonitorLimit(): int');
+    expect($content)->toContain('limit must be between 1 and 100');
+    expect($content)->toContain('private function buildCollectedInvoiceQueueMonitorPayload(economic_transfer_queue $queue, int $user_id, int $limit): array');
+    expect($content)->toContain('$queue->listMonitorJobsForUser(');
+    expect($content)->toContain("'queued' => 0");
+    expect($content)->toContain("'in_progress' => 0");
+    expect($content)->toContain("'progress_percent' => \$counts['total'] > 0");
+
+    expect($content)->toContain('$queue->dismissTerminalJobForUser($job_id, (int)$user->id);');
+    expect($content)->toContain('Only completed or failed collected invoice queue jobs can be cleared');
+    expect($content)->toContain('$queue->dismissTerminalJobsForUser(');
+    expect($content)->toContain("'dismissed_count' => \$dismissed_count");
+});
+
 it('runs collected-invoice queue batches through an explicit manual endpoint', function (): void {
     $content = file_get_contents(app_path('routes/orderInvoicesRoute.php'));