Improve Fleet-Ops server test coverage

[roncodes]

Summary

Continues the Fleet-Ops backend coverage push toward a 100% server-side coverage gate for ./server.

This branch wires Composer coverage reporting, adds a 100% fail-under coverage command, and expands Pest coverage across backend contracts that can be exercised inside the package CI harness. Production changes remain limited to issues uncovered while making the backend tests executable in CI.

Latest Coverage

• Target line coverage: 100.00%
• Current verified PR line coverage: pending, not yet available from CI
• Current verified PR method coverage: pending, not yet available from CI
• Current verified PR class coverage: pending, not yet available from CI

The Fleet-Ops server workflow now installs Xdebug and is configured to upload coverage/clover.xml, but the current remote PR head is still failing before the coverage-generation step. The latest failing server run stops in server/tests/FuelProviderResourceContractsTest.php, so no trustworthy branch coverage percentage has been produced yet. I will update this section with the actual line, method, and class coverage percentages as soon as the backend build reaches the coverage baseline step.

Coverage Reporting

• Added composer coverage:baseline to generate Clover coverage and print a summary.
• Added composer coverage:check to generate Clover coverage and fail below 100% line coverage.
• Added scripts/coverage-summary.php support for --fail-under=100.
• Updated the server CI workflow to install Xdebug, run the coverage baseline, and upload coverage/clover.xml as an artifact.

Coverage Added

• Export contracts for Fleet-Ops server exports.
• Import contracts for Fleet-Ops server imports.
• Support value objects, tracking options/results/stops, polyline helpers, and provider descriptors.
• Tracking provider registry, provider manager fallback behavior, calculated tracking, and tracking context behavior.
• Flow resource serialization contracts.
• Exception contracts for telematics, rate limits, customer/user conflicts, and integrated vendor response payloads.
• Validation rule and cast contracts.
• Event payload and broadcast contract coverage.
• Metric registry and metric aggregation behavior.
• Analytics option and route contract coverage.
• Telematics provider registry and abstract provider behavior.
• Notification and mail contract coverage for operational alerts and maintenance/work-order messages.
• Service provider registration contracts for observers, commands, notifications, notifiables, and event listeners.
• Request validation contracts for devices, vehicles, work orders, fuel reports, and fuel transactions.
• Fuel provider resource contracts and fuel provider implementation contracts.
• Middleware coverage for recursive location normalization.
• Vehicle data parsing coverage.

Production Fixes

• Fixed TelematicRateLimitExceededException inheritance so it extends the existing telematics provider exception contract.
• Fixed Fleet-Ops event classes to import the available Illuminate\Foundation\Bus\Dispatchable trait instead of the missing Illuminate\Foundation\Events\Dispatchable namespace in this package CI matrix.

Current CI Status

• GitHub Actions is running on PR Improve Fleet-Ops server test coverage #277.
• CodeQL and workflow analysis checks are passing on recent runs.
• The server build is still being walked forward through isolated package test failures before coverage can be generated.
• Current known remote blocker: FuelProviderResourceContractsTest request-context/resource fixture mismatch before the coverage step.

Validation

• php -l on every added or touched backend PHP test/source file.
• git diff --check and git diff --cached --check for each committed slice.
• PR checks inspected with authenticated machine gh.
• Local full Pest coverage is still not available in this shell because local Composer dependencies and a coverage driver are not installed here; CI is the authoritative coverage path for this PR.

Notes

This remains a progressive draft PR. The next local batch is being held back until it represents a more meaningful coverage increase or a necessary CI-unblocking bundle, rather than pushing every small test slice individually.