EA_with_Python/docs/MyProject/HITEntryEA_spec_ja.md

# HITEntryEA 仕様書（日本語）

## 1. 概要

`HITEntryEA.mq5` は、H4/H1の外部Python判定とM15確認を使って新規pending注文までを実行する発注専用EAです。約定後ポジションのSL移動、トレーリング、時間決済は行わず、同じマジックナンバーを監視する `HITPositionManagerEA.mq5` に委譲します。

2つのEAは `_Symbol` と `input_entry_magic_number` / `input_managed_magic_number` の一致で連携します。運用口座はhedging口座を前提とし、非hedging口座では初期化に失敗します。

## 2. 使用インジケータ

- 標準・カスタムインジケータは使用しません。
- H4/H1の確定足OHLCをPythonへ渡し、`trend_state.txt`, `target_prices.txt`, `target_zones.txt` を読み込みます。
- M15確認は `CopyRates(_Symbol, PERIOD_M15, OHLC_START_SHIFT, M15_CONFIRM_BARS, rates)` を使用します。

## 3. パラメータ設定

- `lot_size = 0.01`: 通常注文ロット。
- `spread_limit = 60`: 許容スプレッド（point）。
- `input_entry_magic_number = 10001`: 発注EAがpending注文へ付与するマジックナンバー。
- `input_slippage_points = 10`: 注文送信時の許容偏差。
- `input_position_limit = 10`: 同一symbol/magicのpending注文 + ポジション上限。
- `use_split_entry_zone = false`: H1予測ゾーンによる分割エントリーを有効化するか。
- `split_entry_count = 3`: 分割本数。
- `split_lot_mode = SPLIT_LOT_TOTAL`: 総量分割または固定ロット分割。
- `input_cancel_retry_cooldown_seconds = 60`: pending取消失敗後のticket単位再試行間隔。
- `use_m15_entry_filter = true`: M15確定足確認を使うか。
- `input_entry_max_candidate_age_minutes = 120`: H1候補を新規発注に使える最大経過分数。
- `input_tp_multiplier = 1.25`: APIから取得したTP距離を、エントリー価格からの距離ベースで拡大する倍率。`1.0` 未満は `1.0`、`100.0` 超は `100.0` に丸めます。
- `input_min_tp_points = 0`: 拡大後TP距離の最小値（point）。`0` の場合は無効です。
- `input_max_tp_points = 0`: 拡大後TP距離の最大値（point）。`0` の場合は無効です。ただしAPI由来TPより近くなる場合は縮小せず、API距離を維持します。
- `input_range_breakout_guard_enabled = true`: レンジ上抜け/下抜け時に逆方向の逆張りLimit注文を退避し、新規発注も一時停止するか。
- `input_range_breakout_guard_timeframe = PERIOD_M15`: レンジブレイクを監視する時間足。
- `input_range_breakout_lookback_bars = 20`: レンジ高値・安値と平均レンジを計算する確定足本数。
- `input_range_breakout_max_width_multiplier = 6.0`: 平均レンジに対して許容する最大レンジ幅。`0` の場合はレンジ幅フィルタを無効化します。
- `input_range_breakout_buffer_multiplier = 0.20`: 確定ブレイク判定に使う平均レンジ倍率。
- `input_range_breakout_near_multiplier = 0.50`: ブレイク警戒判定に使うレンジ境界への接近幅倍率。
- `input_range_breakout_body_multiplier = 1.50`: ブレイク警戒に必要な直近確定足実体の平均実体倍率。
- `input_range_breakout_cooldown_bars = 4`: ブレイク検知後に逆方向Limitの新規発注を停止する足数。

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

- 新規注文はスプレッド、H4状態、H1候補、M15確認、価格整合、ブローカー距離、ロット制約、同一symbol/magicの上限を満たす場合のみ送信します。
- TPは注文送信前に、APIのTP価格そのものではなく「エントリー価格からAPI TPまでの距離」を `input_tp_multiplier` で拡大して最終TPを計算します。Buy系はエントリーより上、Sell系はエントリーより下へ再配置します。
- 分割エントリーではslotごとのエントリー価格を基準に、各slotの最終TPを個別に計算します。
- pending注文には `input_entry_magic_number` を付与します。
- H4状態と矛盾するpending注文、期限切れpending注文、古い分割pending注文は発注EAが取消します。
- レンジブレイクガードがONの場合、M15監視足で上方向ブレイク警戒/確定を検出すると既存T4 Sell Limitを取消し、T4新規発注をクールダウン終了まで停止します。下方向ブレイクでは既存T2 Buy Limitを取消し、T2新規発注を停止します。
- H1 Python結果の読み込み、候補時刻更新、古い分割pending取消はスプレッド判定より前に実行し、スプレッド超過は新規発注だけを停止します。
- 約定後ポジションのSL変更、時間決済、トレーリングは発注EAでは行いません。

## 5. リスク管理

- 発注上限は口座全体ではなく `_Symbol` と `input_entry_magic_number` が一致するpending注文 + ポジションで判定します。
- Python連携は起動中/完了ファイルとプロセスIDを監視し、二重起動と古い結果の再利用を抑止します。
- doneファイルが存在しても結果ファイルが欠落している場合は、done/running状態を破棄し、次tickで同じ処理を再実行できる状態へ戻します。
- API由来TPの方向がBuy/Sell条件と逆の場合、EAは方向を補正せず既存の価格整合チェックで発注を見送ります。
- レンジブレイクガードは `_Symbol` と `input_entry_magic_number` が一致するpending注文だけを対象にし、上方向ではT4 Sell Limit、下方向ではT2 Buy Limitのみを取消します。
- `OrderSend` の戻り値と `MqlTradeResult.retcode` を確認し、失敗時はエラーまたはretcodeをログに出します。
- hedging口座前提のため、約定後の複数ticket管理は `HITPositionManagerEA.mq5` が担当します。

## 6. 単体テスト

- Strategy Testerでは発注EA単体で、pending注文の作成、期限切れ取消、H4状態不一致取消を確認します。
- 管理EA機能はこのテスト対象に含めません。
- Python連携ファイル名は `_Symbol` と `input_entry_magic_number` を含むprefixで分離し、再現性を保ちます。

## 7. 変更履歴

- 2026-06-14: 非hedging口座での初期化停止を追加。H1結果読み込みをスプレッド判定前へ移動し、doneのみ残るPython不整合時の再実行復旧を追加。発注EA側に残っていた未使用の約定後時間決済経路を削除。
- 2026-06-13: `HIT-EA_refactor_ver6.mq5` と同等のレンジブレイクガードを発注EAへ接続。レンジ上抜け時のT4 Sell Limit退避、レンジ下抜け時のT2 Buy Limit退避、およびクールダウン中の新規発注停止を反映。
- 2026-06-13: API由来TPをエントリー価格からの距離ベースで拡大する `input_tp_multiplier`, `input_min_tp_points`, `input_max_tp_points` を追加し、通常注文と分割slotごとの最終TP計算に反映。
- 2026-06-07: `HIT-EA_refactor_ver6.mq5` から発注責務を分離し、SLTPパネルとポジション管理を `HITPositionManagerEA.mq5` へ移管する仕様を追加。