feat: lock concurrent moderation decisions

apps/api/app/main.py

@@ -33,7 +33,7 @@ from .routers.public_data import router as public_data_router
 from .routers.submissions import router as submissions_router
 from .time_utils import aware
 from .public_cache import public_cache
-from .schemas import ActivityOut, AdminCatchReportOut, AdminModerationHistoryOut, CatchReportAccepted, CatchReportCreate, CatchReportCreated, ExternalAliasSuggestionOut, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, ImportRunOut, ModerationUpdate
+from .schemas import ActivityOut, AdminCatchReportOut, AdminModerationHistoryOut, CatchReportAccepted, CatchReportCreate, CatchReportCreated, ExternalAliasSuggestionOut, ExternalObservationAction, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, ImportRunOut, ModerationUpdate
 from .storage import ScreenshotError, client as storage_client, delete_screenshot, signed_screenshot_url, upload_screenshot
 from .submission_security import check_rate_limit
 from .submission_security import is_trusted_proxy as _is_trusted_proxy
@@ -237,6 +237,7 @@ def _external_out(item: ExternalObservation) -> ExternalObservationOut:
         waterbody_slug=item.waterbody.slug if item.waterbody else None,
         catch_report_id=item.catch_report_id, review_note=item.review_note,
         missing_fields=missing_fields, source_payload=allowed_payload,
+        moderation_version=item.moderation_version,
     )
 
 
@@ -312,13 +313,16 @@ def admin_map_external_observation(
     observation_id: UUID, payload: ExternalObservationMapping, db: Db,
     _: Annotated[str, Depends(_admin)],
 ) -> ExternalObservationOut:
-    observation = db.get(ExternalObservation, observation_id)
+    observation = db.scalar(select(ExternalObservation).where(ExternalObservation.id == observation_id).with_for_update())
     fish = db.scalar(select(Fish).where(Fish.slug == payload.fish_slug))
     waterbody = db.scalar(select(Waterbody).where(Waterbody.slug == payload.waterbody_slug))
     if observation is None:
         raise HTTPException(status_code=404, detail="external observation not found")
     if fish is None or waterbody is None:
         raise HTTPException(status_code=422, detail="unknown fish or waterbody")
+    if observation.moderation_version != payload.expected_version:
+        raise HTTPException(status_code=409, detail="observation changed; reload the queue")
+    observation.moderation_version += 1
     try:
         return _external_out(map_observation(db, observation, fish, waterbody, note=payload.note))
     except ExternalReviewError as exc:
