Add collection/franchise ingestion

Collections were bare stubs (name only) lazily created the moment a
movie's belongs_to_collection reference was seen. Adds a real
ingest_collection pipeline: TMDb's /collection/{id} for overview and
poster/backdrop artwork, plus ordered CollectionMovie membership --
linking only movies already ingested into Aurora, the same
never-fabricate-a-stub rule movie recommendations already follow.

get_or_create_collection now refreshes name/overview on an existing
stub instead of only creating, guarded so a bare movie-stub call
(overview=None) never clobbers real data a full ingestion already
filled in.

New POST /api/v1/admin/ingest/collection endpoint and
ingest_collection_task; GET /api/v1/collections/{id} needed no changes
since its read path (collection_service.py) already assembled the full
detail shape.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

tests/integration/test_collection_ingestion.py

@@ -0,0 +1,182 @@
+"""Integration tests for collection/franchise ingestion (section 15): a fake
+provider stands in for TMDb so these run without network access, while
+still exercising the real normalize -> match -> upsert -> provenance path
+against PostgreSQL."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.ids import aurora_id
+from app.models.artwork import Artwork
+from app.models.collection import Collection, CollectionMovie
+from app.providers.base import MetadataProvider
+from app.services import collection_service
+from app.services.ingestion.collection_ingestion import ingest_collection
+from app.services.ingestion.movie_ingestion import ingest_movie
+from tests.unit.test_normalizer import FAKE_COLLECTION, FAKE_MOVIE
+
+
+class FakeTMDbCollectionProvider(MetadataProvider):
+    slug = "tmdb"
+    name = "The Movie Database (TMDb)"
+
+    def __init__(
+        self, movie_payloads: dict[str, dict[str, Any]], collection_payload: dict[str, Any]
+    ) -> None:
+        self._movie_payloads = movie_payloads
+        self._collection_payload = collection_payload
+
+    async def get_movie(self, external_id: str) -> dict[str, Any]:
+        return self._movie_payloads[external_id]
+
+    async def get_series(self, external_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def get_season(self, series_external_id: str, season_number: int) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def get_person(self, external_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
+    async def get_collection(self, external_id: str) -> dict[str, Any]:
+        return self._collection_payload
+
+    async def search_movie(self, query: str) -> list[dict[str, Any]]:
+        raise NotImplementedError
+
+
+@pytest.mark.asyncio
+async def test_ingest_collection_only_links_already_ingested_movies(db_session: AsyncSession):
+    """Two of FAKE_COLLECTION's four parts (603, 604) are ingested first;
+    605 and 999 are not -- CollectionMovie must link only the two Aurora
+    already knows about, in release-date order, never fabricate a stub for
+    the other two (section 15)."""
+
+    provider = FakeTMDbCollectionProvider(
+        movie_payloads={
+            "603": {**FAKE_MOVIE, "id": 603, "title": "The Matrix"},
+            "604": {**FAKE_MOVIE, "id": 604, "title": "The Matrix Reloaded"},
+        },
+        collection_payload=FAKE_COLLECTION,
+    )
+
+    await ingest_movie(db_session, provider, "603")
+    await ingest_movie(db_session, provider, "604")
+    await db_session.flush()
+
+    collection_id = await ingest_collection(db_session, provider, "2344")
+    await db_session.commit()
+
+    collection = await db_session.get(Collection, collection_id)
+    assert collection is not None
+    assert collection.name == "The Matrix Collection"
+    assert collection.overview == "A group of films..."
+
+    links = (
+        (
+            await db_session.execute(
+                select(CollectionMovie)
+                .where(CollectionMovie.collection_id == collection_id)
+                .order_by(CollectionMovie.sort_order.asc())
+            )
+        )
+        .scalars()
+        .all()
+    )
+    assert len(links) == 2
+
+    detail = await collection_service.get_collection_detail(
+        db_session, aurora_id("collection", str(collection_id))
+    )
+    assert [m.title for m in detail.movies] == ["The Matrix", "The Matrix Reloaded"]
+    assert detail.poster_path is not None
+    assert detail.poster_path.endswith("/collection-poster.jpg")
+
+
+@pytest.mark.asyncio
+async def test_ingest_collection_is_idempotent_and_does_not_duplicate_links(
+    db_session: AsyncSession,
+):
+    provider = FakeTMDbCollectionProvider(
+        movie_payloads={"603": {**FAKE_MOVIE, "id": 603, "title": "The Matrix"}},
+        collection_payload=FAKE_COLLECTION,
+    )
+
+    await ingest_movie(db_session, provider, "603")
+    await db_session.flush()
+
+    first_id = await ingest_collection(db_session, provider, "2344")
+    await db_session.flush()
+    second_id = await ingest_collection(db_session, provider, "2344")
+    await db_session.commit()
+
+    assert first_id == second_id
+
+    all_collections = (await db_session.execute(select(Collection))).scalars().all()
+    assert len(all_collections) == 1
+
+    links = (
+        (
+            await db_session.execute(
+                select(CollectionMovie).where(CollectionMovie.collection_id == first_id)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    assert len(links) == 1
+
+
+@pytest.mark.asyncio
+async def test_ingest_collection_does_not_clobber_overview_from_movie_stub(
+    db_session: AsyncSession,
+):
+    """A movie referencing this collection via belongs_to_collection creates
+    a bare stub (name only, overview=None) *after* the real ingest_collection
+    already ran -- get_or_create_collection must not blank the real overview
+    back to None just because the stub call has none to offer."""
+
+    provider = FakeTMDbCollectionProvider(
+        movie_payloads={
+            "603": {**FAKE_MOVIE, "id": 603, "title": "The Matrix"},
+            "604": {**FAKE_MOVIE, "id": 604, "title": "The Matrix Reloaded"},
+        },
+        collection_payload=FAKE_COLLECTION,
+    )
+
+    collection_id = await ingest_collection(db_session, provider, "2344")
+    await db_session.flush()
+
+    await ingest_movie(db_session, provider, "604")
+    await db_session.commit()
+
+    collection = await db_session.get(Collection, collection_id)
+    assert collection.overview == "A group of films..."
+
+
+@pytest.mark.asyncio
+async def test_ingest_collection_ingests_poster_and_backdrop_artwork(db_session: AsyncSession):
+    provider = FakeTMDbCollectionProvider(movie_payloads={}, collection_payload=FAKE_COLLECTION)
+
+    collection_id = await ingest_collection(db_session, provider, "2344")
+    await db_session.commit()
+
+    artwork = (
+        (
+            await db_session.execute(
+                select(Artwork).where(
+                    Artwork.entity_type == "collection", Artwork.entity_id == collection_id
+                )
+            )
+        )
+        .scalars()
+        .all()
+    )
+    types = {a.artwork_type.value for a in artwork}
+    assert types == {"poster", "backdrop"}
+    assert all(a.is_primary for a in artwork)

tests/integration/test_movie_ingestion.py

@@ -44,6 +44,9 @@ class FakeTMDbProvider(MetadataProvider):
     async def get_person(self, external_id: str) -> dict[str, Any]:
         raise NotImplementedError
 
+    async def get_collection(self, external_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
     async def search_movie(self, query: str) -> list[dict[str, Any]]:
         raise NotImplementedError
 

tests/integration/test_series_ingestion.py

@@ -39,6 +39,9 @@ class FakeTMDbSeriesProvider(MetadataProvider):
     async def get_person(self, external_id: str) -> dict[str, Any]:
         raise NotImplementedError
 
+    async def get_collection(self, external_id: str) -> dict[str, Any]:
+        raise NotImplementedError
+
     async def search_movie(self, query: str) -> list[dict[str, Any]]:
         raise NotImplementedError
 

tests/unit/test_normalizer.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 from datetime import date
 
 from app.services.metadata.normalizer import (
+    normalize_collection,
     normalize_movie,
     normalize_person,
     normalize_season,
@@ -403,3 +404,50 @@ def test_normalize_season_maps_episode_crew_and_stills():
 def test_normalize_season_handles_episode_without_still():
     season = normalize_season(FAKE_SEASON)
     assert season.episodes[1].stills == []
+
+
+FAKE_COLLECTION = {
+    "id": 2344,
+    "name": "The Matrix Collection",
+    "overview": "A group of films...",
+    "poster_path": "/collection-poster.jpg",
+    "backdrop_path": "/collection-backdrop.jpg",
+    "parts": [
+        {"id": 605, "title": "The Matrix Revolutions", "release_date": "2003-11-05"},
+        {"id": 603, "title": "The Matrix", "release_date": "1999-03-30"},
+        {"id": 604, "title": "The Matrix Reloaded", "release_date": "2003-05-15"},
+        {"id": 999, "title": "Untitled Prequel", "release_date": ""},
+    ],
+}
+
+
+def test_normalize_collection_maps_basic_fields():
+    collection = normalize_collection(FAKE_COLLECTION)
+    assert collection.external_id == "2344"
+    assert collection.name == "The Matrix Collection"
+    assert collection.overview == "A group of films..."
+
+
+def test_normalize_collection_maps_poster_and_backdrop_as_primary_artwork():
+    collection = normalize_collection(FAKE_COLLECTION)
+    poster = next(a for a in collection.artwork if a.artwork_type == "poster")
+    backdrop = next(a for a in collection.artwork if a.artwork_type == "backdrop")
+    assert poster.is_primary is True
+    assert poster.url.endswith("/collection-poster.jpg")
+    assert backdrop.is_primary is True
+    assert backdrop.url.endswith("/collection-backdrop.jpg")
+
+
+def test_normalize_collection_orders_parts_by_release_date_not_array_order():
+    collection = normalize_collection(FAKE_COLLECTION)
+    # Input order is [605, 603, 604, 999] -- release-date order puts the
+    # undated "999" entry last rather than fabricating a sort position.
+    assert collection.part_external_ids == ["603", "604", "605", "999"]
+
+
+def test_normalize_collection_handles_missing_overview_and_parts():
+    minimal = {"id": 1, "name": "Minimal Collection"}
+    collection = normalize_collection(minimal)
+    assert collection.overview is None
+    assert collection.artwork == []
+    assert collection.part_external_ids == []