EA_with_Python/docs/MyProject/TradingPanel_spec_ja.md

TradingPanel 仕様書

1. 概要

TradingPanel.mq5 は、指定マジックナンバーの _Symbol ポジションを管理する MQL5 Expert Advisor です。チャート上の操作パネルから主要な SL/TP 設定を変更し、ポジション保有時間、ブレークイーブン、ステップ式トレールストップ、総建値ラインを管理します。

2. 使用インジケータ

• Deviation Band 系の値表示用ハンドルを保持します。
• SuperTrend 関連のストップ管理・表示・コンボボックスは使用しません。

3. パラメータ設定

• exit_time_interval: 時間制限クローズまでの保有時間（時間）。パネル入力値は UpdateInputValues() 内で秒へ変換されます。
• slippage: 許容スリッページ。
• magic_number: 管理対象ポジションを識別するマジックナンバー。
• take_profit_pips: 初期 TP 幅。
• default_sl: 初期 SL 幅。
• stop_offset_pips: SL オフセット。
• enable_breakeven: ManageStops() のブレークイーブン処理を有効化する。
• breakeven_pips: ブレークイーブン判定に使う含み益幅。
• stop_loss_offset_pips: 建値から SL を置くマージン。
• step_trigger_pips: トレール更新を判定する利益ステップ。
• step_move_pips: 1 ステップごとに SL を有利方向へ動かす幅。
• tp_edit_pips: パネルから TP を増減する初期幅。
• range_pips: レンジ判定表示用設定。
• isTradingTimeEnabled, TradeStartHour, TradeStartMin, TradeEndHour, TradeEndMin: 取引時間制限。

4. エントリー/エグジット条件

• CloseTimedPositions() は、timelimit_exit が ON の場合のみ、ポジションの建値時刻に exit_time_interval を加算した時刻へ到達した対象マジックナンバーかつ _Symbol のポジションを成行でクローズします。この監視は取引時間フィルターとは独立して OnTick() と OnTimer() から実行します。
• ApplyInitialStops() は、EA 起動時および取引トランザクション検知時に、対象マジックナンバーかつ _Symbol の既存ポジションを走査し、未設定の SL/TP のみ default_sl / take_profit_pips から補完します。既に設定済みの SL/TP は上書きしません。
• ManageStops(enable_breakeven) は BUY/SELL 両方のポジションを 1 回の呼び出しで走査します。
• enable_breakeven=true の場合、含み益が breakeven_pips 未満の間はトレールへ移行しません。閾値到達後、SL を建値 +/- stop_loss_offset_pips に更新し、その後ステップ式トレールへ移行します。
• enable_breakeven=false の場合、建値移動は行わず、含み益が step_trigger_pips 以上になった時点でステップ式トレールを開始します。
• トレール SL は、含み益のステップ数に応じて建値から step_move_pips 単位で有利方向へ更新します。

5. リスク管理

• すべてのストップ管理および時間制限クローズ対象は _Symbol かつ magic_number が一致するポジションに限定します。
• 初期 SL/TP 補完は、BUY では建値から default_sl pips 下に SL、take_profit_pips pips 上に TP を置き、SELL では建値から default_sl pips 上に SL、take_profit_pips pips 下に TP を置きます。
• SL/TP 更新前に SYMBOL_TRADE_STOPS_LEVEL と SYMBOL_TRADE_FREEZE_LEVEL を確認します。これらのブローカー制約はポイント単位のため、判定には SYMBOL_POINT を使用します。
• CTrade::PositionModify() の戻り値を確認し、失敗時は retcode、GetLastError()、設定予定 SL をログ出力します。
• SL は BUY では上方向、SELL では下方向の改善時のみ更新します。

6. 内部構成

• Experts/MyProject/TradingPanel.mq5: OnInit(), OnDeinit(), OnTimer(), OnTick(), OnChartEvent(), OnTradeTransaction() のイベント入口と取引時間判定を保持します。
• Include/MyLib/Panel/TradingPanelPanel.mqh: CTradingPanelPanel として操作パネル、入力値検証、ボタン状態管理、TP 調整イベントの生成を担当します。
• Include/MyLib/Common/TradingPanelSymbolUtils.mqh: pips 換算と注文執行ポリシー取得の共通関数を提供します。
• Include/MyLib/Trading/TradingPanelTradingManagers.mqh: CTradingPanelStopManager, CTradingPanelPositionManager, CTradingPanelBreakEvenLineManager を定義し、SL/TP 管理、時間制限クローズ、ポジション集計、総建値ライン管理を担当します。

7. 変更履歴

• 2026-05-04: EA 起動時および取引トランザクション検知時に、対象 _Symbol と magic_number が一致する既存ポジションへ未設定の初期 SL/TP を補完する処理を追加。既存 SL/TP は上書きせず、stop/freeze level に近い候補はスキップしてログ出力する仕様を追加。
• 2026-05-03: 可読性・保守性向上のため、EA 本体をイベント入口中心へ整理し、パネル、ストップ管理、ポジション管理、総建値ライン管理、シンボル共通処理を .mqh のクラス/共通関数へ分割。
• 2026-05-03: EA 名を TradingPanel に変更。EA 本体、MyLib 配下の外部 .mqh、仕様書ファイル名と内部参照を TradingPanel 名へ統一。
• 2026-05-03: ManageStops() を ManageStops(bool breakeven_enabled) に変更。ブレークイーブン ON/OFF を引数で切り替え、BE ON 時は breakeven_pips 到達後にステップ式トレールへ移行する仕様へ変更。SuperTrend ベースのストップ管理・表示・コンボボックスを削除し、未使用の check_expand_pips を削除。
• 2026-05-03: order_interval を exit_time_interval に変更し、時間単位の入力へ変更。UpdateInputValues() で秒へ変換し、timelimit_exit ON 時のみ entry_time + exit_time_interval 到達で時間制限クローズする仕様へ変更。
• 2026-05-03: 時間制限クローズを取引時間フィルターから独立させ、OnTimer() でも監視するよう変更。時間制限クローズに _Symbol フィルターを追加。stop/freeze level 判定をポイント単位へ修正し、SL 更新失敗ログを共通化。
• 2026-05-03: 未使用の input、グローバル変数、未使用定数、未使用 DLL import、未使用パネル部品宣言を削除。