Refactor services and update documentation

- Refactor ban_service.py with improved error handling
- Refactor blocklist_service.py for better code organization
- Update geo_cache.py with performance improvements
- Update backend development guide and task documentation
- Update runner.csx script

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/app/services/ban_service.py

@@ -15,6 +15,7 @@ import contextlib
 import ipaddress
 from typing import TYPE_CHECKING, cast
 
+import aiohttp
 import structlog
 
 from app.exceptions import JailNotFoundError, JailOperationError
@@ -59,7 +60,8 @@ from app.utils.fail2ban_response import (
 from app.utils.time_utils import since_unix
 
 if TYPE_CHECKING:
-    import aiohttp
+    from collections.abc import Awaitable
+
     import aiosqlite
 
     from app.models.geo import GeoCacheLookup, GeoEnricher, GeoInfo
@@ -302,7 +304,7 @@ async def get_active_bans(
         all_ips: list[str] = [ban.ip for ban in bans]
         try:
             geo_map = await geo_cache.lookup_batch(all_ips, http_session, db=app_db)
-        except Exception:  # noqa: BLE001
+        except (TimeoutError, aiohttp.ClientError, OSError):
             log.warning("active_bans_batch_geo_failed")
             geo_map = {}
         enriched: list[ActiveBan] = []
@@ -420,7 +422,7 @@ async def list_bans(
         page_ips: list[str] = [r.ip for r in rows]
         try:
             geo_map = await geo_cache.lookup_batch(page_ips, http_session, db=app_db)
-        except Exception:  # noqa: BLE001
+        except (TimeoutError, aiohttp.ClientError, OSError):
             log.warning("ban_service_batch_geo_failed_list_bans")
 
     items: list[DashboardBanItem] = []
@@ -460,8 +462,10 @@ async def list_bans(
                     country_name = geo.country_name
                     asn = geo.asn
                     org = geo.org
-            except Exception:  # noqa: BLE001
+            except (TimeoutError, aiohttp.ClientError, OSError):
                 log.warning("ban_service_geo_lookup_failed", ip=ip)
+            except Exception as exc:
+                log.error("ban_service_geo_lookup_unexpected_error", ip=ip, error=type(exc).__name__)
 
         items.append(
             DashboardBanItem(
@@ -624,9 +628,12 @@ async def bans_by_country(
         async def _safe_lookup(ip: str) -> tuple[str, GeoInfo | None]:
             try:
                 return ip, await geo_enricher(ip)
-            except Exception:  # noqa: BLE001
+            except (TimeoutError, aiohttp.ClientError, OSError):
                 log.warning("ban_service_geo_lookup_failed", ip=ip)
                 return ip, None
+            except Exception as exc:
+                log.error("ban_service_geo_lookup_unexpected_error", ip=ip, error=type(exc).__name__)
+                return ip, None
 
         results = await asyncio.gather(*(_safe_lookup(ip) for ip in unique_ips))
         geo_map = {ip: geo for ip, geo in results if geo is not None}