本システムは、証券会社のAPIと連携して株式の自動売買を行うものである。「共通設定(strategy.yml)」と「エントリー戦略カタログ(strategies.yml)」を動的に合成し、「戦略割り当て表(all_recommend_*.csv)」に基づいて各銘柄に適用する戦略を決定する。この柔軟な戦略管理機構により、日々の市場状況に応じた迅速な設定変更を可能にする。

リアルタイムトレードのシミュレーション（ドライラン）では、backtrader標準のブローカーが注文を処理し、カスタムAnalyzer (TradePersistenceAnalyzer) が取引イベントを監視して、ポジションの状態をデータベースに永続化する。これにより、実際のAPI連携を実装する前に、ロジックの正当性を安全かつ効率的に検証できる。

graph TD
    subgraph "設定レイヤー"
        A["<b>strategy.yml</b><br>(共通基盤)"]
        B["<b>strategies.yml</b><br>(エントリー戦略カタログ)"]
        C["<b>all_recommend_*.csv</b><br>(戦略割り当て表)"]
    end

    subgraph "実行レイヤー"
        D[メインコントローラー<br><b>run_realtrade.py</b>] -->|"1. 設定ファイルを読み込み<br>2. 戦略を動的に合成"| E{合成済み戦略<br>パラメータ}
        E -->|"3. 戦略パラメータを渡す"| F[Cerebroエンジン]

        subgraph "Cerebroエンジン内部"
            direction TB
            G[DynamicStrategy<br><b>btrader_strategy.py</b>]
            H[永続化アナライザー<br><b>realtrade/analyzer.py</b>]
        end

        F --> G
        F --> H

        G -->|4. 注文発行| I[(標準BackBroker)]
        I -->|5. 取引イベント| H
        H -->|6. ポジション永続化| M[状態管理モジュール<br><b>StateManager</b>]
        
        G -->|データ要求| J[データ取得モジュール<br><b>DataFetcher</b>]
        J -->|価格データ| L((外部データソース<br>API / Mock))

        M <--DB/File--> N[(SQLiteデータベース)]
    end
      
    style D fill:#cce5ff,stroke:#b8daff

sequenceDiagram
    participant Main as run_realtrade.py
    participant Cerebro as Cerebroエンジン
    participant Analyzer as TradePersistenceAnalyzer
    participant Strategy as DynamicStrategy
    
    Main->>Main: 各種設定ファイル (yml, csv) をロード
    Main->>Main: 戦略を動的に合成
    
    Main->>Cerebro: Cerebroエンジンを初期化
    Main->>Cerebro: cerebro.setbroker(標準ブローカー)
    
    Main->>Cerebro: cerebro.addanalyzer(Analyzer, state_manager)
    
    loop 各銘柄
        Main->>Main: 銘柄のデータフィードを取得
        Main->>Cerebro: cerebro.adddata(データフィード)
    end

    Main->>Cerebro: cerebro.addstrategy(Strategy, 合成済みパラメータ)

    Main->>Cerebro: cerebro.run() を実行

• クラス: RealtimeTrader
• 責務:
  • システム全体の起動・停止シーケンスの管理。
  • 設定ファイルの読み込みと戦略の動的合成。
  • backtrader.Cerebroエンジンのセットアップと実行。
  • 標準ブローカー (bt.brokers.BackBroker) をセットアップする。
  • TradePersistenceAnalyzer を StateManager と共にCerebroエンジンに追加する。
• 主要メソッド:
  • _setup_cerebro(): setbrokerで標準ブローカーを設定し、addanalyzerで永続化用アナライザーを追加する。

• クラス: DynamicStrategy
• 責務:
  • run_realtrade.pyから渡された、合成済みの単一の戦略パラメータ (self.p.strategy_params) に基づいて動作する。
  • インジケーターの計算、エントリーおよびエグジット条件の評価を行う。
  • self.buy() / self.sell() を通じて、Cerebroに登録された標準ブローカーに対して注文を発行する。
• 主要メソッド:
  • __init__():
    • 渡されたstrategy_paramsを自身のパラメータとして設定する。
    • exit_conditionsとstop_lossの存在を必須項目として検証する。
  • notify_order(), notify_trade(): 注文や取引の状態変化をログに記録する。（状態永続化の責務は持たない）

• 目的: backtraderの取引イベントを監視し、ポジションの状態をデータベースに永続化することに特化する。 これにより、注文執行ロジックと状態保存ロジックを完全に分離する。
• クラス: TradePersistenceAnalyzer
• 基底クラス: backtrader.Analyzer
• 責務:
  • CerebroからStateManagerのインスタンスを受け取る。
  • 取引イベント（notify_trade）をフックする。
  • 取引がオープンされたら、StateManager.save_position()を呼び出す。
  • 取引がクローズされたら、StateManager.delete_position()を呼び出す。
• 主要メソッド:
  • __init__(): cerebro.addanalyzerから渡されたstate_managerをインスタンス変数として保持する。
  • notify_trade(trade):
    • trade.isopen または trade.isclosed を判定する。
    • 対応するStateManagerのメソッドを呼び出して、データベース操作を実行する。

• 責務: SQLiteデータベースとの接続、テーブルの作成、ポジション情報のCRUD（作成・読み取り・更新・削除）操作を提供する。（変更なし）

バージョン2.0までのカスタムブローカー (BrokerBridge) を利用した設計から、backtraderの標準ブローカーとカスタムアナライザーを組み合わせる設計へと変更した。

• 変更理由:
  1. 関心の分離: 注文執行のシミュレーション（ブローカーの役割）と、その結果の永続化（アナライザーの役割）を明確に分離できる。
  2. backtraderへの準拠: Analyzerは、backtraderが公式にサポートするイベント監視・分析のための仕組みであり、フレームワークの思想に沿った自然な実装となる。
  3. コードの簡素化: get_notificationのような通知キューの管理や、注文状態の複雑なハンドリングをbacktraderの標準ブローカーに任せることができるため、自作コードが大幅に削減され、堅牢性が向上する。

この変更により、将来実際の証券会社APIに接続する際も、このTradePersistenceAnalyzerを再利用または参考にすることで、スムーズな移行が期待できる。