fix(data): harden portfolio publication concurrency

2026-06-01 09:46:18 +03:00
parent d591e5ed5a
commit 3c1a98bcc4
11 changed files with 648 additions and 79 deletions
@@ -91,11 +91,12 @@ public async Task MigrationV029_ShouldCreatePortfolioTablesAndPublicationGuards(
    Assert.Contains("CREATE INDEX ix_portfolio_games_group ON portfolio_games (group_id, completed_at DESC);", normalizedMigration, StringComparison.Ordinal);
    Assert.Contains("CREATE INDEX ix_portfolio_game_masters_player ON portfolio_game_masters (player_id, portfolio_game_id);", normalizedMigration, StringComparison.Ordinal);
    Assert.Contains("CREATE INDEX ix_portfolio_game_reviews_pending ON portfolio_game_reviews (portfolio_game_id, created_at DESC) WHERE moderation_status = 'Pending';", normalizedMigration, StringComparison.Ordinal);
-    Assert.Contains("CREATE FUNCTION unpublish_portfolio_game_without_required_links() RETURNS TRIGGER LANGUAGE plpgsql", normalizedMigration, StringComparison.Ordinal);
-    Assert.Contains("PERFORM 1 FROM portfolio_games WHERE id = OLD.portfolio_game_id FOR UPDATE;", normalizedMigration, StringComparison.Ordinal);
-    Assert.Contains("UPDATE portfolio_games SET is_public = false, updated_at = now()", normalizedMigration, StringComparison.Ordinal);
-    Assert.Contains("CREATE TRIGGER trg_portfolio_game_sessions_unpublish_after_delete AFTER DELETE ON portfolio_game_sessions", normalizedMigration, StringComparison.Ordinal);
-    Assert.Contains("CREATE TRIGGER trg_portfolio_game_masters_unpublish_after_delete AFTER DELETE ON portfolio_game_masters", normalizedMigration, StringComparison.Ordinal);
+    Assert.Contains("CREATE FUNCTION validate_public_portfolio_game_required_links() RETURNS TRIGGER LANGUAGE plpgsql", normalizedMigration, StringComparison.Ordinal);
+    Assert.Contains("USING ERRCODE = '23514';", normalizedMigration, StringComparison.Ordinal);
+    Assert.Contains("CREATE CONSTRAINT TRIGGER trg_portfolio_games_validate_required_links AFTER INSERT OR UPDATE OF is_public ON portfolio_games DEFERRABLE INITIALLY DEFERRED", normalizedMigration, StringComparison.Ordinal);
+    Assert.Contains("CREATE CONSTRAINT TRIGGER trg_portfolio_game_sessions_validate_required_links AFTER DELETE OR UPDATE OF portfolio_game_id ON portfolio_game_sessions DEFERRABLE INITIALLY DEFERRED", normalizedMigration, StringComparison.Ordinal);
+    Assert.Contains("CREATE CONSTRAINT TRIGGER trg_portfolio_game_masters_validate_required_links AFTER DELETE OR UPDATE OF portfolio_game_id ON portfolio_game_masters DEFERRABLE INITIALLY DEFERRED", normalizedMigration, StringComparison.Ordinal);
+    Assert.DoesNotContain("FOR UPDATE", normalizedMigration, StringComparison.Ordinal);
 }
 ```

@@ -178,47 +179,64 @@ CREATE TABLE portfolio_game_masters (
 CREATE INDEX ix_portfolio_game_masters_player
    ON portfolio_game_masters (player_id, portfolio_game_id);

-CREATE FUNCTION unpublish_portfolio_game_without_required_links()
+CREATE FUNCTION validate_public_portfolio_game_required_links()
 RETURNS TRIGGER
 LANGUAGE plpgsql
 AS $$
+DECLARE
+    target_portfolio_game_id UUID;
 BEGIN
-    PERFORM 1
-    FROM portfolio_games
-    WHERE id = OLD.portfolio_game_id
-    FOR UPDATE;
+    IF TG_TABLE_NAME = 'portfolio_games' THEN
+        target_portfolio_game_id := NEW.id;
+    ELSE
+        target_portfolio_game_id := OLD.portfolio_game_id;
+    END IF;

-    UPDATE portfolio_games
-    SET is_public = false,
-        updated_at = now()
-    WHERE id = OLD.portfolio_game_id
-      AND is_public = true
-      AND (
-          NOT EXISTS (
-              SELECT 1
-              FROM portfolio_game_sessions
-              WHERE portfolio_game_id = OLD.portfolio_game_id
+    IF EXISTS (
+        SELECT 1
+        FROM portfolio_games pg
+        WHERE pg.id = target_portfolio_game_id
+          AND pg.is_public = true
+          AND (
+              NOT EXISTS (
+                  SELECT 1
+                  FROM portfolio_game_sessions pgs
+                  WHERE pgs.portfolio_game_id = target_portfolio_game_id
+              )
+              OR NOT EXISTS (
+                  SELECT 1
+                  FROM portfolio_game_masters pgm
+                  WHERE pgm.portfolio_game_id = target_portfolio_game_id
+              )
          )
-          OR NOT EXISTS (
-              SELECT 1
-              FROM portfolio_game_masters
-              WHERE portfolio_game_id = OLD.portfolio_game_id
-          )
-      );
+    ) THEN
+        RAISE EXCEPTION
+            'published portfolio game % must have at least one linked session and at least one linked master',
+            target_portfolio_game_id
+            USING ERRCODE = '23514';
+    END IF;

-    RETURN OLD;
+    RETURN NULL;
 END;
 $$;

-CREATE TRIGGER trg_portfolio_game_sessions_unpublish_after_delete
-AFTER DELETE ON portfolio_game_sessions
+CREATE CONSTRAINT TRIGGER trg_portfolio_games_validate_required_links
+AFTER INSERT OR UPDATE OF is_public ON portfolio_games
+DEFERRABLE INITIALLY DEFERRED
 FOR EACH ROW
-EXECUTE FUNCTION unpublish_portfolio_game_without_required_links();
+EXECUTE FUNCTION validate_public_portfolio_game_required_links();

-CREATE TRIGGER trg_portfolio_game_masters_unpublish_after_delete
-AFTER DELETE ON portfolio_game_masters
+CREATE CONSTRAINT TRIGGER trg_portfolio_game_sessions_validate_required_links
+AFTER DELETE OR UPDATE OF portfolio_game_id ON portfolio_game_sessions
+DEFERRABLE INITIALLY DEFERRED
 FOR EACH ROW
-EXECUTE FUNCTION unpublish_portfolio_game_without_required_links();
+EXECUTE FUNCTION validate_public_portfolio_game_required_links();
+
+CREATE CONSTRAINT TRIGGER trg_portfolio_game_masters_validate_required_links
+AFTER DELETE OR UPDATE OF portfolio_game_id ON portfolio_game_masters
+DEFERRABLE INITIALLY DEFERRED
+FOR EACH ROW
+EXECUTE FUNCTION validate_public_portfolio_game_required_links();

 CREATE TABLE portfolio_game_reviews (
    id                     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -245,7 +263,7 @@ CREATE INDEX ix_portfolio_game_reviews_pending
    WHERE moderation_status = 'Pending';
 ```

