feat: Add DART strategy and related configurations

ㅇ Changes: - Introduced the DART strategy to the trading system, including its configuration and integration into the existing framework. - Updated the database schema to include DART-specific tables for disclosures and watchlists. - Enhanced the backtesting and parameter search functionalities to support the DART strategy. - Implemented new rules for browser verification and API interactions to ensure compliance with the updated DART strategy. Impact: - These additions expand the trading capabilities of the system, allowing for more comprehensive analysis and execution of DART-related strategies, while maintaining system integrity and performance.
2026-07-21 07:50:24 +09:00
parent 74db49149f
commit 61bec4bd1d
86 changed files with 4811 additions and 297 deletions
--- a/docs/BREAKOUT_LIVE_BT_QA.md
+++ b/docs/BREAKOUT_LIVE_BT_QA.md
@@ -21,7 +21,7 @@

 ### 동작

- 공통 `resolve_universe_exit_debounce_sec()` → 기본값 = `CONDITION_EXIT_GRACE_SEC`(운영 **120**)
+- 공통 `resolve_universe_exit_debounce_sec()` → 기본값 = `CONDITION_EXIT_GRACE_SEC`(운영 **60**, 기존 120→2026-07-17 축소)
 - 돌파/꼬리/모멘텀 타임라인 `debounce_sec`에 연결
 - 전략별 오버라이드: `BREAKOUT_UNIVERSE_EXIT_DEBOUNCE_SEC` / `TAIL_*` / `MOMENTUM_*` (있으면 우선, `0`=OFF)

@@ -34,7 +34,7 @@
 | 09:11 | 2 |

 - history는 **effective 유니버스 저장** 설계 → 09:07에 1종이면 그 tick의 live effective도 1종으로 보는 게 맞음 (저장이 grace를 빼먹은 버그로 단정하지 않음). 새벽 스냅샷 후 장초 첫 변동·콜드스타트 가능성이 큼.
- 디바운스 ON 시: 09:07 스냅샷에서도 overnight 종목을 **120초** 유지 → 09:11(약 4분 후)에는 신규 스냅샷 기준으로 정리. 실매 EXIT grace와 같은 전환 규칙.
+- 디바운스 ON 시: 09:07 스냅샷에서도 overnight 종목을 **60초** 유지 → 이후 신규 스냅샷 기준으로 정리. 실매 EXIT grace와 같은 전환 규칙.

 ### 영향 범위

@@ -104,7 +104,7 @@

 | 순위 | 항목 | 상태 |
 |------|------|------|
-| 다음 | **2번 검증** — 장초 이노테나·한울: 실매 RAM/틱 vs DB 확정봉 `직전봉약세` 가설 검증 (후보, 미확정) | **다음 순서** |
+| 다음 | **2번 검증** — 장초 이노테나·한울 `직전봉약세` | **근본원인 확정 + 갭보정 진행분 제외 적용** (봇 재시작 시 반영) |
 | 후보 | 1번 A — 마지막 봉 경과 시 포트폴리오 루프에서 **즉시** 슬롯 해제 (전 전략 공통) | 대기 — 저유동은 C로도 분 생성 불가 시 필요 |
 | 진행 | **1번 C — 판 뒤 1회 REST 백필** | **적용** (아래) |
 | — | 3번 슬롯 경쟁 | 패스 |
@@ -118,5 +118,60 @@
 - 로그: `/tmp/backfill_trade_candles_0716c.log` (및 선행 0716b)
 - 한계: 거래 자체가 없는 분(저유동)은 REST에도 없음 → **C만으로는 완전 메꿈 불가**, A 보완 여지

- 웹 돌파 **2026-07-16** 재백테 ↔ 실매 비교는 C 반영 후 / 2번 검증과 병행
+- 웹 돌파 **2026-07-16** 재백테 ↔ 실매 비교는 C 반영 후 / 장초 직전봉 수정과 병행
 - 실매 봇: post-sell 훅 반영하려면 **재시작 필요** (백필 CLI는 봇 없이 완료 가능)
