IAV-577/feat(custom-instructions): Add document attachment support with transactional file management

Summary

This MR introduces document attachment capabilities for custom instructions. Instructions of type SUGGESTIONS can now have an associated file that gets stored via the FileManager service and referenced by UID in the instruction entity.

Implementation Details

The feature required splitting the original request DTO into separate create and update variants. The create request includes the category field and an optional file, while the update request uses an updateFile boolean flag to control document behavior: when false or null the existing document is preserved, when true with a file the document is replaced, and when true without a file the document is removed.

To ensure data consistency, the implementation uses a DocumentUpdateResult pattern that tracks the document operation state. New file uploads are rolled back if the subsequent database save fails, and old documents are only deleted after confirming the database transaction completed successfully. This prevents orphan files in storage and ensures the database and file storage remain synchronized.

The FileManagerService interface has been extended with methods for single-file operations since the existing bulk methods were not suitable for the one-document-per-instruction model. The service implementation was refactored to extract common validation and HTTP handling logic into reusable helper methods.

Breaking Changes

API consumers must update their integration to use multipart/form-data content type for create and update endpoints instead of application/json. The X-User-UID header is now required on all endpoints.

Document Update Behavior

When updating an instruction, the updateFile field controls document handling. Setting it to false or omitting it keeps the current document unchanged. Setting it to true with a new file attached replaces the existing document. Setting it to true without providing a file removes the document entirely.

Testing Notes

Verify document upload works only for SUGGESTIONS category and is ignored for RESTRICTIONS. Test the rollback behavior by simulating a database failure after file upload. Confirm old documents are cleaned up after successful replacement. Check that the list endpoint efficiently fetches all document metadata in a single batch call.

Related Issues

Closes IAV-577