Refactor ban management with domain models and mappers

- Add ban domain model for core business logic separation
- Implement mapper pattern for DTO/domain conversions
- Update ban service with new domain-driven approach
- Refactor router endpoints to use new architecture
- Add comprehensive mapper tests
- Update documentation with architecture changes

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

backend/app/mappers/__init__.py

@@ -0,0 +1,27 @@
+"""Response mappers.
+
+Convert domain models (from services) to response models (for HTTP API).
+
+This is the mapping layer at the router boundary, ensuring the service layer
+remains independent of HTTP response shapes.
+"""
+
+from app.mappers.ban_mappers import (
+    map_domain_active_ban_list_to_response,
+    map_domain_active_ban_to_response,
+    map_domain_ban_trend_to_response,
+    map_domain_bans_by_country_to_response,
+    map_domain_bans_by_jail_to_response,
+    map_domain_dashboard_ban_item_to_response,
+    map_domain_dashboard_ban_list_to_response,
+)
+
+__all__ = [
+    "map_domain_active_ban_to_response",
+    "map_domain_active_ban_list_to_response",
+    "map_domain_dashboard_ban_item_to_response",
+    "map_domain_dashboard_ban_list_to_response",
+    "map_domain_bans_by_country_to_response",
+    "map_domain_ban_trend_to_response",
+    "map_domain_bans_by_jail_to_response",
+]

backend/app/mappers/ban_mappers.py

@@ -0,0 +1,120 @@
+"""Ban response mappers.
+
+Convert domain models (from ban_service) to response models (for HTTP API).
+
+This is the mapping layer at the router boundary, ensuring the service layer
+remains independent of HTTP response shapes.
+"""
+
+from __future__ import annotations
+
+from app.models.ban import (
+    ActiveBan,
+    ActiveBanListResponse,
+    BansByCountryResponse,
+    BansByJailResponse,
+    BanTrendBucket,
+    BanTrendResponse,
+    DashboardBanItem,
+    DashboardBanListResponse,
+    JailBanCount,
+)
+from app.models.ban_domain import (
+    DomainActiveBan,
+    DomainActiveBanList,
+    DomainBansByCountry,
+    DomainBansByJail,
+    DomainBanTrend,
+    DomainDashboardBanItem,
+    DomainDashboardBanList,
+)
+
+
+def map_domain_active_ban_to_response(domain_ban: DomainActiveBan) -> ActiveBan:
+    """Convert a domain active ban to a response model."""
+    return ActiveBan(
+        ip=domain_ban.ip,
+        jail=domain_ban.jail,
+        banned_at=domain_ban.banned_at,
+        expires_at=domain_ban.expires_at,
+        ban_count=domain_ban.ban_count,
+        country=domain_ban.country,
+    )
+
+
+def map_domain_active_ban_list_to_response(
+    domain_list: DomainActiveBanList,
+) -> ActiveBanListResponse:
+    """Convert a domain active ban list to a response model."""
+    return ActiveBanListResponse(
+        bans=[map_domain_active_ban_to_response(ban) for ban in domain_list.bans],
+        total=domain_list.total,
+    )
+
+
+def map_domain_dashboard_ban_item_to_response(
+    domain_item: DomainDashboardBanItem,
+) -> DashboardBanItem:
+    """Convert a domain dashboard ban item to a response model."""
+    return DashboardBanItem(
+        ip=domain_item.ip,
+        jail=domain_item.jail,
+        banned_at=domain_item.banned_at,
+        service=domain_item.service,
+        country_code=domain_item.country_code,
+        country_name=domain_item.country_name,
+        asn=domain_item.asn,
+        org=domain_item.org,
+        ban_count=domain_item.ban_count,
+        origin=domain_item.origin,
+    )
+
+
+def map_domain_dashboard_ban_list_to_response(
+    domain_list: DomainDashboardBanList,
+) -> DashboardBanListResponse:
+    """Convert a domain dashboard ban list to a response model."""
+    return DashboardBanListResponse(
+        items=[
+            map_domain_dashboard_ban_item_to_response(item) for item in domain_list.items
+        ],
+        total=domain_list.total,
+        page=domain_list.page,
+        page_size=domain_list.page_size,
+    )
+
+
+def map_domain_bans_by_country_to_response(
+    domain_data: DomainBansByCountry,
+) -> BansByCountryResponse:
+    """Convert domain bans-by-country data to a response model."""
+    return BansByCountryResponse(
+        countries=domain_data.countries,
+        country_names=domain_data.country_names,
+        bans=[map_domain_dashboard_ban_item_to_response(item) for item in domain_data.items],
+        total=domain_data.total,
+    )
+
+
+def map_domain_ban_trend_to_response(domain_trend: DomainBanTrend) -> BanTrendResponse:
+    """Convert domain ban trend data to a response model."""
+    return BanTrendResponse(
+        buckets=[
+            BanTrendBucket(timestamp=bucket.timestamp, count=bucket.count)
+            for bucket in domain_trend.buckets
+        ],
+        bucket_size=domain_trend.bucket_size,
+    )
+
+
+def map_domain_bans_by_jail_to_response(
+    domain_data: DomainBansByJail,
+) -> BansByJailResponse:
+    """Convert domain bans-by-jail data to a response model."""
+    return BansByJailResponse(
+        jails=[
+            JailBanCount(jail=jail_count.jail, count=jail_count.count)
+            for jail_count in domain_data.jails
+        ],
+        total=domain_data.total,
+    )