feat(offset): add automatic season/episode offset detection

- Add offset detector to identify season mismatches between RSS and TMDB
- Only suggest season_offset (user sets episode_offset manually)
- Add background scanner for existing bangumi rules
- Add detect-offset and dismiss-review API endpoints
- Add warning banner in edit dialog with auto-detect button
- Add iOS-style notification badge for needs_review items
- Yellow badge with "!" for warnings, purple badge for multi-rule count
- Combined badge shows "! | 2" when both conditions apply
- Yellow glow animation on cards needing review
- Highlight warning items in rule selection popup

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: EstrellaXD

backend/src/module/api/bangumi.py

@@ -1,18 +1,59 @@
+from typing import Literal, Optional
+
 from fastapi import APIRouter, Depends
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel
 
+from module.conf import settings
+from module.database import Database
 from module.manager import TorrentManager
 from module.models import APIResponse, Bangumi, BangumiUpdate
+from module.parser.analyser.offset_detector import (
+    OffsetSuggestion as DetectorSuggestion,
+)
+from module.parser.analyser.offset_detector import detect_offset_mismatch
+from module.parser.analyser.tmdb_parser import tmdb_parser
 from module.security.api import UNAUTHORIZED, get_current_user
 
 from .response import u_response
 
 
 class OffsetSuggestion(BaseModel):
+    """Legacy offset suggestion model."""
     suggested_offset: int
     reason: str
 
+
+class TMDBSummary(BaseModel):
+    """Summary of TMDB data for display."""
+    title: str
+    total_seasons: int
+    season_episode_counts: dict[int, int]
+    status: Optional[str]
+    virtual_season_starts: Optional[dict[int, list[int]]] = None  # {1: [1, 29], ...}
+
+
+class OffsetSuggestionDetail(BaseModel):
+    """Detailed offset suggestion from detector."""
+    season_offset: int
+    episode_offset: int
+    reason: str
+    confidence: Literal["high", "medium", "low"]
+
+
+class DetectOffsetRequest(BaseModel):
+    """Request body for detect-offset endpoint."""
+    title: str
+    parsed_season: int
+    parsed_episode: int
+
+
+class DetectOffsetResponse(BaseModel):
+    """Response for detect-offset endpoint."""
+    has_mismatch: bool
+    suggestion: Optional[OffsetSuggestionDetail]
+    tmdb_info: Optional[TMDBSummary]
+
 router = APIRouter(prefix="/bangumi", tags=["bangumi"])
 
 
@@ -202,3 +243,99 @@ async def suggest_offset(bangumi_id: int):
     with TorrentManager() as manager:
         resp = await manager.suggest_offset(bangumi_id)
     return resp
+
+
+@router.post(
+    path="/detect-offset",
+    response_model=DetectOffsetResponse,
+    dependencies=[Depends(get_current_user)],
+)
+async def detect_offset(request: DetectOffsetRequest):
+    """Detect season/episode mismatch with TMDB data.
+
+    Called by frontend before adding/subscribing to check if offsets are needed.
+    """
+    language = settings.rss_parser.language
+    tmdb_info = await tmdb_parser(request.title, language)
+
+    if not tmdb_info:
+        return DetectOffsetResponse(
+            has_mismatch=False,
+            suggestion=None,
+            tmdb_info=None,
+        )
+
+    # Detect mismatch
+    suggestion = detect_offset_mismatch(
+        parsed_season=request.parsed_season,
+        parsed_episode=request.parsed_episode,
+        tmdb_info=tmdb_info,
+    )
+
+    # Build TMDB summary
+    tmdb_summary = TMDBSummary(
+        title=tmdb_info.title,
+        total_seasons=tmdb_info.last_season,
+        season_episode_counts=tmdb_info.season_episode_counts or {},
+        status=tmdb_info.series_status,
+        virtual_season_starts=tmdb_info.virtual_season_starts,
+    )
+
+    if suggestion:
+        return DetectOffsetResponse(
+            has_mismatch=True,
+            suggestion=OffsetSuggestionDetail(
+                season_offset=suggestion.season_offset,
+                episode_offset=suggestion.episode_offset,
+                reason=suggestion.reason,
+                confidence=suggestion.confidence,
+            ),
+            tmdb_info=tmdb_summary,
+        )
+
+    return DetectOffsetResponse(
+        has_mismatch=False,
+        suggestion=None,
+        tmdb_info=tmdb_summary,
+    )
+
+
+@router.post(
+    path="/dismiss-review/{bangumi_id}",
+    response_model=APIResponse,
+    dependencies=[Depends(get_current_user)],
+)
+async def dismiss_review(bangumi_id: int):
+    """Clear the needs_review flag for a bangumi after user reviews."""
+    with Database() as db:
+        success = db.bangumi.clear_needs_review(bangumi_id)
+
+    if success:
+        return JSONResponse(
+            status_code=200,
+            content={
+                "status": True,
+                "msg_en": "Review dismissed.",
+                "msg_zh": "已取消检查标记。",
+            },
+        )
+    else:
+        return JSONResponse(
+            status_code=404,
+            content={
+                "status": False,
+                "msg_en": f"Bangumi {bangumi_id} not found.",
+                "msg_zh": f"未找到番剧 {bangumi_id}。",
+            },
+        )
+
+
+@router.get(
+    path="/needs-review",
+    response_model=list[Bangumi],
+    dependencies=[Depends(get_current_user)],
+)
+async def get_needs_review():
+    """Get all bangumi that need review for offset mismatch."""
+    with Database() as db:
+        return db.bangumi.get_needs_review()

