feat(REQ-005): implement TrEx Basic V1 API contract with auth, assets, ledger, and user endpoints

- Add V1 API routes for assets, ledger, and user info with complete CRUD operations
- Implement authentication scopes and request validation via auth_routes.py
- Extend schemas with V1-specific models for accounts, holdings, and positions
- Add database queries and aggregations for P&L, performance, and account data
- Include comprehensive test coverage for all V1 endpoints and integration flows
- Update batch and release documentation with implementation and verification evidence
- Sync project structure and runtime flows per V1 API contract requirements

Closes implementation phase of BAT-001 (TrEx Basic V1 API Contract)

app/api/v1_ledger.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from decimal import Decimal
+
+from fastapi import APIRouter, Depends, HTTPException, Response, status
 
 from app.core.auth import AuthContext, require_read
 from app.repositories.factory import get_portfolio_repository_from_settings
@@ -20,6 +22,17 @@ def _require_service_token(auth: AuthContext = Depends(require_read)) -> AuthCon
     return auth
 
 
+def _payloads_match(existing, body: LedgerTradeRequest) -> bool:
+    """Return True when the existing trade's payload matches the request body."""
+    return (
+        existing.side == body.side
+        and abs(existing.quantity - float(body.quantity)) < 1e-9
+        and abs(existing.price - float(body.price)) < 1e-9
+        and abs(existing.fee_amount - float(body.fee_amount)) < 1e-9
+        and abs(existing.tax_amount - float(body.tax_amount)) < 1e-9
+    )
+
+
 @router.post(
     "/assets/{asset_id}/ledger/trades",
     response_model=LedgerTradeResponse,
@@ -28,6 +41,7 @@ def _require_service_token(auth: AuthContext = Depends(require_read)) -> AuthCon
 def record_ledger_trade(
     asset_id: str,
     body: LedgerTradeRequest,
+    response: Response,
     auth: AuthContext = Depends(_require_service_token),
 ) -> LedgerTradeResponse:
     from app.core.config import get_settings
@@ -35,6 +49,15 @@ def record_ledger_trade(
     settings = get_settings()
     repo = get_portfolio_repository_from_settings(settings)
     try:
+        # B-9: Validate asset_id (portfolio) existence
+        try:
+            repo.get(asset_id)
+        except Exception:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Asset not found: {asset_id}",
+            )
+
         trade, created = repo.insert_ledger_trade(
             asset_id=asset_id,
             order_id=body.order_id,
@@ -50,6 +73,19 @@ def record_ledger_trade(
         if callable(getattr(type(repo), "close", None)):
             repo.close()
 
+    if not created:
+        # B-8: Check payload conflict → 409
+        if not _payloads_match(trade, body):
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail="Duplicate key with different payload",
+            )
+        # B-7: Same payload duplicate → 200 + status="duplicate"
+        response.status_code = status.HTTP_200_OK
+        trade_status = "duplicate"
+    else:
+        trade_status = "new"
+
     return LedgerTradeResponse(
         ledger_entry_id=trade.ledger_entry_id,
         asset_id=trade.asset_id,
@@ -62,5 +98,5 @@ def record_ledger_trade(
         tax_amount=trade.tax_amount,
         executed_at=trade.executed_at,
         recorded_at=trade.recorded_at,
-        created=created,
+        status=trade_status,
     )