api/services/nginx/app/tests/Unit/XLVask/XLVaskUsageRouteContractTest.php

<?php

it('exposes direct linked order metadata on XL Vask usage order rows', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');

    expect($route)->not->toBeFalse();

    $route = (string)$route;

    expect($route)
        ->toContain('$linked_order_ids_by_wash_id = []')
        ->and($route)->toContain('array_key_exists($wash_id, $linked_order_ids_by_wash_id)')
        ->and($route)->toContain('selectByWashId($wash_id)')
        ->and($route)->toContain("'linked_order_id' => \$linked_order_id")
        ->and($route)->toContain("'usage_log_id' => \$id");
});

it('does not execute XL Vask usage automation while listing usage order rows', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');

    expect($route)->not->toBeFalse();

    $route = (string)$route;

    expect($route)
        ->toContain('$automation = $automation_service->readAutomationStateByUsageLogId($id, $log);')
        ->and($route)->not->toContain('$automation = $automation_service->evaluateUsageLogRow($log, (int)$user->id, true);')
        ->and($route)->toContain("requirePermission('manage_xlvask_usage_automation')");
    expect($route)
        ->toContain("if (\$allowedHallIds === [])")
        ->toContain("No XL Vask hall scope is available', 403")
        ->not->toContain('__no_authorized_xlvask_hall__');
});

it('returns cached amount summaries on XL Vask usage order rows without widening the usage-log object payload', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');

    expect($route)->not->toBeFalse();

    $route = (string)$route;

    expect($route)
        ->toContain('$amount_summary = $xlvask_usage_logs->getAmountSummaryReadOnly($log)')
        ->and($route)->toContain('$usage_log_payload = array_intersect_key($log, array_flip([')
        ->and($route)->toContain('$tmp->setProperties($usage_log_payload)')
        ->and($route)->toContain("\$tmp_res['order']['total_net_amount'] = \$amount_summary['total_net_amount']")
        ->and($route)->toContain("\$tmp_res['order']['xlvask_primary_product_name'] = \$amount_summary['primary_product_name']")
        ->and($route)->toContain("\$tmp_res['order']['xlvask_amount_cached'] = \$amount_summary['cached']");
});

it('keeps automation metadata out of the strict legacy XL Vask helper payload', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');

    expect($route)->not->toBeFalse();

    $payloadStart = strpos((string)$route, '$usage_log_payload = array_intersect_key(');
    $payloadEnd = strpos((string)$route, '// Create a new xlvask usage log object', $payloadStart ?: 0);

    expect($payloadStart)->not->toBeFalse()
        ->and($payloadEnd)->not->toBeFalse();

    $payloadDefinition = substr((string)$route, (int)$payloadStart, (int)$payloadEnd - (int)$payloadStart);

    expect($payloadDefinition)
        ->not->toContain("'source_hash'")
        ->not->toContain("'source_revision'")
        ->not->toContain("'import_state'")
        ->not->toContain("'resolution_state'")
        ->not->toContain("'certainty'")
        ->not->toContain("'planned_action'")
        ->not->toContain("'expected_version'")
        ->not->toContain("'last_run_id'");
});

it('keeps the legacy state-changing XL Vask usage import GET non-mutating', function (): void {
    $route = file_get_contents(WD . '/routes/moduleXLVaskRoute.php');
    $automation = file_get_contents(WD . '/classes/xlvask_automation_service.php');

    expect($route)
        ->not->toBeFalse()
        ->and($automation)->not->toBeFalse();

    $route = (string)$route;
    $automation = (string)$automation;

    expect($route)
        ->toContain('Deprecated state-changing GET.')
        ->toContain('Use POST /modules/xlvask/services/usage/autopilot-runs.')
        ->not->toContain("'forceRefetch' => true")
        ->not->toContain('runPending($dateFrom, $dateTo, [], 100, null)')
        ->and($automation)->toContain("STR_TO_DATE(REPLACE(SUBSTRING(StartTime, 1, 19), 'T', ' '), '%Y-%m-%d %H:%i:%s')");
});

