Backend: Zapisnik o vraćanju (return form)

GitHub Issue: #196

Backend task for saving and completing the return record (POST /drivepark/records/{recordId}/return) – check the API spec and DB structure, save return drafts without changing the status, complete the return with signatures, PDF and e-mail, implement, and verify against the spec.

Docs: Zapisnik o vraćanju (return form) Spec: POST /drivepark/records/{recordId}/return (saveDriveParkRecordReturn), DriveParkRecordReturnRequest, DriveParkRecordSigning, DriveParkRecordDetail, DriveParkRecordConflict in api-docs/openapi.yaml DB: DriveParkRecords (Return* columns) in api/database/pending_schema.sql (-- DRIVE PARK --)

1. Double check API spec and DB structure

• Every docs field of Stanje vozila pri vraćanju is in DriveParkRecordReturnRequest: returnMileageKm (mandatory, prefilled by the frontend from pickupMileageKm), returnDate, returnTime (mandatory), returnBatteryPercent (0–100), returnFuelLevel, returnDamage. Voženo is computed (drivenDays / drivenHours), not sent.
• Mandatory for completion: Km stanje, Datum and Vrijeme vraćanja, the terms checkbox and both signatures. Check the docs and the spec agree.
• Draft: saving keeps the status Preuzeto (docs). Check the spec says the same.
• Validation not decided in the docs: return km ≥ pickup km, and return date/time not before pickup date/time (docs: “Recommended”). Decide and add to the spec (→ 400).
• Opći uvjeti with the return e-mail: the spec sends only the return PDF (as the docs' conflict comment notes, the spec attaches the terms to the pickup copy only). Confirm.
• PDF and e-mail: layout and texts are not specified yet.
• Roles and permissions: drivepark.access.

2. Implementation

• Roles and permissions: require drivepark.access → 403.
• Record must be Preuzeto (PickupCompletedAt IS NOT NULL AND ReturnCompletedAt IS NULL) → else 409 record_not_picked_up. Put the check in the UPDATE’s WHERE and handle 0 rows.
• Replace the return fields only; pickup fields can’t change here.
• Completion (with signing): validate → 400 validation_error; upload the signatures; generate the return PDF; set ReturnCompletedAt, ReturnCompletedBy, the blob columns and ReturnEmailStatus; after the commit e-mail the PDF to Email and set sent / failed. Reuse the helpers from Backend: Zapisnik o preuzimanju.
• Response 200 with DriveParkRecordDetail.
• Vehicle usage overview: the drivepark-rental entry now ends on ReturnDate.

3. Verify implementation against spec

• Route, request and response shapes match saveDriveParkRecordReturn.
• 400 validation_error, 404, 409 record_not_picked_up can be produced; no undocumented ones.
• Return draft → status stays picked-up, values come back on the next load.
• Complete → status returned, return PDF downloadable, e-mail sent if an e-mail was entered.
• Return on a Draft or a Vraćeno record → 409.

Done when

A Manager of Vozni park can fill in, save and sign the return, and the record becomes Vraćeno.