feat(series): assisted-continuation matcher + suggestion queue — backend (FC-6.3)

Confirm-only "this post may continue this series" matcher. - series_suggestion table (post_id, series_tag_id, score, signals jsonb, status pending|added|dismissed, UNIQUE(post,series)); migration 0041 + two settings knobs (series_suggest_enabled, series_suggest_threshold). - series_match_service: weighted additive score (title-stem / same-artist / page-continuity / shared-distinctive-tags), no single signal gating. The title "pattern" is derived on the fly from the post titles already in a series, so it sharpens as more are confirmed (no persisted state to drift). Candidates are bounded to the post's artist. match_post upserts pending suggestions (UNIQUE + on-conflict, respecting prior added/dismissed decisions). - accept reuses add_post_as_chapter then marks 'added'; dismiss marks 'dismissed'. - rescan_series_suggestions_task: settings-gated, time-boxed + self-resuming from a post-id cursor (maintenance_long lane), like normalize_tags_task. - API: GET /series/suggestions, POST .../<id>/accept|dismiss, POST .../rescan. - Settings: enabled + threshold exposed via /settings/import. - Tests: pure scoring helpers + matcher/accept/dismiss/rescan lifecycle + UNIQUE dedup. Frontend (Suggestions tab + settings card) lands next. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-07 18:58:18 -04:00
parent 9e262cc5f0
commit c0fd80e694
10 changed files with 785 additions and 0 deletions
@@ -0,0 +1,48 @@
+"""Pure scoring helpers for the series continuation matcher (FC-6.3)."""
+
+from backend.app.services.series_match_service import (
+    normalize_title,
+    pages_signal,
+    tags_signal,
+    title_signal,
+    weighted_score,
+)
+
+
+def test_normalize_title_strips_installment_markers():
+    assert normalize_title("Story pages 9-12") == "story"
+    assert normalize_title("Bunker Diaries 04") == "bunker diaries"
+    assert normalize_title("My Comic [3/8]") == "my comic"
+    assert normalize_title("") == ""
+    assert normalize_title(None) == ""
+
+
+def test_title_signal():
+    # Same stem after stripping page markers → full match.
+    assert title_signal(["Story pages 1-4"], "Story pages 9-12") == 1.0
+    # Unrelated → no overlap.
+    assert title_signal(["My Comic"], "Other Thing") == 0.0
+    # No data → 0.
+    assert title_signal([], "x") == 0.0
+
+
+def test_pages_signal():
+    assert pages_signal(8, 9) == 1.0      # clean continuation
+    assert pages_signal(8, 10) == 0.5     # near (diff 2)
+    assert pages_signal(8, 11) == 0.5     # near (diff 3)
+    assert pages_signal(8, 20) == 0.0     # far
+    assert pages_signal(8, 5) == 0.0      # before / overlap
+    assert pages_signal(None, 9) == 0.0
+
+
+def test_tags_signal():
+    assert tags_signal(0) == 0.0
+    assert tags_signal(3) == 1.0
+    assert tags_signal(6) == 1.0          # capped
+    assert round(tags_signal(1), 3) == 0.333
+
+
+def test_weighted_score():
+    assert weighted_score({"title": 1, "artist": 1, "pages": 1, "tags": 1}) == 1.0
+    assert weighted_score({}) == 0.0
+    assert weighted_score({"title": 1.0, "artist": 1.0}) == 0.6
@@ -0,0 +1,127 @@
+"""FC-6.3 — matcher writes pending suggestions; accept/dismiss lifecycle."""
+
+import pytest
+from sqlalchemy import func, select
+
+from backend.app.models import Artist, ImageRecord, Post, TagKind
+from backend.app.models.series_suggestion import SeriesSuggestion
+from backend.app.services.series_match_service import SeriesMatchService
+from backend.app.services.series_service import SeriesService
+
+pytestmark = pytest.mark.integration
+
+_SEQ = 0
+
+
+async def _artist(db, name):
+    a = Artist(name=name, slug=name.lower().replace(" ", "-"))
+    db.add(a)
+    await db.flush()
+    return a
+
+
+async def _post_with_images(db, artist, title, ext, n):
+    global _SEQ
+    p = Post(artist_id=artist.id, external_post_id=ext, post_title=title)
+    db.add(p)
+    await db.flush()
+    for _ in range(n):
+        _SEQ += 1
+        db.add(ImageRecord(
+            path=f"/tmp/fc_sm_{_SEQ}.png", sha256=f"{_SEQ:064d}",
+            size_bytes=1, mime="image/png", origin="downloaded",
+            primary_post_id=p.id, artist_id=artist.id,
+        ))
+    await db.flush()
+    return p
+
+
+async def _series_from(db, post):
+    out = await SeriesService(db).promote_post_to_series(post.id)
+    return out["series_tag_id"]
+
+
+@pytest.mark.asyncio
+async def test_match_post_suggests_continuation(db):
+    artist = await _artist(db, "Story Artist")
+    a = await _post_with_images(db, artist, "Story pages 1-4", "a", 4)
+    sid = await _series_from(db, a)            # series stated 1-4
+    b = await _post_with_images(db, artist, "Story pages 5-8", "b", 4)
+
+    svc = SeriesMatchService(db)
+    made = await svc.match_post(b.id, threshold=0.5)
+    assert made == 1
+
+    pending = await svc.list_pending()
+    assert len(pending) == 1
+    sug = pending[0]
+    assert sug["series_tag_id"] == sid
+    assert sug["post_id"] == b.id
+    # title 1.0 + artist 1.0 + pages 1.0 (5 == 4+1) → 0.4+0.2+0.25 = 0.85
+    assert sug["score"] >= 0.85
+    assert sug["signals"]["pages"] == 1.0
+
+
+@pytest.mark.asyncio
+async def test_match_is_idempotent_under_unique(db):
+    artist = await _artist(db, "Idem Artist")
+    a = await _post_with_images(db, artist, "Tale pages 1-4", "a", 2)
+    await _series_from(db, a)
+    b = await _post_with_images(db, artist, "Tale pages 5-8", "b", 2)
+    svc = SeriesMatchService(db)
+    await svc.match_post(b.id, threshold=0.5)
+    await svc.match_post(b.id, threshold=0.5)  # again
+    cnt = await db.scalar(
+        select(func.count()).select_from(SeriesSuggestion)
+        .where(SeriesSuggestion.post_id == b.id)
+    )
+    assert cnt == 1
+
+
+@pytest.mark.asyncio
+async def test_accept_adds_chapter_and_marks_added(db):
+    artist = await _artist(db, "Accept Artist")
+    a = await _post_with_images(db, artist, "Saga pages 1-4", "a", 3)
+    sid = await _series_from(db, a)
+    b = await _post_with_images(db, artist, "Saga pages 5-8", "b", 3)
+    svc = SeriesMatchService(db)
+    await svc.match_post(b.id, threshold=0.5)
+    sug = (await svc.list_pending())[0]
+
+    await svc.accept(sug["id"])
+    data = await SeriesService(db).list_pages(sid)
+    assert len(data["chapters"]) == 2          # b became a 2nd chapter
+    status = await db.scalar(
+        select(SeriesSuggestion.status).where(SeriesSuggestion.id == sug["id"])
+    )
+    assert status == "added"
+
+
+@pytest.mark.asyncio
+async def test_dismiss_then_rematch_skips(db):
+    artist = await _artist(db, "Dismiss Artist")
+    a = await _post_with_images(db, artist, "Epic pages 1-4", "a", 2)
+    await _series_from(db, a)
+    b = await _post_with_images(db, artist, "Epic pages 5-8", "b", 2)
+    svc = SeriesMatchService(db)
+    await svc.match_post(b.id, threshold=0.5)
+    sug = (await svc.list_pending())[0]
+
+    await svc.dismiss(sug["id"])
+    assert await svc.list_pending() == []
+    # A re-match must respect the dismissal (decided → skipped).
+    made = await svc.match_post(b.id, threshold=0.5)
+    assert made == 0
+
+
+@pytest.mark.asyncio
+async def test_rescan_scans_posts(db):
+    artist = await _artist(db, "Rescan Artist")
+    a = await _post_with_images(db, artist, "Quest pages 1-4", "a", 2)
+    await _series_from(db, a)
+    await _post_with_images(db, artist, "Quest pages 5-8", "b", 2)
+    svc = SeriesMatchService(db)
+    summary = await svc.rescan(threshold=0.5)
+    assert summary["scanned"] >= 2
+    assert summary["suggested"] >= 1
+    assert summary["partial"] is False