feat(PORT-001A): add collateral entry basis settings

app/models/portfolio.py

@@ -66,14 +66,20 @@ class PortfolioConfig:
     """User portfolio configuration with validation.
 
     Attributes:
-        gold_value: Current gold collateral value in USD
+        gold_value: Collateral baseline value in USD at entry
+        entry_price: Gold entry price per ounce in USD
+        gold_ounces: Canonical gold collateral weight in ounces
+        entry_basis_mode: Preferred settings UI input mode
         loan_amount: Outstanding loan amount in USD
         margin_threshold: LTV threshold for margin call (default 0.75)
         monthly_budget: Approved monthly hedge budget
         ltv_warning: LTV warning level for alerts (default 0.70)
     """
 
-    gold_value: float = 215000.0
+    gold_value: float | None = None
+    entry_price: float | None = 215.0
+    gold_ounces: float | None = None
+    entry_basis_mode: str = "value_price"
     loan_amount: float = 145000.0
     margin_threshold: float = 0.75
     monthly_budget: float = 8000.0
@@ -89,14 +95,57 @@ class PortfolioConfig:
     spot_drawdown: float = 7.5
     email_alerts: bool = False
 
-    def __post_init__(self):
-        """Validate configuration after initialization."""
+    def __post_init__(self) -> None:
+        """Normalize entry basis fields and validate configuration."""
+        self._normalize_entry_basis()
         self.validate()
 
+    def _normalize_entry_basis(self) -> None:
+        """Resolve user input into canonical weight + entry price representation."""
+        if self.entry_basis_mode not in {"value_price", "weight"}:
+            raise ValueError("Entry basis mode must be 'value_price' or 'weight'")
+
+        if self.entry_price is None or self.entry_price <= 0:
+            raise ValueError("Entry price must be positive")
+
+        if self.gold_value is not None and self.gold_value <= 0:
+            raise ValueError("Gold value must be positive")
+        if self.gold_ounces is not None and self.gold_ounces <= 0:
+            raise ValueError("Gold weight must be positive")
+
+        if self.gold_value is None and self.gold_ounces is None:
+            self.gold_value = 215000.0
+            self.gold_ounces = self.gold_value / self.entry_price
+            return
+
+        if self.gold_value is None and self.gold_ounces is not None:
+            self.gold_value = self.gold_ounces * self.entry_price
+            return
+
+        if self.gold_ounces is None and self.gold_value is not None:
+            self.gold_ounces = self.gold_value / self.entry_price
+            return
+
+        assert self.gold_value is not None
+        assert self.gold_ounces is not None
+        derived_gold_value = self.gold_ounces * self.entry_price
+        tolerance = max(0.01, abs(derived_gold_value) * 1e-9)
+        if abs(self.gold_value - derived_gold_value) > tolerance:
+            raise ValueError("Gold value and weight contradict each other")
+        self.gold_value = derived_gold_value
+
     def validate(self) -> None:
         """Validate configuration values."""
+        assert self.gold_value is not None
+        assert self.entry_price is not None
+        assert self.gold_ounces is not None
+
         if self.gold_value <= 0:
             raise ValueError("Gold value must be positive")
+        if self.entry_price <= 0:
+            raise ValueError("Entry price must be positive")
+        if self.gold_ounces <= 0:
+            raise ValueError("Gold weight must be positive")
         if self.loan_amount < 0:
             raise ValueError("Loan amount cannot be negative")
         if self.loan_amount >= self.gold_value:
@@ -111,6 +160,7 @@ class PortfolioConfig:
     @property
     def current_ltv(self) -> float:
         """Calculate current loan-to-value ratio."""
+        assert self.gold_value is not None
         if self.gold_value == 0:
             return 0.0
         return self.loan_amount / self.gold_value
@@ -123,19 +173,27 @@ class PortfolioConfig:
     @property
     def net_equity(self) -> float:
         """Calculate net equity (gold value - loan)."""
+        assert self.gold_value is not None
         return self.gold_value - self.loan_amount
 
     @property
     def margin_call_price(self) -> float:
-        """Calculate gold price at which margin call occurs."""
-        if self.margin_threshold == 0:
+        """Calculate gold price per ounce at which margin call occurs."""
+        assert self.gold_ounces is not None
+        if self.margin_threshold == 0 or self.gold_ounces == 0:
             return float("inf")
-        return self.loan_amount / self.margin_threshold
+        return self.loan_amount / (self.margin_threshold * self.gold_ounces)
 
     def to_dict(self) -> dict[str, Any]:
         """Convert configuration to dictionary."""
+        assert self.gold_value is not None
+        assert self.entry_price is not None
+        assert self.gold_ounces is not None
         return {
             "gold_value": self.gold_value,
+            "entry_price": self.entry_price,
+            "gold_ounces": self.gold_ounces,
+            "entry_basis_mode": self.entry_basis_mode,
             "loan_amount": self.loan_amount,
             "margin_threshold": self.margin_threshold,
             "monthly_budget": self.monthly_budget,
@@ -162,8 +220,7 @@ class PortfolioRepository:
 
     CONFIG_PATH = Path("data/portfolio_config.json")
 
-    def __init__(self):
-        # Ensure data directory exists
+    def __init__(self) -> None:
         self.CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
 
     def save(self, config: PortfolioConfig) -> None:
@@ -190,7 +247,6 @@ class PortfolioRepository:
             return PortfolioConfig()
 
 
-# Singleton repository instance
 _portfolio_repo: PortfolioRepository | None = None