CRUD operations for Donors (DEV-39)

backend/app/api/donors.py

@@ -1,23 +1,91 @@
-"""Starter endpoints for the Donors API.
+"""Donors REST API.
 
-This module contains a minimal placeholder to extend and implement.
-Refer to `docs/STARTER_BACKEND_GUIDE.md` for implementation
-examples and guidance on using `AsyncSession`, models, and schemas.
+Full CRUD implementation for the Donors resource.
 """
 
-from fastapi import APIRouter, Response, status
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..config import get_settings
+from ..database import get_db
+from ..schemas import DonorCreate, DonorUpdate, Donor as DonorSchema
+from ..services import donor_service
 
 router = APIRouter()
 
 
-@router.get("")
-async def list_donors():
-    """List donors.
+@router.get("", response_model=list[DonorSchema])
+async def list_donors(db: AsyncSession = Depends(get_db)):
+    """List all donors."""
+    return await donor_service.list_donors(db)
+
+
+@router.post("", response_model=DonorSchema, status_code=status.HTTP_201_CREATED)
+async def create_donor(donor: DonorCreate, db: AsyncSession = Depends(get_db)):
+    """Create a new donor."""
+    try:
+        return await donor_service.create_donor(db, donor)
+    except Exception as e:
+        if get_settings().DEBUG:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=str(e),
+            ) from e
+        raise
+
+
+@router.get("/{donor_id}", response_model=DonorSchema, status_code=status.HTTP_200_OK)
+async def get_donor(donor_id: str, db: AsyncSession = Depends(get_db)):
+    """Get a single donor by ID."""
+    donor = await donor_service.get_donor(db, donor_id)
+    if not donor:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Donor not found",
+        )
+    return donor
+
+
+@router.put("/{donor_id}", response_model=DonorSchema, status_code=status.HTTP_200_OK)
+async def update_donor(
+    donor_id: str, payload: DonorUpdate, db: AsyncSession = Depends(get_db)
+):
+    """Update a donor."""
+    try:
+        donor = await donor_service.update_donor(db, donor_id, payload)
+        if not donor:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Donor not found",
+            )
+        return donor
+    except HTTPException:
+        raise
+    except Exception as e:
+        if get_settings().DEBUG:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=str(e),
+            ) from e
+        raise
+
 
-    Placeholder implementation. See `docs/STARTER_BACKEND_GUIDE.md` (repo root)
-    for details on implementing this handler.
-    """
-    return Response(
-        content="Not implemented — see docs/STARTER_BACKEND_GUIDE.md",
-        status_code=status.HTTP_501_NOT_IMPLEMENTED,
-    )
+@router.delete("/{donor_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_donor(donor_id: str, db: AsyncSession = Depends(get_db)):
+    """Delete a donor."""
+    try:
+        deleted = await donor_service.delete_donor(db, donor_id)
+        if not deleted:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Donor not found",
+            )
+    except HTTPException:
+        raise
+    except Exception as e:
+        if get_settings().DEBUG:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=str(e),
+            ) from e
+        raise

backend/app/services/__init__.py

@@ -0,0 +1,8 @@
+"""Services package.
+
+Business logic layer; API routes depend on services, not the reverse.
+"""
+
+from . import donors as donor_service
+
+__all__ = ["donor_service"]

backend/app/services/donors.py

@@ -0,0 +1,70 @@
+"""Donor services module.
+
+Contains business logic for donor-related operations.
+"""
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from ..models import Donor
+from ..schemas import DonorCreate, DonorUpdate
+
+
+async def list_donors(db: AsyncSession) -> list[Donor]:
+    """List all donors."""
+    result = await db.execute(select(Donor).order_by(Donor.name))
+    return list(result.scalars().all())
+
+
+async def create_donor(db: AsyncSession, donor: DonorCreate) -> Donor:
+    """Create a new donor."""
+    try:
+        db_donor = Donor(**donor.model_dump())
+        db.add(db_donor)
+        await db.commit()
+        await db.refresh(db_donor)
+        return db_donor
+    except Exception:
+        await db.rollback()
+        raise
+
+
+async def get_donor(db: AsyncSession, donor_id: str) -> Donor | None:
+    """Get a single donor by ID."""
+    result = await db.execute(select(Donor).where(Donor.id == donor_id))
+    return result.scalar_one_or_none()
+
+
+async def update_donor(
+    db: AsyncSession, donor_id: str, payload: DonorUpdate
+) -> Donor | None:
+    """Update a donor."""
+    donor = await get_donor(db, donor_id)
+    if not donor:
+        return None
+
+    try:
+        # Only update fields that were actually provided in the request
+        update_data = payload.model_dump(exclude_unset=True)
+        for key, value in update_data.items():
+            setattr(donor, key, value)
+
+        await db.commit()
+        await db.refresh(donor)
+        return donor
+    except Exception:
+        await db.rollback()
+        raise
+
+
+async def delete_donor(db: AsyncSession, donor_id: str) -> bool:
+    """Delete a donor."""
+    donor = await get_donor(db, donor_id)
+    if not donor:
+        return False
+    try:
+        await db.delete(donor)
+        await db.commit()
+        return True
+    except Exception:
+        await db.rollback()
+        raise