feat(V1-API): implement TREX-Basic consumer API contract with encryption and persistence

- Add V1 API endpoints: assets, ledger, user-info
- Implement Fernet-based credential payload encryption (req-010)
- Extend health response schema with runtime info (req-004)
- Add service token runtime ID issuance (req-005)
- Implement database schema migration for V1 API (req-009)
- Add comprehensive test coverage for V1 endpoints
- Update SRS with 10 new requirements (REQ-004 through REQ-011)
- Create batch planning, design, and verification for BAT-001
- Integrate review-discovery StagePilot skill
- Update documentation indices and baseline specs

app/api/v1_ledger.py

@@ -0,0 +1,66 @@
+"""POST /v1/assets/{asset_id}/ledger/trades — idempotent ledger trade recording."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.core.auth import AuthContext, require_read
+from app.repositories.factory import get_portfolio_repository_from_settings
+from app.schemas.v1 import LedgerTradeRequest, LedgerTradeResponse
+
+router = APIRouter(prefix="/v1", tags=["v1"])
+
+
+def _require_service_token(auth: AuthContext = Depends(require_read)) -> AuthContext:
+    if auth.token_source != "db" or auth.token_type != "service":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Service token required",
+        )
+    return auth
+
+
+@router.post(
+    "/assets/{asset_id}/ledger/trades",
+    response_model=LedgerTradeResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+def record_ledger_trade(
+    asset_id: str,
+    body: LedgerTradeRequest,
+    auth: AuthContext = Depends(_require_service_token),
+) -> LedgerTradeResponse:
+    from app.core.config import get_settings
+
+    settings = get_settings()
+    repo = get_portfolio_repository_from_settings(settings)
+    try:
+        trade, created = repo.insert_ledger_trade(
+            asset_id=asset_id,
+            order_id=body.order_id,
+            execution_id=body.execution_id,
+            side=body.side,
+            quantity=float(body.quantity),
+            price=float(body.price),
+            executed_at=body.executed_at,
+            fee_amount=float(body.fee_amount),
+            tax_amount=float(body.tax_amount),
+        )
+    finally:
+        if callable(getattr(type(repo), "close", None)):
+            repo.close()
+
+    return LedgerTradeResponse(
+        ledger_entry_id=trade.ledger_entry_id,
+        asset_id=trade.asset_id,
+        order_id=trade.order_id,
+        execution_id=trade.execution_id,
+        side=trade.side,
+        quantity=trade.quantity,
+        price=trade.price,
+        fee_amount=trade.fee_amount,
+        tax_amount=trade.tax_amount,
+        executed_at=trade.executed_at,
+        recorded_at=trade.recorded_at,
+        created=created,
+    )