it('exposes additive XL Vask autopilot run and summary routes', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');

    expect($route)->not->toBeFalse();

    $route = (string)$route;

    expect($route)
        ->toContain("get('/modules/xlvask/services/usage/orders/summary'")
        ->toContain("post('/modules/xlvask/services/usage/autopilot-runs'")
        ->toContain("get('/modules/xlvask/services/usage/autopilot-runs/{id}'")
        ->toContain('(new xlvask_autopilot_service())->getSummary(')
        ->toContain('(new xlvask_autopilot_service())->createRun(')
        ->toContain('(new xlvask_autopilot_service())->getRun(')
        ->toContain('$this->allowedHallIdsForUser($user)')
        ->toContain('], 202);');
});

it('routes legacy automation entry points through the durable queue and preview lifecycle', function (): void {
    $route = (string)file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');
    expect($route)
        ->toContain('Deprecated. Use /modules/xlvask/services/usage/autopilot-runs.')
        ->toContain('Use the server-generated automation decision preview and apply endpoints.')
        ->not->toContain("post('/modules/xlvask/services/usage/orders/automation/run', function () {\n            global \$response;\n            \$this->requirePermission('manage_xlvask_usage_automation');\n\n            \$user")
        ->not->toContain('(new xlvask_automation_service())->runPending(')
        ->not->toContain('(new xlvask_automation_service())->evaluateUsageLogById(');
});

it('exposes permission-aware capabilities active run and preview-bound server policy routes', function (): void {
    $route = (string)file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');
    expect($route)
        ->toContain("get('/modules/xlvask/services/usage/automation/capabilities'")
        ->toContain("get('/modules/xlvask/services/usage/autopilot-runs/active'")
        ->toContain("post('/modules/xlvask/services/usage/automation/admin/policy/previews'")
        ->toContain("post('/modules/xlvask/services/usage/automation/admin/policy/apply'")
        ->toContain("post('/modules/xlvask/services/usage/automation/admin/halt'")
        ->toContain("'can_manage_policy' => \$canManagePolicy")
        ->toContain("'can_halt' => \$canManagePolicy")
        ->toContain("'preview' => (new xlvask_automation_policy_service())->createPolicyPreview(")
        ->toContain("self::requireParameters(['target_stage', 'reason'])")
        ->toContain("(string)\$this->getParameter('reason')")
        ->toContain("['run' => (new xlvask_automation_policy_service())->activeRunReadOnly(");
});

it('allows all-only permission and uses every configured scanner hall for all scope', function (): void {
    $route = (string)file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');
    expect($route)
        ->toContain("if (!\$this->hasPermission(\$permission_list_all))")
        ->toContain("if (\$this->hasPermission('list_xlvask_usage_orders_all'))")
        ->toContain("if (!\$this->hasPermission('list_xlvask_usage_orders_all'))")
        ->toContain('private function allowedHallIdsForUser(object $user): array')
        ->not->toContain('private static function allowedHallIdsForUser')
        ->toContain("'list_xlvask_usage_orders_all' => 'Read all XL Vask usage-log automation summaries'")
        ->toContain('SELECT DISTINCT HallId FROM plate_scanners');
});

it('makes direct ignore and deprecated automation routes non-mutating', function (): void {
    $route = (string)file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');
    expect($route)
        ->toContain("patch('/modules/xlvask/services/usage/orders/{id}/ignore'")
        ->toContain("response->error('Use the server-generated automation decision preview and apply endpoints.', 409)")
        ->toContain("response->error('Deprecated. Use /modules/xlvask/services/usage/autopilot-runs.', 410)")
        ->not->toContain("SET ignored_at = NOW(),");
});