@@ -327,11 +331,14 @@ def admin_map_external_observation(
 
 @app.post("/api/v1/admin/external-observations/{observation_id}/publish", response_model=ExternalObservationPublished)
 def admin_publish_external_observation(
-    observation_id: UUID, db: Db, _: Annotated[str, Depends(_admin)],
+    observation_id: UUID, payload: ExternalObservationAction, db: Db, _: Annotated[str, Depends(_admin)],
 ) -> ExternalObservationPublished:
-    observation = db.get(ExternalObservation, observation_id)
+    observation = db.scalar(select(ExternalObservation).where(ExternalObservation.id == observation_id).with_for_update())
     if observation is None:
         raise HTTPException(status_code=404, detail="external observation not found")
+    if observation.moderation_version != payload.expected_version:
+        raise HTTPException(status_code=409, detail="observation changed; reload the queue")
+    observation.moderation_version += 1
     try:
         report = publish_observation(db, observation)
     except ExternalReviewError as exc:
@@ -345,9 +352,12 @@ def admin_reject_external_observation(
     observation_id: UUID, payload: ExternalObservationDecision, db: Db,
     _: Annotated[str, Depends(_admin)],
 ) -> ExternalObservationOut:
-    observation = db.get(ExternalObservation, observation_id)
+    observation = db.scalar(select(ExternalObservation).where(ExternalObservation.id == observation_id).with_for_update())
     if observation is None:
         raise HTTPException(status_code=404, detail="external observation not found")
+    if observation.moderation_version != payload.expected_version:
+        raise HTTPException(status_code=409, detail="observation changed; reload the queue")
+    observation.moderation_version += 1
     try:
         return _external_out(reject_observation(db, observation, reason=payload.reason))
     except ExternalReviewError as exc:
@@ -459,16 +469,19 @@ app.include_router(submissions_router)
 @app.get("/api/v1/admin/catch-reports", response_model=list[AdminCatchReportOut])
 def admin_reports(db: Db, _: Annotated[str, Depends(_admin)], status: ModerationStatus = ModerationStatus.pending, limit: int = Query(50, ge=1, le=100), offset: int = Query(0, ge=0)) -> list[AdminCatchReportOut]:
     reports = list(db.scalars(select(CatchReport).options(joinedload(CatchReport.fish), joinedload(CatchReport.waterbody), joinedload(CatchReport.spot), joinedload(CatchReport.bait)).where(CatchReport.source_type == SourceType.user, CatchReport.moderation_status == status, CatchReport.deleted_at.is_(None)).order_by(CatchReport.reported_at, CatchReport.id).offset(offset).limit(limit)))
-    return [AdminCatchReportOut(id=r.id, fish=r.fish.name_ru, waterbody=r.waterbody.name_ru, coordinates=f"{r.spot.x}:{r.spot.y}" if r.spot else "—", weight_g=r.weight_g, bait=r.bait.name if r.bait else None, player_name=r.player_name, reported_at=r.reported_at, moderation_status=r.moderation_status.value, comment=(r.raw_payload or {}).get("comment"), screenshot_url=signed_screenshot_url(r.screenshot_key) if r.screenshot_key else None) for r in reports]
+    return [AdminCatchReportOut(id=r.id, fish=r.fish.name_ru, waterbody=r.waterbody.name_ru, coordinates=f"{r.spot.x}:{r.spot.y}" if r.spot else "—", weight_g=r.weight_g, bait=r.bait.name if r.bait else None, player_name=r.player_name, reported_at=r.reported_at, moderation_status=r.moderation_status.value, comment=(r.raw_payload or {}).get("comment"), screenshot_url=signed_screenshot_url(r.screenshot_key) if r.screenshot_key else None, moderation_version=r.moderation_version) for r in reports]
 
 
 @app.patch("/api/v1/admin/catch-reports/{report_id}", response_model=CatchReportCreated)
 def moderate_report(report_id: UUID, payload: ModerationUpdate, db: Db, moderator: Annotated[str, Depends(_admin)]) -> CatchReportCreated:
-    report = db.get(CatchReport, report_id)
+    report = db.scalar(select(CatchReport).where(CatchReport.id == report_id).with_for_update())
     if report is None or report.source_type != SourceType.user or report.deleted_at is not None:
         raise HTTPException(status_code=404, detail="catch report not found")
+    if report.moderation_version != payload.expected_version:
+        raise HTTPException(status_code=409, detail="report changed; reload the queue")
     previous = report.moderation_status
     report.moderation_status = ModerationStatus(payload.status)
+    report.moderation_version += 1
     db.add(ModerationEvent(catch_report=report, created_at=datetime.now(timezone.utc), previous_status=previous, new_status=report.moderation_status, moderator=moderator, reason=payload.reason))
     db.commit()
     public_cache.invalidate()
@@ -476,10 +489,12 @@ def moderate_report(report_id: UUID, payload: ModerationUpdate, db: Db, moderato
 
 
 @app.delete("/api/v1/admin/catch-reports/{report_id}", status_code=204, response_class=Response)
-def delete_report(report_id: UUID, db: Db, moderator: Annotated[str, Depends(_admin)]) -> Response:
-    report = db.get(CatchReport, report_id)
+def delete_report(report_id: UUID, db: Db, moderator: Annotated[str, Depends(_admin)], expected_version: int = Query(ge=0)) -> Response:
+    report = db.scalar(select(CatchReport).where(CatchReport.id == report_id).with_for_update())
     if report is None or report.source_type != SourceType.user or report.deleted_at is not None:
         raise HTTPException(status_code=404, detail="catch report not found")
+    if report.moderation_version != expected_version:
+        raise HTTPException(status_code=409, detail="report changed; reload the queue")
     previous = report.moderation_status
     if report.screenshot_key:
         try:
@@ -487,6 +502,7 @@ def delete_report(report_id: UUID, db: Db, moderator: Annotated[str, Depends(_ad
         except Exception as exc:
             raise HTTPException(status_code=502, detail="screenshot deletion failed") from exc
     report.moderation_status = ModerationStatus.rejected
+    report.moderation_version += 1
     report.deleted_at = datetime.now(timezone.utc)
     report.player_name = None
     report.source_url = None