feat(series): chapter layer over series_page — backend (FC-6.1)

Adds an ordered chapter layer to series. Reading order becomes
(series_chapter.chapter_number, series_page.page_number); a chapter may be a
placeholder reserving a slot, and carries an optional parsed stated-page range
used to flag missing-page gaps. An image still lives in at most one series ⇒ one
chapter (image_id stays UNIQUE).

- models: series_chapter; series_page gains chapter_id (NOT NULL, cascade) +
  stated_page. Migration 0040 backfills every existing series into one
  auto-chapter holding its current flat pages — no data loss.
- SeriesService: chapter CRUD (create/update/reorder/delete/merge), page→chapter
  assignment, reorder_pages, chapter-aware set_cover; list_pages now returns
  chapters[] + gaps[] alongside a back-compat flat pages[]. Legacy series-wide
  reorder operates on the single default chapter and rejects multi-chapter series.
- API: chapter endpoints under /api/series/<tag>/chapters; POST pages accepts an
  optional chapter_id.
- TagService.merge now repoints series_chapter too, so a merged series' chapters
  (and their pages) survive the source tag's deletion instead of cascading away.
- Tests: new chapter suite; updated the 4 direct SeriesPage(...) constructions to
  supply chapter_id.

Frontend (chapter-aware manage view + reader) lands next; until then the
existing UI keeps working via the flat pages[] + single default chapter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

tests/test_cleanup_service.py

@@ -9,6 +9,7 @@ import pytest
 from sqlalchemy import func, select
 
 from backend.app.models import Artist, ImageRecord, Tag, TagKind
+from backend.app.models.series_chapter import SeriesChapter
 from backend.app.models.series_page import SeriesPage
 from backend.app.models.tag import image_tag
 from backend.app.services import cleanup_service
@@ -376,7 +377,12 @@ def test_reset_content_tagging_deletes_content_keeps_fandom_series(db_sync, tmp_
         {"image_record_id": img.id, "tag_id": c.id},
         {"image_record_id": img.id, "tag_id": s.id},  # series membership
     ]))
-    db_sync.add(SeriesPage(series_tag_id=s.id, image_id=img.id, page_number=1))
+    ch = SeriesChapter(series_tag_id=s.id, chapter_number=1)
+    db_sync.add(ch)
+    db_sync.flush()
+    db_sync.add(SeriesPage(
+        series_tag_id=s.id, chapter_id=ch.id, image_id=img.id, page_number=1
+    ))
     db_sync.commit()
 
     result = cleanup_service.reset_content_tagging(db_sync, dry_run=False)

tests/test_series_chapters.py

