refactor: 收口 V3 分层架构与插件兼容边界

app/application/mediaserver.py

@@ -1,11 +1,11 @@
 import re
 from collections.abc import Iterable, Mapping
-from typing import Any, Optional
+from typing import Any, Optional, Protocol
 
 from app.schemas.mediaserver import MediaServerItem as _SchemaMediaServerItem
 from app.domain.context import MusicInfo
 from app.schemas.media import normalize_media_source, resolve_media_identity
-from app.runtime.extensions.service_registry import ServiceBaseHelper
+from app.application.service import ServiceBaseHelper
 from app.schemas.system import MediaServerConf
 from app.schemas.system import ServiceInfo
 from app.schemas.types import (
@@ -16,6 +16,43 @@ from app.schemas.types import (
 )
 
 
+class AsyncMediaServerQueryRepository(Protocol):
+    """媒体服务器本地条目查询所需的异步持久化端口。"""
+
+    async def async_exists(self, **kwargs: Any) -> Any | None:
+        """按标题或统一媒体身份查找已同步条目。"""
+        ...
+
+
+class MediaServerQueryService:
+    """封装媒体服务器本地存在性查询与 ORM 投影。"""
+
+    def __init__(self, repository: AsyncMediaServerQueryRepository):
+        """使用显式媒体服务器查询端口初始化服务。"""
+        self._repository = repository
+
+    async def find_item_id(
+            self,
+            *,
+            title: Optional[str] = None,
+            year: Optional[str] = None,
+            mtype: Optional[str] = None,
+            media_source: Optional[MediaSource] = None,
+            media_id: Optional[str] = None,
+            season: Optional[int] = None,
+    ) -> Optional[str]:
+        """返回匹配条目的服务器 item_id，未命中时返回 None。"""
+        item = await self._repository.async_exists(
+            title=title,
+            year=year,
+            mtype=mtype,
+            media_source=media_source,
+            media_id=media_id,
+            season=season,
+        )
+        return item.item_id if item else None
+
+
 class MediaServerIdentityHelper:
     """将媒体服务器专有 ProviderIds 适配为统一媒体身份。"""