-The delete triggers retain the link-table `ON DELETE CASCADE` behavior. They lock the parent card before checking both required link sets, unpublish the card and refresh `updated_at` when either set becomes empty, preserve the first-publication `published_at`, and become harmless no-ops while the card itself or its owning club is being deleted.
+The deferred constraint triggers retain the link-table `ON DELETE CASCADE` behavior. At transaction commit they reject a surviving published card when either required link set is empty. Child delete triggers do not lock or update the parent card, avoiding reverse lock order. Normal session-deletion handlers explicitly unpublish linked cards before deleting sessions. Card and club cascade deletion remain harmless because no published parent survives validation.

 - [ ] **Step 4: Run the migration tests to verify GREEN**

@@ -741,10 +759,10 @@ ModeratePortfolioReviewAsync
 Rules:

 - Draft creation optionally links one session only if it belongs to the same group, is in the past, and is not linked elsewhere.
- Update runs in one transaction, locks the portfolio row, updates scalar fields, replaces child links, rejects cross-club or future sessions, and accepts only managers from the same club.
+- Update runs in one transaction, locks the portfolio row, updates scalar fields, unpublishes the card before replacing required child links, replaces child links, rejects cross-club or future sessions, and accepts only managers from the same club.
 - Cover replacement returns the prior storage key after the database update.
 - Delete returns the cover key after deleting the row.