backend/src/module/core/offset_scanner.py

@@ -0,0 +1,117 @@
+"""Background scanner for detecting season/episode offset mismatches."""
+
+import logging
+
+from module.conf import settings
+from module.database import Database
+from module.models import Bangumi
+from module.parser.analyser.offset_detector import detect_offset_mismatch
+from module.parser.analyser.tmdb_parser import tmdb_parser
+
+logger = logging.getLogger(__name__)
+
+
+class OffsetScanner:
+    """Periodically scan bangumi for season/episode mismatches with TMDB."""
+
+    async def scan_all(self) -> int:
+        """Scan all active bangumi for offset mismatches.
+
+        Returns:
+            Number of bangumi flagged for review.
+        """
+        logger.info("[OffsetScanner] Starting offset scan...")
+
+        with Database() as db:
+            bangumi_list = db.bangumi.get_active_for_scan()
+
+        if not bangumi_list:
+            logger.debug("[OffsetScanner] No active bangumi to scan.")
+            return 0
+
+        flagged_count = 0
+        for bangumi in bangumi_list:
+            try:
+                if await self._check_bangumi(bangumi):
+                    flagged_count += 1
+            except Exception as e:
+                logger.warning(
+                    f"[OffsetScanner] Error checking {bangumi.official_title}: {e}"
+                )
+
+        logger.info(
+            f"[OffsetScanner] Scan complete. Flagged {flagged_count} bangumi for review."
+        )
+        return flagged_count
+
+    async def _check_bangumi(self, bangumi: Bangumi) -> bool:
+        """Check a single bangumi for offset mismatch.
+
+        Args:
+            bangumi: The bangumi to check.
+
+        Returns:
+            True if flagged for review, False otherwise.
+        """
+        # Skip if already needs review
+        if bangumi.needs_review:
+            logger.debug(
+                f"[OffsetScanner] Skipping {bangumi.official_title}: already needs review"
+            )
+            return False
+
+        # Skip if user has already configured offsets
+        if bangumi.season_offset != 0 or bangumi.episode_offset != 0:
+            logger.debug(
+                f"[OffsetScanner] Skipping {bangumi.official_title}: has configured offsets"
+            )
+            return False
+
+        # Get TMDB info
+        language = settings.rss_parser.language
+        tmdb_info = await tmdb_parser(bangumi.official_title, language)
+
+        if not tmdb_info:
+            logger.debug(
+                f"[OffsetScanner] Skipping {bangumi.official_title}: no TMDB info"
+            )
+            return False
+
+        # Get latest episode for this bangumi (use season as proxy since we don't track episodes)
+        # For now, we'll check based on the bangumi's season
+        parsed_episode = 1  # Default to episode 1 for season-based detection
+
+        # Detect mismatch
+        suggestion = detect_offset_mismatch(
+            parsed_season=bangumi.season,
+            parsed_episode=parsed_episode,
+            tmdb_info=tmdb_info,
+        )
+
+        if suggestion and suggestion.confidence in ("high", "medium"):
+            with Database() as db:
+                db.bangumi.set_needs_review(bangumi.id, suggestion.reason)
+            logger.info(
+                f"[OffsetScanner] Flagged {bangumi.official_title} for review: {suggestion.reason}"
+            )
+            return True
+
+        return False
+
+    async def check_single(self, bangumi_id: int) -> bool:
+        """Check a single bangumi by ID.
+
+        Args:
+            bangumi_id: The ID of the bangumi to check.
+
+        Returns:
+            True if flagged for review, False otherwise.
+        """
+        with Database() as db:
+            bangumi = db.bangumi.search_id(bangumi_id)
+
+        if not bangumi:
+            logger.warning(f"[OffsetScanner] Bangumi {bangumi_id} not found")
+            return False
+
+        return await self._check_bangumi(bangumi)

