refactor(sdk): isolate plugin query snapshots

app/sdk/queries.py

@@ -2,41 +2,133 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Protocol, cast
 
 from app.schemas.query import (
     DEFAULT_QUERY_PAGE_SIZE,
     MAX_QUERY_PAGE_SIZE,
-    DownloadHistory,
     DownloadHistoryFilter,
+    DownloadHistorySnapshot,
     MediaIdentityQuery,
     QueryPage,
     QueryPageRequest,
     QuerySort,
     QuerySortDirection,
     QuerySortField,
-    Subscribe,
-    SubscribeHistory,
     SubscriptionFilter,
     SubscriptionHistoryFilter,
-    TransferHistory,
+    SubscriptionHistorySnapshot,
+    SubscriptionSnapshot,
     TransferHistoryFilter,
+    TransferHistorySnapshot,
 )
 
 
-def _service() -> Any:
+class _DataQueryBackend(Protocol):
+    """SDK 转发所需的最小类型合同，不向插件公开应用服务实现。"""
+
+    def list_subscriptions(
+        self,
+        filters: SubscriptionFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[SubscriptionSnapshot]: ...
+
+    async def async_list_subscriptions(
+        self,
+        filters: SubscriptionFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[SubscriptionSnapshot]: ...
+
+    def get_subscription(
+        self,
+        subscription_id: int,
+    ) -> SubscriptionSnapshot | None: ...
+
+    async def async_get_subscription(
+        self,
+        subscription_id: int,
+    ) -> SubscriptionSnapshot | None: ...
+
+    def list_subscription_history(
+        self,
+        filters: SubscriptionHistoryFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[SubscriptionHistorySnapshot]: ...
+
+    async def async_list_subscription_history(
+        self,
+        filters: SubscriptionHistoryFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[SubscriptionHistorySnapshot]: ...
+
+    def get_subscription_history(
+        self,
+        history_id: int,
+    ) -> SubscriptionHistorySnapshot | None: ...
+
+    async def async_get_subscription_history(
+        self,
+        history_id: int,
+    ) -> SubscriptionHistorySnapshot | None: ...
+
+    def list_download_history(
+        self,
+        filters: DownloadHistoryFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[DownloadHistorySnapshot]: ...
+
+    async def async_list_download_history(
+        self,
+        filters: DownloadHistoryFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[DownloadHistorySnapshot]: ...
+
+    def get_download_history(
+        self,
+        history_id: int,
+    ) -> DownloadHistorySnapshot | None: ...
+
+    async def async_get_download_history(
+        self,
+        history_id: int,
+    ) -> DownloadHistorySnapshot | None: ...
+
+    def list_transfer_history(
+        self,
+        filters: TransferHistoryFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[TransferHistorySnapshot]: ...
+
+    async def async_list_transfer_history(
+        self,
+        filters: TransferHistoryFilter | dict[str, Any] | None = None,
+        page: QueryPageRequest | dict[str, Any] | None = None,
+    ) -> QueryPage[TransferHistorySnapshot]: ...
+
+    def get_transfer_history(
+        self,
+        history_id: int,
+    ) -> TransferHistorySnapshot | None: ...
+
+    async def async_get_transfer_history(
+        self,
+        history_id: int,
+    ) -> TransferHistorySnapshot | None: ...
+
+
+def _service() -> _DataQueryBackend:
     """获取启动阶段登记的查询服务，避免把应用服务暴露为 SDK 合同。"""
     from app.application.data_query import (
         get_configured_data_query_service,
     )
 
-    return get_configured_data_query_service()
+    return cast(_DataQueryBackend, get_configured_data_query_service())
 
 
 def list_subscriptions(
     filters: SubscriptionFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[Subscribe]:
+) -> QueryPage[SubscriptionSnapshot]:
     """同步分页读取订阅 DTO。"""
     return _service().list_subscriptions(filters, page)
 
@@ -44,17 +136,19 @@ def list_subscriptions(
 async def async_list_subscriptions(
     filters: SubscriptionFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[Subscribe]:
+) -> QueryPage[SubscriptionSnapshot]:
     """异步分页读取订阅 DTO。"""
     return await _service().async_list_subscriptions(filters, page)
 
 
-def get_subscription(subscription_id: int) -> Subscribe | None:
+def get_subscription(subscription_id: int) -> SubscriptionSnapshot | None:
     """同步按 ID 读取订阅 DTO。"""
     return _service().get_subscription(subscription_id)
 
 
-async def async_get_subscription(subscription_id: int) -> Subscribe | None:
+async def async_get_subscription(
+    subscription_id: int,
+) -> SubscriptionSnapshot | None:
     """异步按 ID 读取订阅 DTO。"""
     return await _service().async_get_subscription(subscription_id)
 
@@ -62,7 +156,7 @@ async def async_get_subscription(subscription_id: int) -> Subscribe | None:
 def list_subscription_history(
     filters: SubscriptionHistoryFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[SubscribeHistory]:
+) -> QueryPage[SubscriptionHistorySnapshot]:
     """同步分页读取订阅完成历史 DTO。"""
     return _service().list_subscription_history(filters, page)
 
@@ -70,17 +164,19 @@ def list_subscription_history(
 async def async_list_subscription_history(
     filters: SubscriptionHistoryFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[SubscribeHistory]:
+) -> QueryPage[SubscriptionHistorySnapshot]:
     """异步分页读取订阅完成历史 DTO。"""
     return await _service().async_list_subscription_history(filters, page)
 
 
-def get_subscription_history(history_id: int) -> SubscribeHistory | None:
+def get_subscription_history(history_id: int) -> SubscriptionHistorySnapshot | None:
     """同步按 ID 读取订阅完成历史 DTO。"""
     return _service().get_subscription_history(history_id)
 
 
-async def async_get_subscription_history(history_id: int) -> SubscribeHistory | None:
+async def async_get_subscription_history(
+    history_id: int,
+) -> SubscriptionHistorySnapshot | None:
     """异步按 ID 读取订阅完成历史 DTO。"""
     return await _service().async_get_subscription_history(history_id)
 
@@ -88,7 +184,7 @@ async def async_get_subscription_history(history_id: int) -> SubscribeHistory |
 def list_download_history(
     filters: DownloadHistoryFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[DownloadHistory]:
+) -> QueryPage[DownloadHistorySnapshot]:
     """同步分页读取下载历史 DTO。"""
     return _service().list_download_history(filters, page)
 
@@ -96,17 +192,19 @@ def list_download_history(
 async def async_list_download_history(
     filters: DownloadHistoryFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[DownloadHistory]:
+) -> QueryPage[DownloadHistorySnapshot]:
     """异步分页读取下载历史 DTO。"""
     return await _service().async_list_download_history(filters, page)
 
 
-def get_download_history(history_id: int) -> DownloadHistory | None:
+def get_download_history(history_id: int) -> DownloadHistorySnapshot | None:
     """同步按 ID 读取下载历史 DTO。"""
     return _service().get_download_history(history_id)
 
 
-async def async_get_download_history(history_id: int) -> DownloadHistory | None:
+async def async_get_download_history(
+    history_id: int,
+) -> DownloadHistorySnapshot | None:
     """异步按 ID 读取下载历史 DTO。"""
     return await _service().async_get_download_history(history_id)
 
@@ -114,7 +212,7 @@ async def async_get_download_history(history_id: int) -> DownloadHistory | None:
 def list_transfer_history(
     filters: TransferHistoryFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[TransferHistory]:
+) -> QueryPage[TransferHistorySnapshot]:
     """同步分页读取整理历史 DTO。"""
     return _service().list_transfer_history(filters, page)
 
@@ -122,17 +220,19 @@ def list_transfer_history(
 async def async_list_transfer_history(
     filters: TransferHistoryFilter | dict[str, Any] | None = None,
     page: QueryPageRequest | dict[str, Any] | None = None,
-) -> QueryPage[TransferHistory]:
+) -> QueryPage[TransferHistorySnapshot]:
     """异步分页读取整理历史 DTO。"""
     return await _service().async_list_transfer_history(filters, page)
 
 
-def get_transfer_history(history_id: int) -> TransferHistory | None:
+def get_transfer_history(history_id: int) -> TransferHistorySnapshot | None:
     """同步按 ID 读取整理历史 DTO。"""
     return _service().get_transfer_history(history_id)
 
 
-async def async_get_transfer_history(history_id: int) -> TransferHistory | None:
+async def async_get_transfer_history(
+    history_id: int,
+) -> TransferHistorySnapshot | None:
     """异步按 ID 读取整理历史 DTO。"""
     return await _service().async_get_transfer_history(history_id)
 
@@ -140,20 +240,20 @@ async def async_get_transfer_history(history_id: int) -> TransferHistory | None:
 __all__ = [
     "DEFAULT_QUERY_PAGE_SIZE",
     "MAX_QUERY_PAGE_SIZE",
-    "DownloadHistory",
     "DownloadHistoryFilter",
+    "DownloadHistorySnapshot",
     "MediaIdentityQuery",
     "QueryPage",
     "QueryPageRequest",
     "QuerySort",
     "QuerySortDirection",
     "QuerySortField",
-    "Subscribe",
-    "SubscribeHistory",
     "SubscriptionFilter",
     "SubscriptionHistoryFilter",
-    "TransferHistory",
+    "SubscriptionHistorySnapshot",
+    "SubscriptionSnapshot",
     "TransferHistoryFilter",
+    "TransferHistorySnapshot",
     "async_get_download_history",
     "async_get_subscription",
     "async_get_subscription_history",