refactor(bot): update paper trading models, broker integration, background services, and test project

FinlyticBot/Services/Alpaca/IAlpacaTradingService.cs

@@ -0,0 +1,57 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+using FinlyticCore.Dtos.Bot;
+using FinlyticCore.Dtos.TechnicalAnalysis;
+
+namespace FinlyticBot.Services.Alpaca;
+
+/// <summary>
+/// Outcome of a confirmed Alpaca position liquidation (<see cref="IAlpacaTradingService.ClosePositionAsync"/>).
+/// Only ever constructed after Alpaca's REST API has accepted the liquidation order — see the method's
+/// XML doc for why callers may treat its mere existence as proof the broker confirmed the close.
+/// </summary>
+/// <param name="OrderId">The Alpaca order ID of the liquidation (market) order.</param>
+/// <param name="OrderStatus">The Alpaca order status returned immediately after submission (e.g. "Accepted", "Filled").</param>
+/// <param name="AverageFillPrice">
+/// The average fill price if Alpaca already reports one at submission time; <see langword="null"/> when the
+/// liquidation order has been accepted but not yet filled (e.g. outside market hours). Callers must fall back
+/// to the position's last known synced price in that case rather than treating <see langword="null"/> as zero.
+/// </param>
+public record AlpacaPositionCloseResult(string OrderId, string OrderStatus, decimal? AverageFillPrice);
+
+public interface IAlpacaTradingService
+{
+    bool IsConfigured { get; }
+
+    Task<string> PlaceBracketOrderAsync(
+        string symbol,
+        SignalDirection direction,
+        decimal quantity,
+        decimal entryPrice,
+        decimal stopLossPrice,
+        decimal takeProfitPrice,
+        CancellationToken cancellationToken = default);
+
+    Task UpdateStopLossAsync(
+        string alpacaOrderId,
+        decimal newStopLossPrice,
+        CancellationToken cancellationToken = default);
+
+    Task CancelOrderAsync(
+        string alpacaOrderId,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Liquidates the entire open position for <paramref name="symbol"/> at market price via Alpaca's native
+    /// position-close endpoint. Returns only once Alpaca has ACCEPTED the liquidation order — a caller (e.g.
+    /// the panic-close handler) must only mark the corresponding local position as closed AFTER this call
+    /// returns without throwing, never optimistically before calling it.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Alpaca is not configured/reachable.</exception>
+    Task<AlpacaPositionCloseResult> ClosePositionAsync(
+        string symbol,
+        CancellationToken cancellationToken = default);
+
+    Task<AccountSummaryDto> GetPortfolioSummaryAsync(CancellationToken cancellationToken = default);
+}