feat(tag): add upsertBySourceRef keyed on canonical tag_path

Idempotent tag upsert for the Phase-3 importer (ADR-025). source_ref is
the stable identity (the canonical tag_path); on re-import a
human-renamed tag name is preserved while the parent link is refreshed.

Refs #669

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

backend/src/main/java/org/raddatz/familienarchiv/tag/TagRepository.java

@@ -22,6 +22,9 @@ public interface TagRepository extends JpaRepository<Tag, UUID> {
 
     Optional<Tag> findByNameIgnoreCase(String name);
 
+    // Lookup by the canonical tag_path, used for idempotent canonical re-import (Phase 3).
+    Optional<Tag> findBySourceRef(String sourceRef);
+
     List<Tag> findByNameContainingIgnoreCase(String name);
 
     /**

backend/src/main/java/org/raddatz/familienarchiv/tag/TagService.java

@@ -55,6 +55,26 @@ public class TagService {
                 .orElseGet(() -> tagRepository.save(Tag.builder().name(cleanName).build()));
     }
 
+    /**
+     * Idempotent upsert keyed on {@code sourceRef} (the canonical tag_path) for the
+     * Phase-3 importer (ADR-025). On first import the canonical name and parent are
+     * written; on re-import a human-renamed tag name is preserved (the source_ref is the
+     * stable identity, the name is a human-editable label).
+     */
+    @Transactional
+    public Tag upsertBySourceRef(String sourceRef, String name, UUID parentId) {
+        return tagRepository.findBySourceRef(sourceRef)
+                .map(existing -> {
+                    existing.setParentId(parentId);
+                    return tagRepository.save(existing);
+                })
+                .orElseGet(() -> tagRepository.save(Tag.builder()
+                        .sourceRef(sourceRef)
+                        .name(name)
+                        .parentId(parentId)
+                        .build()));
+    }
+
     @Transactional
     public Tag update(UUID id, TagUpdateDTO dto) {
         Tag tag = getById(id);