refactor: complete Task 2/3 geo decouple + exceptions centralization; mark as done

backend/app/models/geo.py

@@ -3,8 +3,18 @@
 Response models for the ``GET /api/geo/lookup/{ip}`` endpoint.
 """
 
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
 from pydantic import BaseModel, ConfigDict, Field
 
+if TYPE_CHECKING:
+    import aiohttp
+    import aiosqlite
+
 
 class GeoDetail(BaseModel):
     """Enriched geolocation data for an IP address.
@@ -64,3 +74,26 @@ class IpLookupResponse(BaseModel):
         default=None,
         description="Enriched geographical and network information.",
     )
+
+
+# ---------------------------------------------------------------------------
+# shared service types
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class GeoInfo:
+    """Geo resolution result used throughout backend services."""
+
+    country_code: str | None
+    country_name: str | None
+    asn: str | None
+    org: str | None
+
+
+GeoEnricher = Callable[[str], Awaitable[GeoInfo | None]]
+GeoBatchLookup = Callable[
+    [list[str], "aiohttp.ClientSession", "aiosqlite.Connection | None"],
+    Awaitable[dict[str, GeoInfo]],
+]
+GeoCacheLookup = Callable[[list[str]], tuple[dict[str, GeoInfo], list[str]]]