refactor: enhance Optuna backtesting framework, optimize orderbook filtering, and update database management utilities.

docs/옵투나.md

@@ -0,0 +1,69 @@
+# Optuna 파라미터 탐색 및 호가 수급 최적화 구조 가이드 (옵투나.md)
+
+이 문서는 백테스트 웹페이지 및 CLI 환경에서 구동되는 **Optuna 파라미터 최적화(Stage 1 & 2) 메커니즘**과, 특히 **호가 수급 필터(Orderbook Filter) 및 수익구간 호가매도(Exit Orderbook) 수치의 탐색·표기·DB 반영 체계**를 설명합니다.
+
+---
+
+## 🚀 1. 투-스테이지(2-Stage) 최적화 작동 원리
+
+백테스트 웹페이지 또는 스크립트에서 Optuna를 돌릴 경우 다음과 같이 2단계로 연쇄 구동됩니다.
+
+```
++---------------------------------------------------------------------------------------------+
+| [Stage 1: 캔들 차트 파라미터 탐색]                                                           |
+| - RSI, 손익비(TP/SL), 풀백, 휩쏘, 이평선 등 주가 차트 지표 최적 수치 탐색                        |
++---------------------------------------------------------------------------------------------+
+                                              │ (Stage 1 완료 즉시 자동 연쇄 기동)
+                                              ▼
++---------------------------------------------------------------------------------------------+
+| [Stage 2: 호가 수급 합의 수치 1,000회 고속 핀셋 탐색] (`optuna_orderbook_recommend.py`)       |
+| - Stage 1의 최우량 진입/청산 타점 데이터를 바탕으로, 진입 전후의 실매 호가 스냅샷을 분석       |
+| - 최적의 호가 스프레드 상한(%), 잔량비 하한, 수익구간 호가매도 마이크로 수치 도출                |
++---------------------------------------------------------------------------------------------+
+```
+
+---
+
+## 🌐 2. 백테스트 웹페이지 연동 및 결과 표기
+
+### ① 웹페이지 Optuna 실행 시 자동 1,000회 탑재
+* 웹 UI(`http://192.168.0.149:5050/`)에서 Optuna 버튼을 작동시키면, 서버 단의 `optuna_mode_combo.py` 모듈이 차트 최적화 종료 시점에 `attach_orderbook_recommend`를 자동으로 호출합니다.
+* 별도의 추가 조작 없이도 호가 1,000회 시뮬레이션이 백그라운드에서 즉각 동반 구동됩니다.
+
+### ② 웹 화면 및 보고서(JSON) 표기 위치
+* 도출된 호가 수급 추천 합의 수치는 웹에서 반환되는 Optuna 결과 딕셔너리(`out_data` 및 `mode_combo`)의 **`"orderbook_recommend"`** 전용 블록에 실려서 화면에 출력됩니다.
+
+```json
+/* 웹 UI 및 optuna_*_tpe_*.json 내 출력 예시 */
+"orderbook_recommend": {
+    "ok": true,
+    "strategy": "MOMENTUM",
+    "params": {
+        "orderbook_filter_enabled": true,
+        "orderbook_max_spread_pct": 0.46,
+        "orderbook_min_bid_ask_ratio": 0.59,
+        "exit_ob_enabled": true,
+        "exit_ob_ratio_min": 1.25,
+        "exit_ob_ma_window": 58
+    }
+}
+```
+
+---
+
+## 🚨 3. 실매매 DB 적용 안전 분리 원칙 (필수 숙지)
+
+Optuna가 찾아낸 수치 중 **차트 파라미터**와 **호가 수급 파라미터**는 실전 DB 각인 방식이 완전히 분리되어 있습니다.
+
+| 구분 | 차트 캔들 파라미터 (RSI, 손익 등) | 호가 수급 파라미터 (스프레드, 호가 익절 등) |
+|------|---------------------------------------|-------------------------------------------|
+| **웹 UI "Apply(적용)" 버튼** | ✅ 버튼 한방으로 DB 환경변수 및 웹 인풋 적용 완료 | ⚪ **미리보기 및 화면 보고서 확인 전용** (차트 수치에 휩쓸려 실수로 DB 덮어씌워짐 방지) |
+| **실매매 DB 최종 갱신 커맨드** | 웹 버튼 또는 `param_search_optuna.py --apply-best` | 🚨 **반드시 전용 독립 스크립트를 가동해야 DB에 안전 새김** |
+
+### 🛠️ 호가 수급 최적 수치 실매매 DB 전용 각인 커맨드
+호가 쪽 Optuna 합의 수치를 실매매 DB에 정기적으로 세팅하거나 갱신할 때는 반드시 아래 스크립트를 가동하여 도장 찍고 적용해야 합니다.
+```bash
+# 특정 전략(MOMENTUM, BREAKOUT, SCALPING, TAIL) 호가 합의 수치 DB 갱신
+.venv/bin/python3 scripts/apply_optuna_ob_consensus.py --strategy MOMENTUM
+```
+* **수행 내용:** 1,000회 고속 최적화 ➔ 합의 수치 도출 ➔ TradeDB 환경변수 세트 안전 패치 ➔ `test_live_execution_validation.py`로 사전 정합성 증명 가동!