- Publishing locks the row and verifies slug, description, cover key, one or more linked past sessions, and one or more masters before setting `is_public = true` and `published_at = COALESCE(published_at, now())`.
+- Publishing locks the row and verifies slug, description, cover key, one or more linked past sessions, and one or more masters before setting `is_public = true` and `published_at = COALESCE(published_at, now())`. The deferred database guard is a backstop for direct SQL and concurrent changes.
 - Unpublishing only sets `is_public = false`.
 - Moderation accepts `Approved`, `Rejected`, or `Hidden`, stores moderator ID and timestamp, and scopes the review to the managed adventure.

@@ -77,9 +77,9 @@ CHECK (NOT is_public OR (
 - Index on `(group_id, completed_at DESC)`.
 - Partial public index on `(completed_at DESC)` where `is_public = true`.

-Application validation additionally requires at least one linked completed session and at least one linked GM before publishing because those requirements span child tables.
+Application validation additionally requires at least one linked completed session and at least one linked GM before publishing because those requirements span child tables. Publishing locks the parent card, validates both required link sets, then sets `is_public = true` and `published_at = COALESCE(published_at, now())` so `published_at` remains the first-publication timestamp. Link replacement locks the parent card and unpublishes it before replacing required links.

-Database triggers on `portfolio_game_sessions` and `portfolio_game_masters` protect the same invariant after link removal. After a link is deleted, the trigger locks the parent card, checks both required link sets, and sets `is_public = false` with a fresh `updated_at` when either set is empty. It deliberately preserves `published_at` as the timestamp of the first publication. The link foreign keys retain `ON DELETE CASCADE`; when the card itself or its owning club is deleted, the trigger update is a harmless no-op for the disappearing parent row.
+Deferred database constraint triggers validate the same invariant at transaction commit after a card transitions to public or a required session/master link is deleted or moved. They raise a check-violation error if a published card would commit without both required link sets. The deferred guard is a database backstop and deliberately does not lock or update a parent card from a child delete trigger, avoiding reverse lock order. Normal session-deletion handlers explicitly unpublish linked cards in the same transaction before deleting the session. The link foreign keys retain `ON DELETE CASCADE`; when the card itself or its owning club is deleted, deferred validation sees no surviving published card and remains harmless.

 ### `portfolio_game_sessions`

@@ -341,7 +341,8 @@ Follow TDD for production changes.

 ### Schema And Contracts

- Migration source-contract tests assert the four new tables, format constraint, publication guard, case-insensitive slug uniqueness, group and GM-profile indexes, card-oriented pending-review index, and the link-removal trigger protection.
+- Migration source-contract tests assert the four new tables, format constraint, publication guard, case-insensitive slug uniqueness, group and GM-profile indexes, card-oriented pending-review index, and deferred constraint-trigger backstop.
+- PostgreSQL integration tests apply migrations V001 through V029 to `postgres:17-alpine` and cover direct invalid link removal, explicit unpublish before session deletion, concurrent publish/delete ordering without deadlock, and parent/card cascade deletion.
 - Public DTO reflection/source tests assert that private identifiers and physical storage paths are absent.
 - Existing showcase tests continue to assert the future-session catalog boundary.