namespace IBKRTrader.Modules.Supervisor.Agent;

/// <summary>
/// Kuratiertes Architektur-/Verhaltensdokument von IBKRTrader – der System-Kontext des Agenten
/// („so entscheidet und handelt die Software"). Bewusst destilliertes Verhalten statt Code-Dump; bei
/// Änderungen am Geld-Pfad mitpflegen. Inline gehalten (versioniert mit dem Code).
/// </summary>
public static class ArchitectureContext
{
    public static string Load() => Text;

    private const string Text =
"""
# IBKRTrader – Architektur & Verhalten (Supervisor-Kontext)

## Grundaufbau
- Harter Core + unabhängige Strategie-Module + Launcher. Module referenzieren nur den Core, nie einander.
- Persistenz: EF Core / MariaDB. Core-Tabellen `core_*`, je Modul eigener Präfix (`ct_`, `acc_`, `sup_`).
- Generic Host; Worker/Services laufen als IHostedService.

## Handels-Pipeline (ExecutionService)
Module übergeben ein `TradeSignal` (Symbol, Side, SourceModule, optional LimitPrice/SuggestedNotional,
SignalId). Der Core prüft in fester Reihenfolge:
1. Globaler Hauptschalter `TradingEnabled` (Default AUS) → sonst Decision=Skipped, Reason=TradingDisabled.
2. Kurs vom Broker → fehlt er, Decision=Skipped, Reason=NoQuote.
3. Konto + bestehende Exposure/Position.
4. Risikoprüfung (RiskService) mit MaxTradePercent, MaxPositionPercentPerModule, MaxSlippagePercent →
   Ablehnung: Decision=Rejected, Reason=RiskRejected (Begründung im Message/ContextJson).
5. Order platzieren (Broker). Erfolg → Decision=Executed, Reason=OrderPlaced; Fehler → Decision=Failed,
   Reason=OrderFailed. Order-Events (Placed/Filled/PlaceFailed) landen in core_order_events.
6. Buchung: Fill → Position/Budget/Trade-Historie; die SignalId wird durchgereicht.

## Sicherer Standard
Broker ist standardmäßig `NullBrokerClient` (handelt nie), bis der echte IBKR-Adapter (TWS API / IB
Gateway) verifiziert ist. Ohne `TradingEnabled=true` wird nie gehandelt.

## Datenfundament für Analyse
- `core_decision_journal`: JEDE Entscheidung (Executed/Rejected/Skipped/Failed) mit ReasonCode, strukturiert.
- `core_order_events`: Order-Lifecycle als Daten.
- `core_trade_history`: gebuchte Fills (BUY/SELL), inkl. SignalId zur Korrelation.
- JSONL-Logs `Logs/{yyyy-MM-dd}.jsonl`: eine Zeile je Event (ts, level, source, cid=SignalId, message).
- Die SignalId verbindet Signal → Entscheidung(en) → Order(s) → Trade → Log-Zeilen (= das Dossier).

## Realisierte GuV / KPIs
Fills werden per FIFO-Lot-Matching (RealizedPnlEngine) zu realisierten Round-Trips; daraus KPIs
(NetPnl, Winrate, ProfitFactor). Long-only-Sicht.

## Module (aktuell)
- CongressTrading (`ct_`): kopiert US-Kongress-Aktien-Trades → TradeSignal.
- Accounting (`acc_`): unabhängiger IBKR-Kontoauszug → append-only Ledger + Abrechnung (KEIN Handel).
- Supervisor (`sup_`): DU – read-only Analyse/Forensik über alle Module.
""";
}