refactor: deepen Deck and Card data-access modules (#51)

* refactor: deepen Deck and Card data-access modules

The DecksRepository / CardsRepository were empty subclasses of
advanced-alchemy's service, so their interface was the entire generic
surface and the query knowledge — filters, eager-load options,
schema→model mapping — leaked into every HTTP handler.

Deepen both modules with a small set of named methods that absorb that
knowledge behind the interface:

- DecksRepository.fetch_with_cards — id filter + selectinload(cards)
- CardsRepository.list_for_deck    — deck_id filter
- CardsRepository.add_cards        — model_dump + deck_id + Card(...) build
- CardsRepository.upsert_cards     — same mapping, upsert semantics

Handlers now name the intent and hand over the request schemas they
already hold. Additive only: advanced-alchemy's generic surface stays
visible so the template still demonstrates the library. Behaviour is
unchanged — fetch_with_cards returns Deck | None and the existing 404
path is byte-for-byte the same.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* update packages

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lesnik512

app/api/decks.py

@@ -3,7 +3,6 @@
 import fastapi
 from advanced_alchemy.exceptions import NotFoundError
 from modern_di_fastapi import FromDI
-from sqlalchemy import orm
 from starlette import status
 
 from app import models, schemas
@@ -26,10 +25,7 @@ async def get_deck(
     deck_id: int,
     decks_repository: DecksRepository = FromDI(DecksRepository),
 ) -> schemas.Deck:
-    instance = await decks_repository.get_one_or_none(
-        models.Deck.id == deck_id,
-        load=[orm.selectinload(models.Deck.cards)],
-    )
+    instance = await decks_repository.fetch_with_cards(deck_id)
     if not instance:
         raise fastapi.HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Deck is not found")
 
@@ -64,7 +60,7 @@ async def list_cards(
     deck_id: int,
     cards_repository: CardsRepository = FromDI(CardsRepository),
 ) -> schemas.Cards:
-    objects = await cards_repository.get_many(models.Card.deck_id == deck_id)
+    objects = await cards_repository.list_for_deck(deck_id)
     return typing.cast("schemas.Cards", {"items": objects})
 
 
@@ -85,9 +81,7 @@ async def create_cards(
     data: list[schemas.CardCreate],
     cards_repository: CardsRepository = FromDI(CardsRepository),
 ) -> schemas.Cards:
-    objects = await cards_repository.create_many(
-        data=[models.Card(**card.model_dump(), deck_id=deck_id) for card in data],
-    )
+    objects = await cards_repository.add_cards(deck_id, data)
     return typing.cast("schemas.Cards", {"items": objects})
 
 
@@ -97,7 +91,5 @@ async def update_cards(
     data: list[schemas.Card],
     cards_repository: CardsRepository = FromDI(CardsRepository),
 ) -> schemas.Cards:
-    objects = await cards_repository.upsert_many(
-        data=[models.Card(**card.model_dump(exclude={"deck_id"}), deck_id=deck_id) for card in data],
-    )
+    objects = await cards_repository.upsert_cards(deck_id, data)
     return typing.cast("schemas.Cards", {"items": objects})

app/repositories.py

@@ -1,7 +1,14 @@
+from typing import TYPE_CHECKING
+
 from advanced_alchemy.repository import SQLAlchemyAsyncRepository
 from advanced_alchemy.service import SQLAlchemyAsyncRepositoryService
+from sqlalchemy import orm
+
+from app import models, schemas
 
-from app import models
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
 
 
 class DecksRepository(SQLAlchemyAsyncRepositoryService[models.Deck]):
@@ -10,9 +17,26 @@ class BaseRepository(SQLAlchemyAsyncRepository[models.Deck]):
 
     repository_type = BaseRepository
 
+    async def fetch_with_cards(self, deck_id: int) -> models.Deck | None:
+        return await self.get_one_or_none(
+            models.Deck.id == deck_id,
+            load=[orm.selectinload(models.Deck.cards)],
+        )
+
 
 class CardsRepository(SQLAlchemyAsyncRepositoryService[models.Card]):
     class BaseRepository(SQLAlchemyAsyncRepository[models.Card]):
         model_type = models.Card
 
     repository_type = BaseRepository
+
+    async def list_for_deck(self, deck_id: int) -> Sequence[models.Card]:
+        return await self.get_many(models.Card.deck_id == deck_id)
+
+    async def add_cards(self, deck_id: int, cards: list[schemas.CardCreate]) -> Sequence[models.Card]:
+        return await self.create_many([models.Card(**card.model_dump(), deck_id=deck_id) for card in cards])
+
+    async def upsert_cards(self, deck_id: int, cards: list[schemas.Card]) -> Sequence[models.Card]:
+        return await self.upsert_many(
+            [models.Card(**card.model_dump(exclude={"deck_id"}), deck_id=deck_id) for card in cards],
+        )