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>

backend/app/models/__init__.py

@@ -18,6 +18,7 @@ from .patreon_failed_media import PatreonFailedMedia
 from .patreon_seen_media import PatreonSeenMedia
 from .post import Post
 from .post_attachment import PostAttachment
+from .series_chapter import SeriesChapter
 from .series_page import SeriesPage
 from .source import Source
 from .tag import Tag, TagKind, image_tag
@@ -39,6 +40,7 @@ __all__ = [
     "PatreonSeenMedia",
     "Post",
     "PostAttachment",
+    "SeriesChapter",
     "SeriesPage",
     "ImageRecord",
     "ImageProvenance",

backend/app/models/series_chapter.py

@@ -0,0 +1,47 @@
+"""SeriesChapter — an ordered chapter/part within a series.
+
+A series IS a Tag(kind='series'); a chapter groups ordered SeriesPages under it.
+Reading order is (chapter.chapter_number, series_page.page_number): chapter_number
+sets the order of chapters, page_number orders pages within a chapter.
+
+chapter_number is an ordering key only (not unique) — reorder rewrites 1..N
+wholesale, mirroring series_page.page_number, so a reorder can't transiently
+collide on a unique index.
+
+A chapter may be a placeholder (is_placeholder=True) — a reserved empty slot for
+a section the operator doesn't have yet; it holds no pages and shows as a gap in
+the reader. stated_page_start/end carry the page range parsed from the source
+post (FC-6.2), used to flag missing-page gaps; both are nullable when unknown.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, Text, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class SeriesChapter(Base):
+    __tablename__ = "series_chapter"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    series_tag_id: Mapped[int] = mapped_column(
+        ForeignKey("tag.id", ondelete="CASCADE"), nullable=False, index=True
+    )
+    chapter_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    title: Mapped[str | None] = mapped_column(Text, nullable=True)
+    is_placeholder: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, server_default="false"
+    )
+    stated_page_start: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    stated_page_end: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        server_default=func.now(),
+        onupdate=func.now(),
+    )

backend/app/models/series_page.py

@@ -1,9 +1,12 @@
 """SeriesPage — ordered image membership for a series-kind Tag.
 
-A series IS a Tag with kind='series'; series_page gives it ordered pages.
-An image belongs to at most one series (UNIQUE image_id). Cover = the
-lowest page_number. page_number is an ordering key only (not unique) —
-reorder rewrites 1..N wholesale.
+A series IS a Tag with kind='series'; series_page gives it ordered pages,
+grouped into chapters (FC-6). An image belongs to at most one series
+(UNIQUE image_id) ⇒ at most one chapter. Reading order is
+(chapter.chapter_number, series_page.page_number): page_number orders pages
+WITHIN a chapter and is an ordering key only (not unique) — reorder rewrites
+1..N wholesale. stated_page carries the page number parsed from the source
+post (FC-6.2), nullable when unknown.
 """
 
 from datetime import datetime
@@ -21,12 +24,18 @@ class SeriesPage(Base):
     series_tag_id: Mapped[int] = mapped_column(
         ForeignKey("tag.id", ondelete="CASCADE"), nullable=False, index=True
     )
+    chapter_id: Mapped[int] = mapped_column(
+        ForeignKey("series_chapter.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
     image_id: Mapped[int] = mapped_column(
         ForeignKey("image_record.id", ondelete="CASCADE"),
         nullable=False,
         unique=True,
     )
     page_number: Mapped[int] = mapped_column(Integer, nullable=False)
+    stated_page: Mapped[int | None] = mapped_column(Integer, nullable=True)
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, server_default=func.now()
     )