chore: initial project scaffold and gitignore

app/repositories/portfolio_repository.py

@@ -0,0 +1,74 @@
+"""Portfolio repository contract."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from app.domain.models import LedgerEntry, Portfolio, StrategySet
+
+
+class PortfolioRepository(Protocol):
+    def ping(self) -> None: ...
+
+    def get(self, portfolio_id: str) -> Portfolio: ...
+
+    def get_or_create(
+        self,
+        portfolio_id: str,
+        symbol: str,
+        *,
+        broker: str = "kis",
+        status: str = "enabled",
+        strategy_name: str = "",
+        strategy_params: dict | None = None,
+        initial_cash: float = 0.0,
+    ) -> Portfolio: ...
+
+    def create_portfolio(
+        self,
+        portfolio_id: str,
+        *,
+        broker: str,
+        status: str,
+        symbol: str,
+        strategy_name: str,
+        strategy_params: dict,
+        cash_balance: float,
+        asset_quantity: float,
+        asset_price: float,
+        profit_buffer: float,
+    ) -> Portfolio: ...
+
+    def update_portfolio(self, portfolio_id: str, **fields: object) -> Portfolio: ...
+
+    def list_portfolios(self, *, broker: str | None = None, status: str | None = None) -> list[Portfolio]: ...
+
+    def get_or_create_strategy_set(self, strategy_name: str, strategy_config: str) -> StrategySet: ...
+
+    def get_strategy_set(self, id: str) -> StrategySet | None: ...
+
+    def save(
+        self,
+        portfolio: Portfolio,
+        *,
+        current_price: float,
+        action: str,
+        trade_price: float,
+        quantity: float,
+        fee_amount: float,
+        tax_amount: float,
+        total_value_after: float,
+        strategy_set_id: str = "manual",
+        note: str = "",
+    ) -> None: ...
+
+    def list_recent_trades(self, portfolio_id: str, limit: int = 5) -> list[LedgerEntry]: ...
+
+    def reset(self, portfolio_id: str) -> Portfolio: ...
+
+    def adjust_buffer(self, portfolio_id: str, amount: float, action: str, note: str = "") -> Portfolio: ...
+
+    def transfer_buffer(self, portfolio_id: str, amount: float, direction: str, note: str = "") -> Portfolio: ...
+
+    def delete(self, portfolio_id: str, *, clear_ledger: bool = True) -> None: ...
+