refactor: govern background tasks and query ownership

app/db/models/site.py

@@ -6,7 +6,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import Mapped, Session, mapped_column
 
 from app.db.base import Base, get_id_column
-from app.db.decorators import db_query, async_db_query
+from app.db.decorators import run_legacy_async_query, run_legacy_sync_query
 
 
 class Site(Base):
@@ -58,48 +58,114 @@ class Site(Base):
     downloader: Mapped[Optional[str]] = mapped_column(String)
 
     @classmethod
-    @db_query
-    def get_by_domain(cls, db: Session, domain: str):
-        return db.execute(select(cls).where(cls.domain == domain)).scalars().first()
+    def get_by_domain(cls, db: Session | str | None = None, domain: str | None = None):
+        """按域名查询站点，兼容显式会话和旧插件无会话调用。"""
+        if domain is None and isinstance(db, str):
+            domain, db = db, None
+        if domain is None:
+            raise TypeError("domain is required")
+
+        def query(session: Session):
+            """在给定同步会话中执行域名查询。"""
+            return session.execute(select(cls).where(cls.domain == domain)).scalars().first()
+
+        return query(db) if isinstance(db, Session) else run_legacy_sync_query(query)
 
     @classmethod
-    @async_db_query
-    async def async_get_by_domain(cls, db: AsyncSession, domain: str):
-        result = await db.execute(select(cls).where(cls.domain == domain))
-        return result.scalar_one_or_none()
+    async def async_get_by_domain(
+        cls,
+        db: AsyncSession | str | None = None,
+        domain: str | None = None,
+    ):
+        """异步按域名查询站点，兼容显式会话和旧插件无会话调用。"""
+        if domain is None and isinstance(db, str):
+            domain, db = db, None
+        if domain is None:
+            raise TypeError("domain is required")
+
+        async def query(session: AsyncSession):
+            """在给定异步会话中执行域名查询。"""
+            result = await session.execute(select(cls).where(cls.domain == domain))
+            return result.scalar_one_or_none()
+
+        return await query(db) if isinstance(db, AsyncSession) else await run_legacy_async_query(query)
 
     @classmethod
-    @async_db_query
-    async def async_get_by_name(cls, db: AsyncSession, name: str):
-        result = await db.execute(select(cls).where(cls.name == name))
-        return result.scalar_one_or_none()
+    async def async_get_by_name(
+        cls,
+        db: AsyncSession | str | None = None,
+        name: str | None = None,
+    ):
+        """异步按站点名称查询，兼容显式会话和旧插件无会话调用。"""
+        if name is None and isinstance(db, str):
+            name, db = db, None
+        if name is None:
+            raise TypeError("name is required")
+
+        async def query(session: AsyncSession):
+            """在给定异步会话中执行名称查询。"""
+            result = await session.execute(select(cls).where(cls.name == name))
+            return result.scalar_one_or_none()
+
+        return await query(db) if isinstance(db, AsyncSession) else await run_legacy_async_query(query)
 
     @classmethod
-    @db_query
-    def get_actives(cls, db: Session):
-        return list(db.execute(select(cls).where(cls.is_active.is_(True))).scalars().all())
+    def get_actives(cls, db: Session | None = None):
+        """查询启用站点，兼容显式会话和旧插件无会话调用。"""
+        def query(session: Session):
+            """在给定同步会话中执行启用站点查询。"""
+            return list(session.execute(select(cls).where(cls.is_active.is_(True))).scalars().all())
+
+        return query(db) if isinstance(db, Session) else run_legacy_sync_query(query)
 
     @classmethod
-    @async_db_query
-    async def async_get_actives(cls, db: AsyncSession):
-        result = await db.execute(select(cls).where(cls.is_active.is_(True)))
-        return list(result.scalars().all())
+    async def async_get_actives(cls, db: AsyncSession | None = None):
+        """异步查询启用站点，兼容显式会话和旧插件无会话调用。"""
+        async def query(session: AsyncSession):
+            """在给定异步会话中执行启用站点查询。"""
+            result = await session.execute(select(cls).where(cls.is_active.is_(True)))
+            return list(result.scalars().all())
+
+        return await query(db) if isinstance(db, AsyncSession) else await run_legacy_async_query(query)
 
     @classmethod
-    @db_query
-    def list_order_by_pri(cls, db: Session):
-        return list(db.execute(select(cls).order_by(cls.pri)).scalars().all())
+    def list_order_by_pri(cls, db: Session | None = None):
+        """按优先级升序查询站点，兼容显式会话和旧插件无会话调用。"""
+        def query(session: Session):
+            """在给定同步会话中执行优先级查询。"""
+            return list(session.execute(select(cls).order_by(cls.pri)).scalars().all())
+
+        return query(db) if isinstance(db, Session) else run_legacy_sync_query(query)
 
     @classmethod
-    @async_db_query
-    async def async_list_order_by_pri(cls, db: AsyncSession):
-        result = await db.execute(select(cls).order_by(cls.pri))
-        return list(result.scalars().all())
+    async def async_list_order_by_pri(cls, db: AsyncSession | None = None):
+        """异步按优先级升序查询站点，兼容显式会话和旧插件无会话调用。"""
+        async def query(session: AsyncSession):
+            """在给定异步会话中执行优先级查询。"""
+            result = await session.execute(select(cls).order_by(cls.pri))
+            return list(result.scalars().all())
+
+        return await query(db) if isinstance(db, AsyncSession) else await run_legacy_async_query(query)
 
     @classmethod
-    @db_query
-    def get_domains_by_ids(cls, db: Session, ids: list):
-        return list(db.execute(select(cls.domain).where(cls.id.in_(ids))).scalars().all())
+    def get_domains_by_ids(
+        cls,
+        db: Session | list[int] | None = None,
+        ids: list[int] | None = None,
+    ):
+        """按 ID 查询域名，兼容显式会话和旧插件无会话调用。"""
+        if ids is None and isinstance(db, list):
+            ids, db = db, None
+        if ids is None:
+            raise TypeError("ids is required")
+        if not ids:
+            return []
+
+        def query(session: Session):
+            """在给定同步会话中执行域名投影查询。"""
+            return list(session.execute(select(cls.domain).where(cls.id.in_(ids))).scalars().all())
+
+        return query(db) if isinstance(db, Session) else run_legacy_sync_query(query)
 
     @classmethod
     def reset(cls, db: Session):