refactor(maintenance): simplify state restoration and workflow orchestration

[DevSkyLex]

Context

The integrated maintenance release fails the fireguard-api-develop Sonar gate on 173 open issues. New-code coverage (93.3%) and duplication (1.19%) already meet the gate. Complex workflows, discarded UUID allocations and broad restoration/persistence methods obscure the invariants that the maintenance release needs to preserve.

Change Summary

• Make UUID validation explicit through the same shared validator used by the value-object constructor.
• Group equipment/customer, preventive, procurement and repair-request state into typed domain values; retain every persisted field and historical value during restoration.
• Separate pure row restoration and canonical integrity checks from SQL, transactions and locks. Inventory uses its explicitly wired main DBAL connection throughout.
• Extract cohesive workflow, valuation, reporting and export steps; retain replay hashes, exact monetary arithmetic, append-only corrections, occurrence reservations and publication snapshots.
• Reduce nested branches/ternaries and centralize identical resource, SQL and error literals.

Review Guide

Review creation versus raw historical restoration, omitted/null patches, exact hash/JSON bytes, main/auth ownership, transaction/lock ordering, domain boundaries and runtime service wiring. Independent cross-module reviews and targeted PostgreSQL tests have passed.

Risk And Rollback

This refactor changes internal factory and port signatures across the maintenance modules. HTTP contracts and database records are intended to remain identical. Rollback uses the previous compatible application image and retains additive schema migrations and pending operation identities.

Validation

• Targeted module tests, scoped PHPStan and formatting passed before source freeze.
• Independent reviews covered Inventory, Procurement/Maintenance, MaintenanceCost/Shared, Equipment/Customer, Intervention/Exports and ServiceRequest/Facility/Inspection.
• Full API suite: 15,757 tests and 126,574 assertions passed on eight isolated PostgreSQL clones, after correcting helper placement while retaining all architecture tests.
• Global gates passed: uncached style (7,143 files), PHPStan (7,135 files), both Deptrac configurations, Symfony container, 74 YAML files and both auth/main mappings/schemas.
• Fresh runtime OpenAPI is identical; static API/frontend review and 54 contract tests plus canonical drift check passed. A pre-existing nullable publishedAt frontend type is corrected in the companion delivery.
• Fresh PR CI and integrated develop Sonar must validate their exact committed revisions before dev deployment.

Deployment Notes

API and web only; FireGuard is retained. Development SSH host verification is configured from the operator's existing trusted host key. Deploy the API before the companion web PR DevSkyLex/fireguard-web#310. The temporary GitHub Sonar diagnostic was cancelled before publication after direct Sonar access recovered.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-08T20:04:15.730523Z	9d5e63a	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.