feat: suggest confirmed external aliases

apps/api/app/community_review.py

@@ -34,6 +34,20 @@ def map_observation(
     return observation
 
 
+def suggest_aliases(session: Session, observation: ExternalObservation) -> tuple[Fish | None, Waterbody | None]:
+    fish_alias = session.scalar(select(ExternalEntityAlias).where(
+        ExternalEntityAlias.source_system == observation.source_system,
+        ExternalEntityAlias.entity_type == "fish",
+        ExternalEntityAlias.external_id == (observation.fish_external_id or observation.fish_name),
+    ))
+    waterbody_alias = session.scalar(select(ExternalEntityAlias).where(
+        ExternalEntityAlias.source_system == observation.source_system,
+        ExternalEntityAlias.entity_type == "waterbody",
+        ExternalEntityAlias.external_id == (observation.waterbody_external_id or observation.waterbody_name),
+    ))
+    return (fish_alias.fish if fish_alias else None, waterbody_alias.waterbody if waterbody_alias else None)
+
+
 def reject_observation(session: Session, observation: ExternalObservation, *, reason: str) -> ExternalObservation:
     if observation.status == "published":
         raise ExternalReviewError("published observation cannot be rejected")
@@ -109,6 +123,8 @@ def _save_alias(
             external_id=external_id, external_name=observation.fish_name if fish else observation.waterbody_name,
         )
         session.add(alias)
+    elif (fish is not None and alias.fish_id != fish.id) or (waterbody is not None and alias.waterbody_id != waterbody.id):
+        raise ExternalReviewError(f"confirmed {entity_type} alias points to another entity")
     alias.fish = fish
     alias.waterbody = waterbody
     alias.updated_at = datetime.now(timezone.utc)

apps/api/app/main.py

@@ -21,13 +21,13 @@ from sqlalchemy.orm import Session, joinedload
 from .activity import activity_rows
 from .database import get_session
 from .config import settings
-from .community_review import ExternalReviewError, map_observation, publish_observation, reject_observation
+from .community_review import ExternalReviewError, map_observation, publish_observation, reject_observation, suggest_aliases
 from .importer import ImportAlreadyRunning, ImportSourceError, import_records, normalize
 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, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, FishOut, ImportRunOut, ModerationUpdate, OfficialRecordOut, PublicObservationOut, SourceStatusOut, SpotOut, WaterbodyOut
+from .schemas import ActivityOut, AdminCatchReportOut, BaitOut, CatchOut, CatchReportAccepted, CatchReportCreate, CatchReportCreated, ExternalAliasSuggestionOut, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, FishOut, ImportRunOut, ModerationUpdate, OfficialRecordOut, PublicObservationOut, SourceStatusOut, SpotOut, WaterbodyOut
 from .storage import ScreenshotError, client as storage_client, delete_screenshot, signed_screenshot_url, upload_screenshot
 
 
@@ -351,6 +351,20 @@ def admin_external_observations(
     return [_external_out(item) for item in items]
 
 
+@app.get("/api/v1/admin/external-observations/{observation_id}/alias-suggestions", response_model=ExternalAliasSuggestionOut)
+def admin_external_alias_suggestions(
+    observation_id: UUID, db: Db, _: Annotated[str, Depends(_admin)],
+) -> ExternalAliasSuggestionOut:
+    observation = db.get(ExternalObservation, observation_id)
+    if observation is None:
+        raise HTTPException(status_code=404, detail="external observation not found")
+    fish, waterbody = suggest_aliases(db, observation)
+    return ExternalAliasSuggestionOut(
+        fish_slug=fish.slug if fish else None,
+        waterbody_slug=waterbody.slug if waterbody else None,
+    )
+
+
 @app.patch("/api/v1/admin/external-observations/{observation_id}/mapping", response_model=ExternalObservationOut)
 def admin_map_external_observation(
     observation_id: UUID, payload: ExternalObservationMapping, db: Db,

apps/api/app/schemas.py

@@ -213,6 +213,12 @@ class ExternalObservationMapping(BaseModel):
     note: str | None = Field(default=None, max_length=1000)
 
 
+class ExternalAliasSuggestionOut(BaseModel):
+    fish_slug: str | None
+    waterbody_slug: str | None
+    requires_confirmation: bool = True
+
+
 class ExternalObservationDecision(BaseModel):
     reason: str = Field(min_length=1, max_length=1000)