As an admin I want annotations to stay linked to their file version so they disappear when a different file is uploaded but reappear if the original file is re-uploaded #55

New Issue

marcel · 2026-03-24T08:47:02+01:00

marcel commented

2026-03-24 08:47:02 +01:00

Problem

Annotations are currently stored against a document, not against a specific file. If an admin uploads a replacement file, all existing annotations remain visible even though they point at coordinates on a different page layout. Conversely, if the wrong file was uploaded by accident and corrected, the annotations are lost.

Solution: content-based file hash

Compute a SHA-256 hash of the file bytes on every upload (UI and mass import). Store it as file_hash on the document. Each annotation stores the file_hash that was current when the annotation was created.

The frontend renders annotations only when annotation.fileHash == document.fileHash. When they differ, show a non-blocking notice:

"X Annotationen beziehen sich auf eine frühere Dateiversion."

This is content-based, so uploading the exact same file twice (even with a different filename) correctly restores the annotations.

User Journey

Admin opens a document with annotations on page 1. They realise they scanned the wrong page and upload the correct scan. The annotation highlight disappears and a notice explains it belongs to the previous file. The admin re-uploads the original scan — the annotation reappears automatically without any manual action.

E2E Scenarios

Scenario: Annotations are hidden after a different file is uploaded
  Given a document has a PDF with an annotation
  When an admin uploads a different PDF to the same document
  Then the annotation is no longer visible
  And a notice "Annotationen beziehen sich auf eine frühere Dateiversion" is shown

Scenario: Annotations reappear after re-uploading the original file
  Given a document's annotation is hidden (different file uploaded)
  When an admin re-uploads the original PDF
  Then the annotation is visible again
  And the notice is no longer shown

Implementation notes

Backend: add file_hash VARCHAR(64) column to documents (Flyway migration); compute SHA-256 in FileService.upload() and store on the document
Backend: add file_hash VARCHAR(64) column to document_annotations; set from document.fileHash at annotation creation time
Mass import: MassImportService calls FileService already — hash computed there automatically
Frontend: expose fileHash on DocumentResponse; expose fileHash on AnnotationResponse; filter annotation rendering accordingly; show notice when at least one annotation has a different hash
No annotations are ever deleted by a file upload — all data is preserved

## Problem Annotations are currently stored against a document, not against a specific file. If an admin uploads a replacement file, all existing annotations remain visible even though they point at coordinates on a different page layout. Conversely, if the wrong file was uploaded by accident and corrected, the annotations are lost. ## Solution: content-based file hash Compute a **SHA-256 hash of the file bytes** on every upload (UI and mass import). Store it as `file_hash` on the document. Each annotation stores the `file_hash` that was current when the annotation was created. The frontend renders annotations only when `annotation.fileHash == document.fileHash`. When they differ, show a non-blocking notice: > *"X Annotationen beziehen sich auf eine frühere Dateiversion."* This is content-based, so uploading the exact same file twice (even with a different filename) correctly restores the annotations. ## User Journey Admin opens a document with annotations on page 1. They realise they scanned the wrong page and upload the correct scan. The annotation highlight disappears and a notice explains it belongs to the previous file. The admin re-uploads the original scan — the annotation reappears automatically without any manual action. ## E2E Scenarios ``` Scenario: Annotations are hidden after a different file is uploaded Given a document has a PDF with an annotation When an admin uploads a different PDF to the same document Then the annotation is no longer visible And a notice "Annotationen beziehen sich auf eine frühere Dateiversion" is shown Scenario: Annotations reappear after re-uploading the original file Given a document's annotation is hidden (different file uploaded) When an admin re-uploads the original PDF Then the annotation is visible again And the notice is no longer shown ``` ## Implementation notes - Backend: add `file_hash VARCHAR(64)` column to `documents` (Flyway migration); compute SHA-256 in `FileService.upload()` and store on the document - Backend: add `file_hash VARCHAR(64)` column to `document_annotations`; set from `document.fileHash` at annotation creation time - Mass import: `MassImportService` calls `FileService` already — hash computed there automatically - Frontend: expose `fileHash` on `DocumentResponse`; expose `fileHash` on `AnnotationResponse`; filter annotation rendering accordingly; show notice when at least one annotation has a different hash - No annotations are ever deleted by a file upload — all data is preserved

marcel referenced this issue

2026-03-24 08:47:19 +01:00

As an admin I want to backfill file hashes for already-uploaded documents so existing files are covered by the annotation versioning feature #56

marcel added the feature collaboration labels 2026-03-24 10:09:54 +01:00

marcel referenced this issue from a commit

2026-03-24 17:09:55 +01:00

feat(backend): hash uploaded files and store hash on documents and annotations

marcel referenced this issue from a commit

2026-03-24 17:09:55 +01:00

feat(frontend): hide outdated annotations when file version changes

marcel referenced a pull request that will close this issue

2026-03-24 17:12:00 +01:00