backend/src/module/core/program.py

@@ -13,7 +13,7 @@
     start_up,
 )
 
-from .sub_thread import RenameThread, RSSThread
+from .sub_thread import OffsetScanThread, RenameThread, RSSThread
 
 logger = logging.getLogger(__name__)
 
@@ -29,7 +29,7 @@
 """
 
 
-class Program(RenameThread, RSSThread):
+class Program(RenameThread, RSSThread, OffsetScanThread):
     @staticmethod
     def __start_info():
         for line in figlet.splitlines():
@@ -91,6 +91,8 @@ async def start(self):
             self.rename_start()
         if self.enable_rss:
             self.rss_start()
+        # Start offset scanner for background mismatch detection
+        self.scan_start()
         logger.info("Program running.")
         return ResponseModel(
             status=True,
@@ -104,6 +106,7 @@ async def stop(self):
             self.stop_event.set()
             await self.rename_stop()
             await self.rss_stop()
+            await self.scan_stop()
             return ResponseModel(
                 status=True,
                 status_code=200,

backend/src/module/core/sub_thread.py

@@ -1,13 +1,17 @@
 import asyncio
+import logging
 
 from module.conf import settings
 from module.downloader import DownloadClient
 from module.manager import Renamer, eps_complete
 from module.notification import PostNotification
 from module.rss import RSSAnalyser, RSSEngine
 
+from .offset_scanner import OffsetScanner
 from .status import ProgramStatus
 
+logger = logging.getLogger(__name__)
+
 
 class RSSThread(ProgramStatus):
     def __init__(self):
@@ -83,3 +87,50 @@ async def rename_stop(self):
             except asyncio.CancelledError:
                 pass
             self._rename_task = None
+
+
+# Offset scan interval in seconds (6 hours)
+OFFSET_SCAN_INTERVAL = 6 * 60 * 60
+
+
+class OffsetScanThread(ProgramStatus):
+    """Background thread for scanning bangumi offset mismatches."""
+
+    def __init__(self):
+        super().__init__()
+        self._scan_task: asyncio.Task | None = None
+        self._scanner = OffsetScanner()
+
+    async def scan_loop(self):
+        # Initial delay to let the system stabilize
+        await asyncio.sleep(60)
+
+        while not self.stop_event.is_set():
+            try:
+                flagged = await self._scanner.scan_all()
+                logger.info(f"[OffsetScanThread] Scan complete, flagged {flagged} bangumi")
+            except Exception as e:
+                logger.error(f"[OffsetScanThread] Error during scan: {e}")
+
+            try:
+                await asyncio.wait_for(
+                    self.stop_event.wait(),
+                    timeout=OFFSET_SCAN_INTERVAL,
+                )
+            except asyncio.TimeoutError:
+                pass
+
+    def scan_start(self):
+        self._scan_task = asyncio.create_task(self.scan_loop())
+        logger.info("[OffsetScanThread] Started offset scanner")
+
+    async def scan_stop(self):
+        if self._scan_task and not self._scan_task.done():
+            self.stop_event.set()
+            self._scan_task.cancel()
+            try:
+                await self._scan_task
+            except asyncio.CancelledError:
+                pass
+            self._scan_task = None
+            logger.info("[OffsetScanThread] Stopped offset scanner")