it('returns revision and resolution state on XL Vask usage order rows', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');

    expect($route)->not->toBeFalse();

    $route = (string)$route;

    expect($route)
        ->toContain("'source_hash' => \$log['source_hash'] ?? null")
        ->toContain("'source_revision' => \$log['source_revision'] ?? null")
        ->toContain("'import_state' => \$log['import_state'] ?? 'unchanged'")
        ->toContain("'resolution_state' => \$log['resolution_state'] ?? 'needs_review'")
        ->toContain("'certainty' => \$log['certainty'] ?? 'none'")
        ->toContain("'planned_action' => \$log['planned_action'] ?? 'none'")
        ->toContain("'expected_version' => isset(\$log['expected_version']) ? (int)\$log['expected_version'] : 1")
        ->toContain("'automation' => \$automation");
});

it('documents XL Vask autopilot summary and run APIs in OpenAPI', function (): void {
    $openApi = file_get_contents(WD . '/openapi.yaml');

    expect($openApi)->not->toBeFalse();

    $openApi = (string)$openApi;

    expect($openApi)
        ->toContain('/modules/xlvask/services/usage/orders/summary:')
        ->toContain('operationId: summarizeXlvaskUsageAutomation')
        ->toContain('/modules/xlvask/services/usage/autopilot-runs:')
        ->toContain('operationId: createXlvaskUsageAutopilotRun')
        ->toContain('/modules/xlvask/services/usage/autopilot-runs/{id}:')
        ->toContain('operationId: getXlvaskUsageAutopilotRun')
        ->toContain('/modules/xlvask/services/usage/automation/decisions/preview:')
        ->toContain('operationId: previewXlvaskUsageAutomationDecision')
        ->toContain('/modules/xlvask/services/usage/automation/decisions/apply:')
        ->toContain('operationId: applyXlvaskUsageAutomationDecision')
        ->toContain('/modules/xlvask/services/usage/automation/admin/readiness:')
        ->toContain('operationId: adjudicateXlvaskCalibrationLabel')
        ->toContain('operationId: generateXlvaskCalibrationArtifact')
        ->toContain('operationId: activateXlvaskCalibrationArtifact')
        ->toContain('operationId: activateXlvaskWashIdUniqueness');
    expect($openApi)
        ->toContain('operationId: getXlvaskAutomationCapabilities')
        ->toContain('effective_action_sources:')
        ->toContain('items: { type: string, enum: [openai] }')
        ->toContain('operationId: getActiveXlvaskUsageAutopilotRun')
        ->toContain('operationId: previewXlvaskAutomationPolicyTransition')
        ->toContain('operationId: applyXlvaskAutomationPolicyTransition')
        ->toContain('operationId: haltXlvaskAutomation')
        ->toContain('required: [target_stage, reason]');
});

it('wires preview-bound bulk decisions through the transactional autopilot service', function (): void {
    $route = file_get_contents(WD . '/routes/xlvaskUsageLogsRoute.php');
    $autopilot = file_get_contents(WD . '/classes/xlvask_autopilot_service.php');

    expect($route)
        ->not->toBeFalse()
        ->and($autopilot)->not->toBeFalse();

    $route = (string)$route;
    $autopilot = (string)$autopilot;

    expect($route)
        ->toContain("post('/modules/xlvask/services/usage/automation/decisions/preview'")
        ->toContain("post('/modules/xlvask/services/usage/automation/decisions/apply'")
        ->toContain('createDecisionPreview(')
        ->toContain('applyDecision(')
        ->and($autopilot)->toContain("SELECT * FROM xlvask_automation_decision_previews WHERE id = '")
        ->toContain('FOR UPDATE')
        ->toContain('applyBoundDecisionWithinTransaction(')
        ->toContain('expected_version')
        ->toContain('source_hash');
});

it('does not let pending automation schema block ordinary invoice period operations', function (): void {
    $bootstrap = (string)file_get_contents(WD . '/classes/invoice_period_flag_schema_bootstrap.php');

    expect($bootstrap)
        ->not->toContain('xlvask_usage_logs_schema_bootstrap::ensureTables()')
        ->toContain('XL Vask automation migration is pending');
});