feat(person): enforce person-delete integrity at the DB layer (V71) (#684)

Add ON DELETE behaviour to the two V1 FKs into persons (documents.sender_id
-> SET NULL, document_receivers.person_id -> CASCADE) and a real FK with
ON DELETE CASCADE on the transcription_block_mentioned_persons soft reference,
cleaning up pre-existing orphan mention rows first. The cascade stays strictly
at the join/reference layer and never reaches documents rows.

Proven by new Postgres-backed PersonRepositoryTest cascade tests (AC-1/2/3/8
plus the cascade-boundary document-survival guard). Rewrites the now-stale
V56 'no FK' comment.

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

backend/src/main/resources/db/migration/V56__add_transcription_block_mentioned_persons.sql

@@ -8,12 +8,13 @@
 -- all blocks mentioning person X" query on the person detail page joins on
 -- the indexed person_id column — equally fast as JSONB GIN containment, no
 -- new dependency. document_comments.comment_mentions stays as a many-to-many
--- to AppUser; the divergence is intentional: Person mentions need lazy
--- degradation when a person is deleted (no FK), while user mentions don't.
+-- to AppUser; the divergence is intentional.
 --
--- No FK on person_id: when a Person is deleted we want @Auguste Raddatz to
--- remain visible as plain unlinked text inside the transcription rather than
--- vanishing or cascade-deleting the block.
+-- person_id FK: added in V71 with ON DELETE CASCADE (this column was originally
+-- created without a FK — that decision was reversed). The literal "@Name" in
+-- transcription_blocks.text keeps the name visible after a person is deleted;
+-- the sidecar row carries only the link and is removed with the person, so the
+-- read renderer degrades to plain unlinked text. See ADR-032.
 
 CREATE TABLE transcription_block_mentioned_persons (
     block_id      UUID          NOT NULL REFERENCES transcription_blocks(id) ON DELETE CASCADE,

backend/src/main/resources/db/migration/V71__person_delete_on_delete_fk.sql

@@ -0,0 +1,50 @@
+-- Move person-delete referential integrity from application code into the database (#684).
+--
+-- Before this migration, PersonService.deletePerson nulled documents.sender_id and removed
+-- document_receivers rows in Java before deleting the person, because the two V1 FKs into
+-- persons had no ON DELETE behaviour. Any other delete path (a future endpoint, a manual
+-- psql, a batch job) could still orphan rows or 500. This migration makes the database the
+-- single source of truth so a person delete is safe from every path.
+--
+-- Cascade boundary: the cascade stays STRICTLY at the join/reference layer and NEVER reaches
+-- documents rows — a cascade into documents would destroy historical letters. sender_id is
+-- SET NULL (documents.senderText preserves the raw textual attribution); the receiver join
+-- row and the @-mention sidecar row are dropped.
+--
+-- No NOT VALID + VALIDATE two-step: these tables are small (thousands of rows → sub-second
+-- ACCESS EXCLUSIVE lock). Do NOT copy this drop-and-recreate pattern onto a large table.
+--
+-- Not audit-logged: a DB ON DELETE cascade runs below AuditService — a known, accepted trade.
+-- The person-delete action itself is still logged at the service layer.
+
+-- documents.sender_id → ON DELETE SET NULL (deleted sender clears the link; the document survives).
+ALTER TABLE public.documents
+    DROP CONSTRAINT fkl5xhww7es3b4um01vmly4y18m,
+    ADD CONSTRAINT fkl5xhww7es3b4um01vmly4y18m
+        FOREIGN KEY (sender_id) REFERENCES public.persons(id) ON DELETE SET NULL;
+
+-- document_receivers.person_id → ON DELETE CASCADE (drop the join row), the symmetric
+-- completion of V14, which added the same to the document_id side of this table.
+ALTER TABLE public.document_receivers
+    DROP CONSTRAINT fkcg7r68qvosqricx1betgrlt7s,
+    ADD CONSTRAINT fkcg7r68qvosqricx1betgrlt7s
+        FOREIGN KEY (person_id) REFERENCES public.persons(id) ON DELETE CASCADE;
+
+-- Soft reference fix: transcription_block_mentioned_persons.person_id was a UUID with no FK
+-- (V56), so deleting a person left dangling mention rows. Give it a real FK with CASCADE.
+-- Clean up pre-existing orphans first — production likely holds dangling rows because the old
+-- deletePerson never cleaned mention rows, and the ADD CONSTRAINT validation scan fails on them.
+-- A DO block with RAISE NOTICE surfaces the purge count: Flyway runs each statement via JDBC
+-- and discards a trailing SELECT's result set, so a "SELECT count(*)" would log nothing.
+DO $$
+DECLARE removed int;
+BEGIN
+    DELETE FROM transcription_block_mentioned_persons m
+    WHERE NOT EXISTS (SELECT 1 FROM persons p WHERE p.id = m.person_id);
+    GET DIAGNOSTICS removed = ROW_COUNT;
+    RAISE NOTICE 'V71 orphaned_mention_rows_removed=%', removed;
+END $$;
+
+ALTER TABLE public.transcription_block_mentioned_persons
+    ADD CONSTRAINT fk_tbmp_person
+        FOREIGN KEY (person_id) REFERENCES public.persons(id) ON DELETE CASCADE;