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/geo_cache.py

@@ -271,8 +271,8 @@ class GeoCache:
             return GeoInfo(country_code=code, country_name=name, asn=None, org=None)
         except geoip2.errors.AddressNotFoundError:
             return None
-        except Exception as exc:  # noqa: BLE001
-            log.warning("geoip_lookup_failed", ip=ip, error=str(exc))
+        except (OSError, geoip2.errors.GeoIP2Error) as exc:
+            log.warning("geoip_lookup_failed", ip=ip, error=type(exc).__name__)
             return None
 
     async def load_cache_from_db(self, db: aiosqlite.Connection) -> None:
@@ -386,8 +386,8 @@ class GeoCache:
                         asn=result.asn,
                         org=result.org,
                     )
-                except Exception as exc:  # noqa: BLE001
-                    log.warning("geo_persist_failed", ip=ip, error=str(exc))
+                except (OSError) as exc:
+                    log.warning("geo_persist_failed", ip=ip, error=type(exc).__name__)
             log.debug("geo_lookup_success_mmdb", ip=ip, country=result.country_code)
             return result
 
@@ -399,8 +399,8 @@ class GeoCache:
             if db is not None:
                 try:
                     await geo_cache_repo.upsert_neg_entry_and_commit(db=db, ip=ip)
-                except Exception as exc:  # noqa: BLE001
-                    log.warning("geo_persist_neg_failed", ip=ip, error=str(exc))
+                except (OSError) as exc:
+                    log.warning("geo_persist_neg_failed", ip=ip, error=type(exc).__name__)
             return GeoInfo(country_code=None, country_name=None, asn=None, org=None)
 
         # HTTP API call (only when allow_http_fallback is True).
@@ -426,8 +426,8 @@ class GeoCache:
                                     asn=result.asn,
                                     org=result.org,
                                 )
-                            except Exception as exc:  # noqa: BLE001
-                                log.warning("geo_persist_failed", ip=ip, error=str(exc))
+                            except (OSError) as exc:
+                                log.warning("geo_persist_failed", ip=ip, error=type(exc).__name__)
                         log.debug("geo_lookup_success_http", ip=ip, country=result.country_code, asn=result.asn)
                         return result
                     log.debug(
@@ -435,7 +435,7 @@ class GeoCache:
                         ip=ip,
                         message=data.get("message", "unknown"),
                     )
-        except Exception as exc:  # noqa: BLE001
+        except (TimeoutError, aiohttp.ClientError, ValueError) as exc:
             log.warning(
                 "geo_lookup_http_request_failed",
                 ip=ip,
@@ -565,11 +565,11 @@ class GeoCache:
         if db is not None and pos_rows:
             try:
                 await geo_cache_repo.bulk_upsert_entries_and_commit(db, pos_rows)
-            except Exception as exc:  # noqa: BLE001
+            except (OSError) as exc:
                 log.warning(
                     "geo_batch_persist_mmdb_failed",
                     count=len(pos_rows),
-                    error=str(exc),
+                    error=type(exc).__name__,
                 )
 
         # FALLBACK: Try HTTP API only if enabled and there are remaining IPs.
@@ -584,11 +584,11 @@ class GeoCache:
             if db is not None and neg_ips:
                 try:
                     await geo_cache_repo.bulk_upsert_neg_entries_and_commit(db, neg_ips)
-                except Exception as exc:  # noqa: BLE001
+                except (OSError) as exc:
                     log.warning(
                         "geo_batch_persist_neg_failed",
                         count=len(neg_ips),
-                        error=str(exc),
+                        error=type(exc).__name__,
                     )
 
             log.info(
@@ -657,12 +657,12 @@ class GeoCache:
                         pos_rows,
                         neg_ips,
                     )
-                except Exception as exc:  # noqa: BLE001
+                except (OSError) as exc:
                     log.warning(
                         "geo_batch_persist_failed",
                         positive_count=len(pos_rows),
                         negative_count=len(neg_ips),
-                        error=str(exc),
+                        error=type(exc).__name__,
                     )
                 pos_rows.clear()
                 neg_ips.clear()
@@ -704,7 +704,7 @@ class GeoCache:
                     log.warning("geo_batch_non_200", status=resp.status, count=len(ips))
                     return fallback
                 data: list[dict[str, object]] = await resp.json(content_type=None)
-        except Exception as exc:  # noqa: BLE001
+        except (TimeoutError, aiohttp.ClientError, ValueError) as exc:
             log.warning(
                 "geo_batch_request_failed",
                 count=len(ips),
@@ -816,8 +816,8 @@ class GeoCache:
 
         try:
             await geo_cache_repo.bulk_upsert_entries_and_commit(db, rows)
-        except Exception as exc:  # noqa: BLE001
-            log.warning("geo_flush_dirty_failed", error=str(exc))
+        except (OSError) as exc:
+            log.warning("geo_flush_dirty_failed", error=type(exc).__name__)
             # Re-add to dirty so they are retried on the next flush cycle.
             self._dirty.update(to_flush)
             return 0