feat(series): SeriesPage model + 0005 migration (unique image, ordered pages)

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

alembic/versions/0005_fc2c_iii_a_series_page.py

@@ -0,0 +1,50 @@
+"""fc2c-iii-a: series_page ordered membership
+
+Revision ID: 0005
+Revises: 0004
+Create Date: 2026-05-16
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0005"
+down_revision: Union[str, None] = "0004"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "series_page",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("series_tag_id", sa.Integer(), nullable=False),
+        sa.Column("image_id", sa.Integer(), nullable=False),
+        sa.Column("page_number", sa.Integer(), nullable=False),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True),
+            nullable=False, server_default=sa.func.now(),
+        ),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True),
+            nullable=False, server_default=sa.func.now(),
+        ),
+        sa.ForeignKeyConstraint(
+            ["series_tag_id"], ["tag.id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(
+            ["image_id"], ["image_record.id"], ondelete="CASCADE"
+        ),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("image_id", name="uq_series_page_image"),
+    )
+    op.create_index(
+        "ix_series_page_series_tag_id", "series_page", ["series_tag_id"]
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_series_page_series_tag_id", table_name="series_page")
+    op.drop_table("series_page")

backend/app/models/__init__.py

@@ -11,6 +11,7 @@ from .import_settings import ImportSettings
 from .import_task import ImportTask
 from .ml_settings import MLSettings
 from .post import Post
+from .series_page import SeriesPage
 from .source import Source
 from .tag import Tag, TagKind, image_tag
 from .tag_alias import TagAlias
@@ -24,6 +25,7 @@ __all__ = [
     "Source",
     "Credential",
     "Post",
+    "SeriesPage",
     "ImageRecord",
     "ImageProvenance",
     "Tag",

backend/app/models/series_page.py

@@ -0,0 +1,38 @@
+"""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.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .base import Base
+
+
+class SeriesPage(Base):
+    __tablename__ = "series_page"
+
+    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
+    )
+    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)
+    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(),
+    )

tests/test_series_model.py

@@ -0,0 +1,40 @@
+import pytest
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from backend.app.models import ImageRecord, TagKind
+from backend.app.models.series_page import SeriesPage
+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_sp_{_SEQ}.png", sha256=f"{_SEQ:064d}",
+        size_bytes=1, mime="image/png", origin="uploaded",
+    )
+    db.add(rec)
+    await db.flush()
+    return rec.id
+
+
+@pytest.mark.asyncio
+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))
+    await db.flush()
+    got = await db.scalar(
+        select(SeriesPage.page_number).where(SeriesPage.image_id == i1)
+    )
+    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))
+    with pytest.raises(IntegrityError):
+        await db.flush()