fix: async branch cleanup - fix test races, deadlock, and SQL bug

- Add BackgroundCleanupTracker interface so CleanDbTestListener can wait
  for in-flight async cleanup workers before truncating tables, preventing
  the PostgreSQL deadlock between BranchCleanupWorker's DELETE row locks
  and CleanDbTestListener's ALTER TABLE DISABLE TRIGGER ALL.

- Refactor BranchCleanupWorker: scheduleCleanup() is now a plain method
  (called within the active transaction) that registers the tracker and
  hooks TransactionSynchronization to dispatch the @async executeCleanup()
  after commit (and deregisters on rollback). BranchServiceImpl.deleteBranch
  is reduced to a single branchCleanupWorker.scheduleCleanup() call with no
  transaction sync boilerplate. Self-injection via @lazy enables the
  afterCommit callback to go through the Spring proxy for @async dispatch.

- Fix SQL bug: ScreenshotRepository.findOrphanFilenamesByBranchId used
  native SQL selecting s.filename, but Screenshot.filename is a Kotlin
  computed property (not a DB column). Changed to JPQL returning Screenshot
  entities; updated ScreenshotService.deleteFilesByBranch accordingly.

- Update BranchControllerTest and BranchCopyIntegrationTest to use
  branchCleanupWorker.waitForPendingCleanups() instead of waitForNotThrowing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dkrizan

backend/data/src/main/kotlin/io/tolgee/component/BackgroundCleanupTracker.kt

@@ -0,0 +1,17 @@
+package io.tolgee.component
+
+/**
+ * Implemented by services that perform background (async) data cleanup.
+ *
+ * [CleanDbTestListener] collects all beans of this type and calls
+ * [waitForPendingCleanups] before truncating the database between tests,
+ * preventing deadlocks between the cleanup worker's row-level locks and
+ * the listener's ALTER TABLE … DISABLE TRIGGER ALL statements.
+ */
+interface BackgroundCleanupTracker {
+  /**
+   * Block until all in-flight cleanups started by this service have finished
+   * (either successfully or with an error).
+   */
+  fun waitForPendingCleanups(timeoutMs: Long = 30_000)
+}

backend/data/src/main/kotlin/io/tolgee/repository/ScreenshotRepository.kt

@@ -6,6 +6,7 @@ import io.tolgee.model.key.screenshotReference.KeyScreenshotReference
 import org.springframework.context.annotation.Lazy
 import org.springframework.data.jpa.repository.JpaRepository
 import org.springframework.data.jpa.repository.Query
+import org.springframework.data.repository.query.Param
 import org.springframework.stereotype.Repository
 
 @Repository
@@ -75,4 +76,29 @@ interface ScreenshotRepository : JpaRepository<Screenshot, Long> {
   """,
   )
   fun getAllKeyScreenshotReferences(key: Key): List<KeyScreenshotReference>
+
+  /**
+   * Returns screenshots that will become orphans after all key_screenshot_reference
+   * rows for [branchId]'s keys are deleted — i.e., screenshots referenced ONLY by branch keys
+   * and by no key on any other branch.
+   *
+   * Uses JPQL (not nativeQuery) because Screenshot.filename is a Kotlin computed property,
+   * not a DB column — so it cannot be selected in native SQL.
+   */
+  @Query(
+    """
+    SELECT s FROM Screenshot s
+    WHERE s.id IN (
+      SELECT ksr.screenshot.id FROM KeyScreenshotReference ksr
+      WHERE ksr.key.id IN (SELECT k.id FROM Key k WHERE k.branch.id = :branchId)
+    )
+    AND s.id NOT IN (
+      SELECT ksr.screenshot.id FROM KeyScreenshotReference ksr
+      WHERE ksr.key.id NOT IN (SELECT k.id FROM Key k WHERE k.branch.id = :branchId)
+    )
+    """,
+  )
+  fun findOrphansByBranchId(
+    @Param("branchId") branchId: Long,
+  ): List<Screenshot>
 }

backend/data/src/main/kotlin/io/tolgee/service/key/ScreenshotService.kt

@@ -351,6 +351,17 @@ class ScreenshotService(
     removeScreenshotReferences(all)
   }
 
+  /**
+   * Deletes storage files for screenshots that will become orphans after all
+   * key_screenshot_reference rows for [branchId]'s keys are removed.
+   * The actual DB rows are deleted by the caller via bulk SQL.
+   */
+  fun deleteFilesByBranch(branchId: Long) {
+    screenshotRepository.findOrphansByBranchId(branchId).forEach { screenshot ->
+      deleteFile(screenshot)
+    }
+  }
+
   private fun deleteFile(screenshot: Screenshot) {
     fileStorage.deleteFile(screenshot.getFilePath())
   }

backend/testing/src/main/kotlin/io/tolgee/CleanDbTestListener.kt

@@ -2,6 +2,7 @@ package io.tolgee
 
 import io.tolgee.batch.BatchJobChunkExecutionQueue
 import io.tolgee.batch.BatchJobConcurrentLauncher
+import io.tolgee.component.BackgroundCleanupTracker
 import kotlinx.coroutines.TimeoutCancellationException
 import org.postgresql.util.PSQLException
 import org.slf4j.LoggerFactory
@@ -36,6 +37,13 @@ class CleanDbTestListener : TestExecutionListener {
     val batchJobConcurrentLauncher = appContext.getBean(BatchJobConcurrentLauncher::class.java)
     val batchJobQueue = appContext.getBean(BatchJobChunkExecutionQueue::class.java)
 
+    // Wait for any background cleanup workers (e.g. BranchCleanupWorker) to finish
+    // before truncating tables.  Without this, their long-running transactions hold
+    // row-level locks that deadlock with ALTER TABLE … DISABLE TRIGGER ALL below.
+    appContext.getBeansOfType(BackgroundCleanupTracker::class.java).values.forEach {
+      it.waitForPendingCleanups()
+    }
+
     batchJobConcurrentLauncher.pause = true
     batchJobQueue.clear()
 
@@ -54,7 +62,9 @@ class CleanDbTestListener : TestExecutionListener {
                 }
               }
 
-              else -> throw e
+              else -> {
+                throw e
+              }
             }
             logger.info(
               "Failed to clean DB, retrying in 1s. Attempt ${i + 1}, " +