@@ -0,0 +1,193 @@
+"""FC-6.1 — chapter layer over series_page."""
+
+import pytest
+from sqlalchemy import func, select
+
+from backend.app.models import ImageRecord, TagKind
+from backend.app.models.series_chapter import SeriesChapter
+from backend.app.models.series_page import SeriesPage
+from backend.app.services.series_service import SeriesError, SeriesService
+from backend.app.services.tag_service import TagService
+
+pytestmark = pytest.mark.integration
+
+_SEQ = 0
+
+
+async def _img(db):
+    global _SEQ
+    _SEQ += 1
+    rec = ImageRecord(
+        path=f"/tmp/fc_sc_{_SEQ}.png", sha256=f"{_SEQ:064d}",
+        size_bytes=1, mime="image/png", origin="uploaded",
+    )
+    db.add(rec)
+    await db.flush()
+    return rec.id
+
+
+async def _series(db, name):
+    return (await TagService(db).find_or_create(name, TagKind.series)).id
+
+
+async def _chapter_numbers(db, sid):
+    rows = (
+        await db.execute(
+            select(SeriesChapter.id, SeriesChapter.chapter_number)
+            .where(SeriesChapter.series_tag_id == sid)
+            .order_by(SeriesChapter.chapter_number)
+        )
+    ).all()
+    return [(r.id, r.chapter_number) for r in rows]
+
+
+async def _page_order(db, chapter_id):
+    rows = (
+        await db.execute(
+            select(SeriesPage.image_id)
+            .where(SeriesPage.chapter_id == chapter_id)
+            .order_by(SeriesPage.page_number)
+        )
+    ).scalars().all()
+    return list(rows)
+
+
+@pytest.mark.asyncio
+async def test_add_images_creates_default_chapter(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C1")
+    i1, i2 = await _img(db), await _img(db)
+    await svc.add_images(sid, [i1, i2])
+    chapters = await _chapter_numbers(db, sid)
+    assert len(chapters) == 1
+    assert chapters[0][1] == 1
+    assert await _page_order(db, chapters[0][0]) == [i1, i2]
+
+
+@pytest.mark.asyncio
+async def test_create_and_target_specific_chapter(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C2")
+    i1, i2 = await _img(db), await _img(db)
+    await svc.add_images(sid, [i1])  # default chapter 1
+    ch2 = await svc.create_chapter(sid, title="Two")
+    assert ch2["chapter_number"] == 2
+    await svc.add_images(sid, [i2], chapter_id=ch2["id"])
+    assert await _page_order(db, ch2["id"]) == [i2]
+    # i1 stayed in chapter 1.
+    chapters = await _chapter_numbers(db, sid)
+    assert len(chapters) == 2
+
+
+@pytest.mark.asyncio
+async def test_reorder_chapters(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C3")
+    c1 = (await svc.create_chapter(sid))["id"]
+    c2 = (await svc.create_chapter(sid))["id"]
+    c3 = (await svc.create_chapter(sid))["id"]
+    await svc.reorder_chapters(sid, [c3, c1, c2])
+    assert await _chapter_numbers(db, sid) == [(c3, 1), (c1, 2), (c2, 3)]
+    with pytest.raises(SeriesError):
+        await svc.reorder_chapters(sid, [c1, c2])
+
+
+@pytest.mark.asyncio
+async def test_reorder_pages_within_chapter(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C4")
+    i1, i2, i3 = await _img(db), await _img(db), await _img(db)
+    await svc.add_images(sid, [i1, i2, i3])
+    cid = (await _chapter_numbers(db, sid))[0][0]
+    await svc.reorder_pages(sid, cid, [i3, i1, i2])
+    assert await _page_order(db, cid) == [i3, i1, i2]
+
+
+@pytest.mark.asyncio
+async def test_legacy_reorder_rejects_multi_chapter(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C5")
+    i1 = await _img(db)
+    await svc.add_images(sid, [i1])
+    await svc.create_chapter(sid)  # now 2 chapters
+    with pytest.raises(SeriesError):
+        await svc.reorder(sid, [i1])
+
+
+@pytest.mark.asyncio
+async def test_merge_chapter_moves_pages_and_renumbers(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C6")
+    i1, i2, i3 = await _img(db), await _img(db), await _img(db)
+    await svc.add_images(sid, [i1])  # chapter 1
+    c2 = (await svc.create_chapter(sid))["id"]
+    await svc.add_images(sid, [i2, i3], chapter_id=c2)
+    c1 = (await _chapter_numbers(db, sid))[0][0]
+    moved = await svc.merge_chapter(sid, c2, c1)
+    assert moved == 2
+    assert await _page_order(db, c1) == [i1, i2, i3]
+    # source chapter gone; remaining renumbered 1..N.
+    assert await _chapter_numbers(db, sid) == [(c1, 1)]
+
+
+@pytest.mark.asyncio
+async def test_delete_chapter_cascades_pages_and_renumbers(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C7")
+    i1, i2 = await _img(db), await _img(db)
+    await svc.add_images(sid, [i1])
+    c2 = (await svc.create_chapter(sid))["id"]
+    await svc.add_images(sid, [i2], chapter_id=c2)
+    await svc.delete_chapter(sid, c2)
+    assert [c for _, c in await _chapter_numbers(db, sid)] == [1]
+    # i2's page cascaded away with its chapter.
+    cnt = await db.scalar(
+        select(func.count()).select_from(SeriesPage)
+        .where(SeriesPage.image_id == i2)
+    )
+    assert cnt == 0
+
+
+@pytest.mark.asyncio
+async def test_set_cover_brings_chapter_and_page_to_front(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C8")
+    i1, i2, i3 = await _img(db), await _img(db), await _img(db)
+    await svc.add_images(sid, [i1])  # chapter 1
+    c2 = (await svc.create_chapter(sid))["id"]
+    await svc.add_images(sid, [i2, i3], chapter_id=c2)
+    await svc.set_cover(sid, i3)
+    chapters = await _chapter_numbers(db, sid)
+    assert chapters[0][0] == c2  # i3's chapter is now first
+    assert (await _page_order(db, c2))[0] == i3  # i3 first in its chapter
+
+
+@pytest.mark.asyncio
+async def test_list_pages_flags_gaps_from_stated_ranges(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C9")
+    await svc.create_chapter(sid, stated_page_start=1, stated_page_end=4)
+    await svc.create_chapter(sid, stated_page_start=9, stated_page_end=12)
+    out = await svc.list_pages(sid)
+    assert len(out["chapters"]) == 2
+    assert len(out["gaps"]) == 1
+    assert out["gaps"][0]["start"] == 5
+    assert out["gaps"][0]["end"] == 8
+
+
+@pytest.mark.asyncio
+async def test_add_with_stated_pages_records_them(db):
+    svc = SeriesService(db)
+    sid = await _series(db, "C10")
+    i1, i2 = await _img(db), await _img(db)
+    await svc.add_images(sid, [i1, i2], stated_pages={i1: 9, i2: 10})
+    rows = dict(
+        (
+            await db.execute(
+                select(SeriesPage.image_id, SeriesPage.stated_page)
+                .where(SeriesPage.series_tag_id == sid)
+            )
+        ).all()
+    )
+    assert rows[i1] == 9
+    assert rows[i2] == 10

tests/test_series_model.py

@@ -3,6 +3,7 @@ from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 
 from backend.app.models import ImageRecord, TagKind
+from backend.app.models.series_chapter import SeriesChapter
 from backend.app.models.series_page import SeriesPage
 from backend.app.services.tag_service import TagService
 
@@ -24,10 +25,20 @@ async def _img(db):
 
 
 @pytest.mark.asyncio
+async def _chapter(db, series_tag_id):
+    ch = SeriesChapter(series_tag_id=series_tag_id, chapter_number=1)
+    db.add(ch)
+    await db.flush()
+    return ch.id
+
+
 async def test_series_page_roundtrip_and_unique_image(db):
     s = await TagService(db).find_or_create("Vol1", TagKind.series)
     i1 = await _img(db)
-    db.add(SeriesPage(series_tag_id=s.id, image_id=i1, page_number=1))
+    ch = await _chapter(db, s.id)
+    db.add(SeriesPage(
+        series_tag_id=s.id, chapter_id=ch, image_id=i1, page_number=1
+    ))
     await db.flush()
     got = await db.scalar(
         select(SeriesPage.page_number).where(SeriesPage.image_id == i1)
@@ -35,6 +46,9 @@ async def test_series_page_roundtrip_and_unique_image(db):
     assert got == 1
     # UNIQUE image_id: same image can't be a page twice (any series).
     s2 = await TagService(db).find_or_create("Vol2", TagKind.series)
-    db.add(SeriesPage(series_tag_id=s2.id, image_id=i1, page_number=1))
+    ch2 = await _chapter(db, s2.id)
+    db.add(SeriesPage(
+        series_tag_id=s2.id, chapter_id=ch2, image_id=i1, page_number=1
+    ))
     with pytest.raises(IntegrityError):
         await db.flush()

tests/test_tag_merge.py

@@ -414,16 +414,27 @@ async def test_alias_create_does_not_clobber_existing(db):
 
 @pytest.mark.asyncio
 async def test_merge_repoints_series_pages(db):
+    from backend.app.models.series_chapter import SeriesChapter
     from backend.app.models.series_page import SeriesPage
 
     svc = TagService(db)
     a = await svc.find_or_create("SerA", TagKind.series)
     b = await svc.find_or_create("SerB", TagKind.series)
     img = await _img(db)
-    db.add(SeriesPage(series_tag_id=a.id, image_id=img, page_number=1))
+    cha = SeriesChapter(series_tag_id=a.id, chapter_number=1)
+    db.add(cha)
+    await db.flush()
+    db.add(SeriesPage(
+        series_tag_id=a.id, chapter_id=cha.id, image_id=img, page_number=1
+    ))
     await db.flush()
     await svc.merge(a.id, b.id)
     owner = await db.scalar(
         select(SeriesPage.series_tag_id).where(SeriesPage.image_id == img)
     )
     assert owner == b.id
+    # The chapter moved to the survivor too, so the page's FK stayed valid.
+    ch_owner = await db.scalar(
+        select(SeriesChapter.series_tag_id).where(SeriesChapter.id == cha.id)
+    )
+    assert ch_owner == b.id