+
+---
+
+## 장초 직전봉 (이노테나·한울) — 2번 검증 결과 (2026-07-17)
+
+### 현상
+
+| | 이노테나 `333050` | 한울 `320000` |
+|--|--|--|
+| 실매 매수 | 09:01:09 @5350 | 09:01:42 @11590 |
+| 실매 로그 `prevChg` | **1.34%** | **0.61%** |
+| BT (DB+웜업) | `탈락-직전봉약세` **0.19%** | `탈락-직전봉약세` **-2.37%** |
+| `PREV_CHG_MIN` | 0.3 (실매=BT 동일) | 동일 |
+
+### 숫자 재현 (스펙: 전전봉 종가 → 직전봉 종가 %)
+
+- 이노테나 09:00: O=5220 C=5290 / 전일 15:30 C=5280  
+  - **전일대비 C2C** `(5290-5280)/5280` = **0.19%** ← BT 탈락  
+  - **당일 몸통** `(5290-5220)/5220` = **1.34%** ← 실매 `prevChg`와 **일치**
+- 한울: 전일 15:58 C=11810 → 09:00 C=11530 → C2C **-2.37%**; 몸통 ≈ **0.70%** ≈ 실매 0.61%(RAM OHLC 미세차)
+
+### 실매 journal 타임라인 (결정적)
+
+1. `09:00:25` 333050 갭보정 REST 빈응답 → `09:00:34` **500봉 RAM 적재** (진행 중 **당일 09:00** 포함)
+2. `09:00:34~09:01:01` 내내 `탈락-직전봉약세 prev=-1.14%`  
+   - `(5220-5280)/5280 = -1.14%` → 갭보정이 넣은 **미완성 09:00(종가≈시가 5220)** 이 확정봉으로 잡힌 상태
+3. `09:01:01` `봉강제확정` 09:00 C=5290
+4. `09:01:02~` `탈락-저항미돌파` (직전봉 게이트 **통과**) → `09:01:06` `BREAKOUT-B ... prevChg=1.34%` 매수
+
+한울도 동일 패턴: 장중 `prev=-2.96%`(갭/전일) → 09:00 확정 후 저항 대기 → `prevChg=0.61%`로 매수.
+
+### 근본원인
+
+**갭보정(REST ka10080)이 장중에 “아직 진행 중인 당일 1분봉”을 `is_confirmed`로 RAM에 넣음.**
+
+- 실매 `check_buy` = `get_candles`(확정) + `get_current_candle`(진행) → **같은 09:00이 확정·진행 양쪽에** 있거나, 확정 체인이 **전일 종가 대신 시가(불완전봉 종가)** 를 `prev_prev`로 물음.
+- 그 결과 직전봉 필터가 문서/코드 스펙(전전봉→직전봉 **종가대비**)이 아니라 **당일 첫 봉 몸통%** 에 가깝게 통과.
+- BT는 DB 확정봉(+웜업 전일 종가)만 쓰므로 **0.19%/-2.37%로 올바르게 거름** → 장초 실매만 사는 괴리.
+
+코드 위치: `kis_ws.merge_confirmed_bars` / `fill_gap_from_rest` (현재 분 제외 없음) + `breakout.check_buy` (`virtual = confirmed + forming`).
+
+### 수정 방향 (승인 후 — 아직 미적용)
+
+1. **갭보정 시 `candle_time >= 현재 진행 분` 봉은 confirmed merge 제외** (또는 `_current`만 갱신). 실매·BT 모두 전일 종가 C2C로 통일.
+2. (선택) 매수 성공 로그에 `confirmed[-2/-1] candle_time/close` 남겨 재발 추적.
+3. 스펙을 “직전봉 몸통%”로 바꾸려면 실매·웹·Optuna를 **한 세트**로 바꿔야 함 — 비권장(HTS/주석과 불일치).
+
+**권장: 1번(진행분 REST 제외).** 핵심 매매 임계값 변경이 아니라 인프라 정합.
+
+### 수정 적용 (2026-07-17)
+
+- env: `WS_GAP_FILL_SKIP_INCOMPLETE_BUCKET` (기본 **true**, DB 시드)
+- `fill_gap_from_rest` / `merge_confirmed_bars`: 진행 중 버킷(`>=` 현재 봉시작) **insert 금지 + RAM purge**
+- 스모크: `scripts/smoke_candle_upsert_rollup.py` (진행분 skip/purge)
+- **실매 반영: `kis_trader_main` 재시작 필요** (미재시작 시 기존 프로세스 구코드)
--- a/docs/계정.md
+++ b/docs/계정.md
@@ -0,0 +1,182 @@
+# 계정 · 슬롯 · 스케일업
+
+> **대화 정리 (2026-07-19)** — 시드/복리 가정, 슬롯 한도, 전략별 자본 격리, **계정 2개 운용** 시 슬리피지·용도 분리.  
+> 세금·수수료·슬리피지는 표에 미반영(순수익 가정이면 Gross는 더 높게 잡아야 함).
+
+관련: [정합성.md](./정합성.md)
+
+---
+
+## 0. 한 줄 결론
+
+| 주제 | 결론 |
+|------|------|
+| 같은 로직·같은 종목·계정 2개 동시 매수 | 시장엔 **슬롯×2 한 방**과 같음 → 중소형주 **슬리피지·자가당착** |
+| 슬롯 올리기 (1천~20만 원대) | **30만 → 60만은 먼지**, 안전 상한 대략 **슬롯당 ~300만** |
+| 시드 더 키울 때 | 계정 복제보다 **20만~100만 원대 전용 전략**으로 유동성 확보 |
+| 비율 슬롯 | **전략 ON 개수로 N빵/뻥튀기 금지**. 슬롯% + **전략별 격벽(Cap)** |
+| 복리 표 | `총수익 = P × ((1+r)^n − 1)`, 두 시드 차이 = `(P2−P1) × ((1+r)^n − 1)` |
+
+---
+
+## 1. 계정 두개 — 용도 (왜 나누나)
+
+대화에서 말한 **봇/계정 2대** 목적 정리. “같은 전략을 두 배로 긁기”가 목적이면 **비추천**.
+
+| 구분 | 용도 예시 | 비고 |
+|------|-----------|------|
+| **A 계정 (운영)** | 실매 메인. 4전략, 슬롯 Hard-Cap 준수 | IP·앱키·WS 구독(41) 한도 본진 |
+| **B 계정 (고액·테스트·분리)** | 파라미터 실험 / 대형주 전용 / 고액 시드 격리 | **가능하면 VM·IP·앱키 분리** (같은 집 동시 → 차단·레이트리밋 위험) |
+| 하지 말 것 | 동일 타점·동일 종목에 A·B가 거의 동시 시장가 | 호가 = **합산 체결**. 후행 계정이 1~2틱 불리 |
+
+**인프라 메모**
+
+- WS 구독·REST 초당한도·429는 **계정 수만큼** 부담이 늘 수 있음 (공유 IP면 더 위험).
+- HTS 접속 OK ≠ OpenAPI 건강. 모의/실전 도메인·토큰 분리 유지.
+- 스케일업 정석: **자본 통합 + 슬롯 Cap** 또는 **유동성 다른 유니버스(대형주) 전략 추가**.
+
+---
+
+## 2. 복리 계산식 (임의 원금 대입용)
+
+거래일 `n` (주식 1년 ≈ **250**), 일 수익률 `r`.
+
+```
+잔고      = P × (1+r)^n
+총수익금  = P × ((1+r)^n − 1)
+시드 차이 = (P2 − P1) × ((1+r)^n − 1)
+```
+
+### 2.1 참고 승수 (매일 동일 r 가정)
+
+| 일 수익률 r | 20거래일 (월) | 250거래일 (년) | 대략 연 누적 수익률 |
+|-------------|---------------|----------------|---------------------|
+| 1.0% (0.01) | ×1.220 → **+22.0%** | ×12.03 → **+~1103%** | 대회급·비현실 고정 |
+| 0.2% (0.002) | — | ×1.647 → **+~64.7%** | 보수 목표 가정 |
+| 0.4% (0.004) | — | ×2.714 → **+~171.4%** | 전략 Gross 가정이면 순은 더 낮음 |
+
+**단리 vs 복리:** 단리면 0.2%→50%, 0.4%→100%(정확히 2배). 복리면 **0.4%가 0.2%의 2배가 아니라 ~171%**로 벌어짐.  
+**고정 슬롯 금액(예: 항상 100만)** = 실질 **단리**. 표의 복리 숫자는 **잔고 비율로 슬롯이 커질 때**만 해당.
+
+---
+
+## 3. 시드별 1년 표 (참고)
+
+### 3.1 일 0.2% · 250일
+
+| 시작 원금 | 1년 뒤 잔고 | 누적 총수익 |
+|-----------|-------------|-------------|
+| 100만 | ~164.7만 | ~64.7만 |
+| 200만 | ~329.4만 | ~129.4만 |
+| 500만 | ~823.4만 | ~323.4만 |
+| 1,000만 | ~1,646.8만 | ~646.8만 |
+
+### 3.2 일 0.4% · 250일 (슬롯 100만 가정 시 “풀가동 복리” 예시)
+
+| 운용 기준 | 시작 | 1년 뒤 | 누적 수익 |
+|-----------|------|--------|-----------|
+| 슬롯 1개 | 100만 | ~271.4만 | ~171.4만 |
+| 전략 1 · 동시 5슬롯 | 500만 | ~1,356.9만 | ~856.9만 |
+| 4전략 · 총 20슬롯 | 2,000만 | ~5,427.5만 | ~3,427.5만 |
+
+> **주의:** “전략당 0.4%” ≠ 계좌 일 0.4% 자동. 동시 슬롯·현금비중·손절·수수료에 따라 계좌 일 수익률은 훨씬 작아질 수 있음.  
+> 월 20%·일 1% 고정은 **소액·무제약 대회 상위** 스케일 이야기지, 기관·버핏 체급 비교용이 아님.
+
+---
+
+## 4. 슬롯 · 주가대 · 시장 충격
+
+운영 유니버스: **주가 1,000원 ~ 200,000원**, 현재 슬롯 **~30만**(60만도 스텔스).
+
+| 주가대 | 슬롯 60만 체감 | 슬리피지 없이 대략 상한(정상 유동성) |
+|--------|----------------|--------------------------------------|
+| 1천~5천 | 120~600주 | **~300만~500만** |
+| 1만~5만 | 소수 십주 | **~500만~1,000만** |
+| 5만~20만 | 소수 주 | 더 넉넉 (단, **틱% 왜곡** 주의) |
+
+**실무 합의:** 이 유니버스에서 **슬롯 Hard-Cap ≈ 300만**. 그 이상은 1호가 소진·부분체결 위험.
+
+### 4.1 20만 ~ 100만 원대 (대형·대장 전용으로 추가할 때)
+
+| 주가대 | 틱 | 대략 슬롯 상한(참고) |
+|--------|----|----------------------|
+| 20만~50만 미만 | 500원 | **~3,000만~5,000만** |
+| 50만~100만 미만 | 1,000원 | **~5,000만~1억** |
+
+함정: 유동성은 크지만 **0.4% 파동 빈도↓**, 틱당 %가 커서 손절/익절 틱 수가 달라짐 → **중소형 파라미터 복붙 금지**, 타임프레임·돌파 가중치 튜닝 필요.
+
+---
+
+## 5. 전략당 한도 (후보 20개 ≠ 20슬롯 매수)
+
+후보 실시간 20개여도 **동시 보유 상한**으로 자본을 잡음.
+
+| 동시 보유 | 슬롯 300만 기준 전략당 한도 | 4전략 총시드(참고) |
+|-----------|------------------------------|---------------------|
+| 3 | 900만 | 3,600만 |
+| **5 (권장)** | **1,500만** | **6,000만** |
+| 10 | 3,000만 | 1.2억 |
+| 20 무제한 | 6,000만 | 2.4억 — 현금잠김·429·동조 손절 위험 |
+
+동시 타점 다수 → **상위 N개만 큐 정렬 후 매수**(점수·수급·호가잔량 등). 전량 매수 금지.
+
+---
+
+## 6. 비율 슬롯 · 전략별 격리 (질문 답)
+
+### 6.1 “켜진 전략 수에 따라 슬롯이 4배/2배?”
+
+**아니요.** ON 전략이 1개라고 남은 3전략 몫을 몰아주면 **집중 리스크** (한 번 손절이 계좌에 증폭).  
+시장이 조용해서 3전략이 쉬는 날 = 오히려 보수적으로 현금 유지하는 쪽이 맞음.
+
+### 6.2 추천 구조 (이중 잠금)
+
+| 단계 | 무엇 | 예시 (총자본 2,000만) |
+|------|------|------------------------|
+| 1 | **1슬롯** = `min(총잔고 × 고정%, Cap)` | 5% → 100만, Cap 300만 |
+| 2 | **전략별 Cap** | 총자본의 25% → 전략당 최대 500만(≈5슬롯) |
+| 3 | (선택) **계좌 최소 현금** | 예: 20% 락 |
+
+→ “이 전략 더 쓰고 저 전략 덜 쓰기” = **시장이 아니라 전략 Cap 안에서만** 허용.  
+→ 유연한 오버플로우(유휴 자본 일부 대출)는 **나중에**. 당장은 **독립 비율 + Hard-Cap + 전략 격벽**이면 충분.
+
+### 6.3 의사코드
+
+```text
+slot = min(int(total_balance * SLOT_PCT), SLOT_MAX_CAP)   # 예: 5%, 300만
+if strategy_invested + slot > total_balance * STRATEGY_CAP_PCT:  # 예: 25%
+    reject buy
+else:
+    allow buy
+```
+
+---
+
+## 7. 계정 2개 × 슬롯 300만 = 600만?
+
+| 질문 | 답 |
+|------|----|
+| 시차 있으면 괜찮은가? | **짧은 시차면 더 나쁨** — 선주문 소진 → 후주문이 2호가 |
+| 언제 괜찮은가? | **종목·시간·전략이 겹치지 않을 때**, 또는 호가가 수억인 대형주 |
+| 대안 | 한 계정 Cap 유지 / **20만+ 전용 전략**으로 용량 확장 |
+
+IOC/FOK·부분체결 시 잔량 취소 여부는 실매 주문 모듈에 명시해 둘 것.
+
+---
+
+## 8. 체크리스트 (스케일업 전)
+
+- [ ] 슬롯 `min(잔고×%, Cap)` — Cap은 유니버스별(중소형 ~300만 / 대형 별도)
+- [ ] 전략별 투자금 Cap (N빵 금지)
+- [ ] 동시 보유 상한 ≤ 후보 수
+- [ ] 계정 2대면 **용도 분리** 문서화 (운영 vs 테스트/대형) — 동일 타점 동시 금지
+- [ ] VM·앱키·IP 분리 여부 / 429·WS 41 한도 점검
+- [ ] “일 0.4%”가 **슬롯 Gross**인지 **계좌 순**인지 구분해서 기록
+
+---
+
+## 9. 변경 이력
+
+| 날짜 | 내용 |
+|------|------|
+| 2026-07-19 | 대화(시드·0.2/0.4% 복리·슬롯300·전략격벽·계정2·대형주) → 본 MD 최초 정리 |
--- a/docs/정합성.md
+++ b/docs/정합성.md
@@ -0,0 +1,176 @@
+# 정합성
+
+> **최종안 (2026-07-17)** — 실매 · 웹백테 · Optuna가 **같은 분봉(OHLCV) 진실**을 쓰게 하는 규칙.  
+> 신호/진입 바 오프셋(±1) 땜빵은 **금지**. 봉이 확정 후에도 커지는 것이 근본 원인이다.
+
+관련: [CANDLE_FLOW.md](./CANDLE_FLOW.md) · [SCALP_BACKTEST_VS_LIVE.md](./SCALP_BACKTEST_VS_LIVE.md) · [BACKTEST_ALIGNMENT_FINAL.md](./BACKTEST_ALIGNMENT_FINAL.md)
+
+---
+
+## 0. 한 줄 원칙
+
+```
+실매가 확정한 1분봉(그 순간의 OHLCV) = DB에 동결 = 웹백테/Optuna가 읽는 봉
+```
+
+- **틱** = 체결가(진입/청산 슬리피지)
+- **분봉** = 매수 여부(RSI·거래량배수·평균 등)
+- **EOD** = 포지션 장마감 청산(≈15:25). **봉 동결이 아님.**
+
+### 0.1 누가 무엇을 읽나 (오해 방지)
+
+| 곳 | 읽는 것 | 아님 |
+|----|---------|------|
+| **실매(장중)** | WS로 막 확정된 봉 → RAM + DB에 **첫 INSERT** | — |
+| **웹백테 · 파람/Optuna** | DB **`ws_candles`(+`ws_ticks`)** 과거 재생 | Optuna가 **실시간 WS에 붙지 않음** |
+| **아침 기동** | 같은 DB 로드 + 없는 분만 INSERT | “새벽 INSERT만 보는” 전용 분기 **없음** |
+
+대화에서 쓰인 “실매가 확정한 **실시간** 분봉” = **장중 확정 순간의 숫자**를 뜻함.  
+→ 파람을 실시간 피드로 바꾸라는 뜻이 **아님**.  
+→ 고칠 코드 = **존재 시 UPDATE 금지**뿐. 파람/아침용 봉 소스를 둘로 나누지 않음.
+
+---
+
+## 1. 잠긴 매매 규칙 (변경 금지)
+
+| 항목 | 규칙 |
+|------|------|
+| 신호 봉 | **T−1 확정봉** (`live_backtest_align=True`) |
+| 진입 봉 | **T 확정봉** |
+| 유니버스 | 초 단위 `event_time` — 분 슬롯 ±1 해킹 금지 |
+| HTS | SCAN 후보 참고. `*_SKIP_HTS_SCAN_DUPES` 기본 **false** 유지 |
+| 차트봉 | 매매·백테·Optuna 경로에 사용하지 않음 (`ws_candles` + `ws_ticks`) |
+
+---
+
+## 2. 근본 원인 (측정, 2026-07-16)
+
+| 현상 | 수치/관찰 | 의미 |
+|------|-----------|------|
+| 장중 확정 후 재기록 | 봉 마감 +5분 이후 `updated_at` ≈ **76%** | 갭보정 REST가 기존 봉 **UPDATE**(큰 volume 우선) |
+| 새벽/매도 후 백필 | 다음날 `updated_at` ≈ **3.8%** (00:48대), 매도 종목과 100% 겹침 | `POST_SELL_CANDLE_BACKFILL`이 hold 구간 UPSERT |
+| 갭 구멍 INSERT | ENTER 시 결측분 흔함 | 웜업용 — **INSERT는 유지**, 덮어쓰기만 문제 |
+| 샘표류(007540) | 실매 vol_avg≈1328 vs DB≈634 | 같은 공식, **lookback 시리즈가 다름** |
+
+**정합을 깨는 본체 = 확정 후 UPDATE.** INSERT(구멍 메우기)가 아니다.
+
+---
+
+## 3. 최종 설계: Freeze-on-confirm
+
+### 3.1 규칙
+
+1. **행이 이미 있으면 OHLCV·RSI 덮어쓰기 금지** (RAM `merge_confirmed_bars` + DB upsert + 매도/보유 백필 동일).
+2. **없을 때만 INSERT** — 갭 구멍·웜업 유지.
+3. 진행 중(미확정) 버킷은 기존처럼 confirmed에 넣지 않음 (`WS_GAP_FILL_SKIP_INCOMPLETE_BUCKET`).
+4. (옵션, 후속) 거래량을 틱 합으로 통일 — 1번 안정화 후.
+
+### 3.2 수정 대상 (구현 시)
+
+| 경로 | 현재 | 목표 |
+|------|------|------|
+| `kis_ws.merge_confirmed_bars` | 기존 봉 + `new_vol > old_vol` → upsert | **존재 시 skip** |
+| `kis_ws` DB batch / `_flush_batch` | `ON DUPLICATE KEY UPDATE` volume 등 덮음 | **존재 시 no-op** (또는 INSERT IGNORE / 조건부) |
+| `post_sell_candle_backfill` `_INSERT_SQL` | `volume=IF(VALUES>volume…)` | **존재 시 skip**, 없는 분만 INSERT |
+| 기타 REST/키움 갭보정 → merge | 위 merge 경유 | merge 규칙만 바꿔도 대부분 흡수 |
+
+### 3.3 하지 않을 것
+
+- 09:05 시작·새벽 수집 전면 중지만으로 “해결” 선언 (보조책은 가능, 본체 아님)
+- 신호/유니버스 ±1분 보정
+- “EOD 했으니 당일 봉만 보면 된다” (EOD≠봉동결; lookback·전일시가 필요)
+- 매수 직전 REST 재조회로 “안정화 체크”를 본치료로 쓰기 (느림·429·나중에 또 덮이면 무의미)
+
+### 3.4 운영 보조 (선택, 본치료 아님)
+
+| 아이디어 | 기대 | 한계 |
+|----------|------|------|
+| 09:05 기동 (조건식·봉 정리 후) | 장초 혼선 ↓ | 장중 UPDATE·새벽 백필 미해결 |
+| 새벽/장전 **덮어쓰기** 금지 | freeze와 동일 방향 | 수집 자체 금지가 아니라 INSERT only |
+| 실시간 “봉 안정” 폴링 | 체감용 | freeze 없으면 DB는 결국 갈라짐 |
+
+---
+
+## 4. 구현 순서 (승인 후)
+
+1. **존재 시 덮어쓰기 금지**  
+   `merge_confirmed_bars` / DB upsert / 백필 — 공통 규칙.
+2. **스모크**  
+   확정 직후 volume vs 1시간 뒤 · 다음날 — **동일**해야 함.
+3. **7/16 샘표류 대조**  
+   vol 평균·PASS/FAIL이 실매 저널과 같은지 (웹백테 동일 파라미터).
+
+코드 변경 전: 핵심 매매 로직이 아닌 **저장/병합 계층** 패치.  
+시그널 T−1/T·청산식은 이 작업에서 건드리지 않음.
+
+---
+
+## 5. 검증 체크리스트
+
+- [ ] 확정 봉 DB row: 이후 REST/백필이 volume을 키우지 않음
+- [ ] 결측 분은 여전히 INSERT로 채워짐 (웜업 0건 폭주 없음)
+- [ ] 재시작 후 RAM 재로드 → 확정분과 DB 일치
+- [ ] 갭보정 로그: `update=` 가 0에 수렴(또는 skip 카운트), `insert=` 만 정상
+- [ ] 전략 2개 이상 경로 스모크 (예: SCALP + TAIL) — 공유 `ws_candles` 부작용 없음
+- [ ] 웹백테 / Optuna: 동일 `ws_candles` → 실매 저널과 PASS·지표 근접
+- [ ] `POST_SELL_CANDLE_BACKFILL` 켠 상태에서도 hold 구간 **구멍만** 채움
+
+---
+
+## 6. 영향 범위 분류
+
+| 구분 | 영향 |
+|------|------|
+| **실매** | RAM/DB에 남는 확정봉이 “첫 확정값”으로 고정 → 이후 매수 판정 입력 안정 |
+| **웹백테·Optuna** | 같은 DB를 읽으므로 실매와 입력 정렬 (엔진식 변경 없음) |
+| **과거 DB** | 이미 덮여 커진 봉은 자동 복구 안 됨. 필요 시 해당일 재수집·재백테는 별도 |
+
+---
+
+## 7. 승인 상태
+
+| 항목 | 상태 |
+|------|------|
+| 방향: freeze-on-confirm / INSERT only | **사용자 승인·구현 진행 (2026-07-17)** |
+| env | `WS_CANDLE_FREEZE_ON_CONFIRM` 기본 **true** (false=레거시 덮어쓰기) |
+| 구현 | `kis_ws` merge/confirm/DB flush · DB시드 · `post_sell_candle_backfill` · `fill_kiwoom_candles` |
+| 재시작 | `db_seed=N` 로그 = DB 확정봉을 RAM에 시드 (REST로 안 덮음) |
+
+첫 패치: **존재 시 UPDATE 금지** (확정행 OHLCV 동결). 미확정→확정 갱신은 허용.  
+재시작 시 RAM이 비면 REST가 “첫 삽입”처럼 보이므로, **DB에 이미 있으면 DB값으로만 RAM 시드**.
+
+---
+
+## 8. 다음에 할 일 (쉬운 말 · 우선순위)
+
+> 코드(freeze)는 이미 켜져 있다. 아래는 **새 기능이 아니라 “잘 됐는지 확인”** 순서다.
+
+### 1순위 — 깨끗한 장일 하루만 검증
+
+**말:** 봉이 끝난 직후 적힌 거래량(volume)이, 한 시간 뒤·다음날에도 **그대로**여야 한다.  
+중간에 REST·갭보정·매도백필이 숫자를 키우면 실패.
+
+**보는 법:**
+- 확정 직후 volume vs 1시간 뒤 · 다음날 → **같아야 함**
+- 갭보정 로그: `freeze_skip` 있고, `update≈0`, **`insert`만** 정상 (구멍 메우기)
+
+### 2순위 — 웹백테 1회 (같은 날 · 같은 파라미터)
+
+**말:** 그날 실매가 본 봉으로, 웹 백테도 같은 시험을 한 번 돌려 본다.  
+PASS/지표가 실매 저널과 **크게 안 벌어지면** OK.
+
+**주의:** 이미 덮여 커진 날(예: **7/15–16**)은 참고만. **정합 합격 기준으로 쓰지 말 것.**
+
+### 3순위 — 이 문서 §5 체크리스트 닫기
+
+위 1·2가 통과하면 §5 미체크 칸을 체크한다.  
+그때 “정합 검증 완료”라고 말해도 된다.
+
+### 선택(후속) — 틱 합으로 volume 통일
+
+freeze가 안정된 **뒤에만**. 지금은 필수 아님.
+
+### 안 하는 것 (여기선 안내만 — 강제 금지는 `.cursorrules`)
+
+- 신호/진입을 ±1분으로 땜빵하지 않는다
+- freeze를 끄거나 `*_SKIP_HTS_SCAN_DUPES`를 true로 바꾸지 않는다
--- a/docs/조건식.md
+++ b/docs/조건식.md
@@ -0,0 +1,52 @@
+# HTS 조건식 (SCAN 참고)
+
+> HTS 조건검색 = **후보 유니버스(SCAN)** 전용.  
+> TRIGGER/Optuna 그리드에 숫자를 맞추라고 강제하지 않음. (`hts-condition-grids.mdc`)  
+> `*_SKIP_HTS_SCAN_DUPES` 기본 **false** 유지 (사용자 명시 전까지).
+
+키움 조건식 이름 ↔ 봇: `CONDITION_SHORT_NAME=tail` → `strategy_id=SHORT`
+
+---
+
+## 꼬리 (tail / SHORT)
+
+**논리:** 아래 4항 **AND** (HTS에서 동시에 만족)
+
+| # | 조건 (HTS 원문) |
+|---|-----------------|
+| A | 주가등락률 : **[일] 0봉전(중) 시가대비 0봉전 종가등락률** **-10% 이상 ~ -0.5% 이하** |
+| G | 주가등락률 : **[1분] 1봉전(중) 종가대비 0봉전 종가등락률** **-10% 이상 ~ -0.5% 이하** |
+| B | **체결강도** **85% 이상 ~ 400% 이하** |
+| D | 거래량비율 : **[일] 3봉 전 거래량대비 동일주기** **150% 이상 ~ 2000% 이하** |
+
+### 한 줄 요약
+
+```
+[일] 시가→종가 -10% ~ -0.5%
+∧ [1분] 직전봉종가→현재봉종가 -10% ~ -0.5%
+∧ 체결강도 85% ~ 400%
+∧ [일] 3봉전 대비 거래량 150% ~ 2000%
+```
+
+### 코드 TRIGGER와의 관계 (참고)
+
+| 축 | HTS (SCAN) | 코드 (`TAIL_SKIP_HTS_SCAN_DUPES=false` 시) |
+|----|------------|---------------------------------------------|
+| 등락 A/G | **일봉** 시가대비 + **1분** 직전대비 | **별도 시험**: `TAIL_BAR_CHG_*` = **3분** 직전대비 (이름에 HTS A 붙이지 말 것) |
+| 체결강도 B | SCAN | TRIGGER에서 동일 재검사 안 함 |
+| 거래량 D | **일봉** 3봉전 대비 | `TAIL_VOL_MULT` → **신호봉(3분)** 거래량 배수 |
+
+- `skip=false` + `BAR_CHG_MAX=-1.0` = 의도된 이중 필터(3분 최소 하락). 장에 안 맞으면 0건 가능 (2026-07-20).
+- 그리드에 `-0.5` 있음 → 파람이 `-1.0`을 고른 것뿐. 시스템 고장 아님.
+
+### 변경 이력
+
+| 날짜 | 내용 |
+|------|------|
+| 2026-07-20 | 사용자 HTS 원문 반영 (일 -10~-0.5 / 1분 -10~-0.5 / 강도 85~400 / 일거래량 150~2000) |
+
+---
+
+## 돌파 / 모멘텀 / 스캘핑
+
+(미기재 — 사용자 제공 시 추가)