refactor: restructure API pagination metadata for better frontend usability

- Create PaginationMetadata model with computed derived fields (total_pages, has_next_page, has_prev_page)
- Update PaginatedListResponse to embed pagination metadata in a separate 'pagination' object
- Add create_pagination_metadata() factory function in utils/pagination.py for consistent computation
- Update all paginated service functions to use new structure:
  - history_service.list_history()
  - blocklist_service.get_import_logs()
  - jail_service.get_jail_banned_ips()
  - ban_mappers.map_domain_dashboard_ban_list_to_response()
- Update response model docstrings with new structure examples
- Update Backend-Development.md documentation with new pagination patterns
- Update test fixtures to work with new response structure

Response shape changes from:
  {"items": [...], "total": 100, "page": 1, "page_size": 50}
To:
  {"items": [...], "pagination": {"page": 1, "page_size": 50, "total": 100, "total_pages": 2, "has_next_page": true, "has_prev_page": false}}

Benefits:
- Frontend receives all pagination state needed for UI controls
- No need for frontend to calculate total_pages or page navigation logic
- Consolidated pagination metadata reduces field sprawl
- OpenAPI schema automatically reflects changes

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

backend/app/services/blocklist_service.py

@@ -35,6 +35,7 @@ from app.repositories import blocklist_repo, import_log_repo, settings_repo
 from app.services.blocklist_downloader import BlocklistDownloader
 from app.services.blocklist_import_workflow import BlocklistImportWorkflow
 from app.services.blocklist_parser import BlocklistParser
+from app.utils.pagination import create_pagination_metadata
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
@@ -547,9 +548,7 @@ async def list_import_logs(
 
     return ImportLogListResponse(
         items=[ImportLogEntry.model_validate(i) for i in items],
-        total=total,
-        page=page,
-        page_size=page_size,
+        pagination=create_pagination_metadata(total, page, page_size),
     )
 
 

backend/app/services/history_service.py

@@ -35,6 +35,7 @@ from app.repositories import fail2ban_db_repo
 from app.repositories import history_archive_repo as default_history_archive_repo
 from app.utils.constants import DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE
 from app.utils.fail2ban_db_utils import parse_data_json, ts_to_iso
+from app.utils.pagination import create_pagination_metadata
 from app.utils.time_utils import since_unix
 
 log: structlog.stdlib.BoundLogger = structlog.get_logger()
@@ -347,9 +348,7 @@ async def list_history(
 
     return HistoryListResponse(
         items=items,
-        total=total,
-        page=page,
-        page_size=effective_page_size,
+        pagination=create_pagination_metadata(total, page, effective_page_size),
     )
 
 

backend/app/services/jail_service.py

@@ -48,6 +48,7 @@ from app.utils.fail2ban_response import (
     to_dict,
 )
 from app.utils.jail_socket import reload_all
+from app.utils.pagination import create_pagination_metadata
 from app.utils.runtime_state import JailServiceState  # noqa: TC001
 
 if TYPE_CHECKING:
@@ -809,9 +810,7 @@ async def get_jail_banned_ips(
     )
     return JailBannedIpsResponse(
         items=page_bans,
-        total=total,
-        page=page,
-        page_size=page_size,
+        pagination=create_pagination_metadata(total, page, page_size),
     )