✨ [feat][backend] read_account_balance function

Author: tomy0000000

backend/kayman/crud/account.py

@@ -1,9 +1,12 @@
 from collections.abc import Sequence
+from datetime import datetime
 from decimal import Decimal
 
+from sqlalchemy import func
 from sqlmodel import Integer, Session, cast, select
 
 from kayman.schemas.account import Account, AccountBase, AccountCreate, AccountUpdate
+from kayman.schemas.transaction import Transaction
 
 
 def create_account(session: Session, account: AccountCreate) -> AccountBase:
@@ -17,6 +20,17 @@ def read_account(session: Session, account_id: int) -> Account | None:
     return session.get(Account, account_id)
 
 
+def read_account_balance(
+    session: Session, account_id: int, at: datetime | None = None
+) -> Decimal:
+    scalar = select(func.coalesce(func.sum(Transaction.amount), 0)).where(
+        Transaction.account_id == account_id
+    )
+    if at is not None:
+        scalar = scalar.where(Transaction.created_at < at)
+    return Decimal(session.exec(scalar).one())
+
+
 def read_accounts(
     session: Session, account_ids: list[int] | None = None, for_update: bool = False
 ) -> Sequence[Account]:

backend/kayman/tests/crud/test_account.py

@@ -1,5 +1,6 @@
 import random
 import re
+from datetime import UTC, datetime
 from decimal import Decimal
 from unittest.mock import patch
 
@@ -10,12 +11,13 @@
     _verify_account_ids,
     create_account,
     read_account,
+    read_account_balance,
     read_accounts,
     update_account_balances,
     update_accounts,
 )
 from kayman.schemas.account import Account
-from kayman.tests.factories import AccountFactory
+from kayman.tests.factories import AccountFactory, TransactionFactory
 
 
 def test_create_account(session: Session):
@@ -44,6 +46,90 @@ def test_read_account_not_found(session: Session):
     assert read_account(session, 1) is None
 
 
+def test_read_account_balance_empty_account(session: Session):
+    account = AccountFactory()
+
+    assert read_account_balance(session, account.id) == Decimal(0)
+
+
+def test_read_account_balance_nonexistent_account(session: Session):
+    assert read_account_balance(session, 9999) == Decimal(0)
+
+
+def test_read_account_balance_sums_all_txns_when_at_is_none(session: Session):
+    account = AccountFactory()
+    TransactionFactory(
+        account=account,
+        amount=Decimal("10.50"),
+        created_at=datetime(2026, 1, 5, tzinfo=UTC),
+    )
+    TransactionFactory(
+        account=account,
+        amount=Decimal("-3.25"),
+        created_at=datetime(2026, 2, 1, tzinfo=UTC),
+    )
+    TransactionFactory(
+        account=account,
+        amount=Decimal("7"),
+        created_at=datetime(2026, 3, 1, tzinfo=UTC),
+    )
+
+    assert read_account_balance(session, account.id) == Decimal("14.25")
+
+
+def test_read_account_balance_at_includes_only_txns_before_cutoff(session: Session):
+    account = AccountFactory()
+    TransactionFactory(
+        account=account,
+        amount=Decimal("100"),
+        created_at=datetime(2025, 12, 1, tzinfo=UTC),
+    )
+    TransactionFactory(
+        account=account,
+        amount=Decimal("50"),
+        created_at=datetime(2025, 12, 31, tzinfo=UTC),
+    )
+    TransactionFactory(
+        account=account,
+        amount=Decimal("999"),
+        created_at=datetime(2026, 2, 1, tzinfo=UTC),
+    )
+
+    assert read_account_balance(
+        session, account.id, at=datetime(2026, 1, 1, tzinfo=UTC)
+    ) == Decimal("150")
+
+
+def test_read_account_balance_at_is_exclusive(session: Session):
+    account = AccountFactory()
+    cutoff = datetime(2026, 1, 1, tzinfo=UTC)
+    TransactionFactory(
+        account=account,
+        amount=Decimal("5"),
+        created_at=datetime(2025, 12, 31, tzinfo=UTC),
+    )
+    TransactionFactory(account=account, amount=Decimal("10"), created_at=cutoff)
+
+    assert read_account_balance(session, account.id, at=cutoff) == Decimal("5")
+
+
+def test_read_account_balance_isolates_account(session: Session):
+    account_a = AccountFactory()
+    account_b = AccountFactory()
+    TransactionFactory(
+        account=account_a,
+        amount=Decimal("10"),
+        created_at=datetime(2026, 1, 5, tzinfo=UTC),
+    )
+    TransactionFactory(
+        account=account_b,
+        amount=Decimal("999"),
+        created_at=datetime(2026, 1, 5, tzinfo=UTC),
+    )
+
+    assert read_account_balance(session, account_a.id) == Decimal("10")
+
+
 def test_read_accounts(session: Session):
     accounts = AccountFactory.create_batch(10)
     db_accounts = read_accounts(session)