R09: Add PaginatedOfficialRecordOut schema and paginated /api/v1/records endpoint

apps/api/app/main.py

@@ -28,7 +28,7 @@ from .logging_config import configure_logging
 from .models import Bait, BaitKind, CatchReport, CommunityImportRun, DataSource, ExternalObservation, Fish, ModerationEvent, ModerationStatus, OfficialRecordImport, SourceType, Spot, SubmissionAttempt, Waterbody
 from .readiness import readiness_report
 from .public_cache import public_cache
-from .schemas import ActivityOut, AdminCatchReportOut, BaitOut, CatchOut, CatchReportAccepted, CatchReportCreate, CatchReportCreated, ExternalAliasSuggestionOut, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, FishOut, ImportRunOut, ImportRunPublicOut, ModerationUpdate, OfficialRecordOut, PaginatedActivityOut, PublicObservationOut, SourceStatusOut, SpotOut, WaterbodyOut
+from .schemas import ActivityOut, AdminCatchReportOut, BaitOut, CatchOut, CatchReportAccepted, CatchReportCreate, CatchReportCreated, ExternalAliasSuggestionOut, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, FishOut, ImportRunOut, ImportRunPublicOut, ModerationUpdate, OfficialRecordOut, PaginatedActivityOut, PaginatedOfficialRecordOut, PublicObservationOut, SourceStatusOut, SpotOut, WaterbodyOut
 from .storage import ScreenshotError, client as storage_client, delete_screenshot, signed_screenshot_url, upload_screenshot
 
 
@@ -274,12 +274,12 @@ def source_status(db: Db) -> list[SourceStatusOut]:
     return result
 
 
-@app.get("/api/v1/records", response_model=list[OfficialRecordOut])
+@app.get("/api/v1/records", response_model=PaginatedOfficialRecordOut)
 def records(
     db: Db, fish: str | None = None, waterbody: str | None = None,
     category: str | None = None, limit: int = Query(50, ge=1, le=100),
     offset: int = Query(0, ge=0),
-) -> list[OfficialRecordOut]:
+) -> PaginatedOfficialRecordOut:
     query = select(CatchReport).options(joinedload(CatchReport.fish), joinedload(CatchReport.waterbody), joinedload(CatchReport.bait)).where(CatchReport.source_type == SourceType.official_record)
     if fish:
         query = query.join(CatchReport.fish).where(Fish.slug == fish)
@@ -287,8 +287,19 @@ def records(
         query = query.join(CatchReport.waterbody).where(Waterbody.slug == waterbody)
     if category:
         query = query.where(CatchReport.raw_payload["category"].as_string() == category)
+    # Count total before pagination
+    total = db.scalar(select(func.count()).select_from(CatchReport).where(CatchReport.source_type == SourceType.official_record)) or 0
+    if fish:
+        total = db.scalar(select(func.count()).select_from(CatchReport).join(CatchReport.fish).where(Fish.slug == fish, CatchReport.source_type == SourceType.official_record)) or 0
+    if waterbody:
+        total = db.scalar(select(func.count()).select_from(CatchReport).join(CatchReport.waterbody).where(Waterbody.slug == waterbody, CatchReport.source_type == SourceType.official_record)) or 0
+    if category:
+        total = db.scalar(select(func.count()).select_from(CatchReport).where(CatchReport.source_type == SourceType.official_record, CatchReport.raw_payload["category"].as_string() == category)) or 0
     items = list(db.scalars(query.order_by(CatchReport.caught_at.desc(), CatchReport.weight_g.desc(), CatchReport.id.desc()).offset(offset).limit(limit)))
-    return [OfficialRecordOut(id=r.id, fish=r.fish.name_ru, weight_g=r.weight_g, waterbody=r.waterbody.name_ru, bait=r.bait.name if r.bait else None, player_name=r.player_name, record_date=r.caught_at, category=(r.raw_payload or {}).get("category"), region=(r.raw_payload or {}).get("region"), source_url=r.source_url) for r in items]
+    return PaginatedOfficialRecordOut(
+        items=[OfficialRecordOut(id=r.id, fish=r.fish.name_ru, weight_g=r.weight_g, waterbody=r.waterbody.name_ru, bait=r.bait.name if r.bait else None, player_name=r.player_name, record_date=r.caught_at, category=(r.raw_payload or {}).get("category"), region=(r.raw_payload or {}).get("region"), source_url=r.source_url) for r in items],
+        total=total, limit=limit, offset=offset,
+    )
 
 
 def _admin(authorization: Annotated[str | None, Header()] = None) -> str:

apps/api/app/schemas.py

@@ -98,6 +98,13 @@ class OfficialRecordOut(BaseModel):
     source_system: str = "rf4-official"
 
 
+class PaginatedOfficialRecordOut(BaseModel):
+    items: list[OfficialRecordOut]
+    total: int
+    limit: int
+    offset: int
+
+
 class PublicObservationOut(BaseModel):
     id: UUID
     source_system: str