refactor: apply portfolio cap and align project docs

Keep the fixed 11-number set intact while adding a second-stage portfolio selection that caps final recommendations to the 70,000 KRW budget, and update docs/data/scripts to match the current project structure and runtime flow.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -1,47 +1,112 @@
 # deeplottery
 
-## 데이터 구간
+`deeplottery`는 로또 번호를 예측하는 프로젝트가 아니라, **전체 조합(45C6)을 규칙 기반으로 필터링해 후보를 줄이는 시스템**입니다.  
+핵심은 `BallFilter` 엔진이며, 운영 실행(`final_practice.py`)과 검증(`final_FilterTest.py`)이 분리되어 있습니다.
 
-| 구간 | 회차 |
-|------|------|
-| 학습 | `lotto_history.txt` 1~800 |
-| 검증 | 801~1000 |
-| 테스트 | 1001~이후 |
+## 목표와 설계 의도
 
-## 핵심 파일
+- 목표: 통계/패턴 기반 규칙으로 비효율 조합을 제거하고 후보군을 관리 가능한 크기로 축소
+- 설계 의도:
+  - 필터 규칙은 `final_BallFilter.py` 한 곳에서 관리
+  - 운영 추천 생성과 과거 회차 검증을 분리하여 반복 개선
+  - 같은 엔진을 운영/검증에서 공통 사용해 일관성 유지
 
-- **`final_BallFilter.py`** — 필터 로직 (`BallFilter_25` 기반, `lotto_history.txt` CSV 로드, `socket` 제거).
-- **`final_filter_params.py`** — 학습 구간(1~800회)에서만 집계한 **6개 합**·**전주 합 차이** 허용 집합.
-- **`filter_model.py`** — `from final_BallFilter import BallFilter` 재노출.
-- **`train.py` / `valid.py`** — 구간별로 당첨 6개가 모든 필터를 통과한 회차 수 집계.
-- **`final_filterTest.py`** — `1_FilterTest_25.py`와 동일한 분석·(선택) MC 생존 추정.
-- **`final_Practice.py`** — DataCrawler → 마지막 JSON 회차+1 크롤 → `predict1`+`predict2`. `lotto_history.json`으로 `BallFilter` 한 번 생성 후 공유. `predict1`은 고정 5조합(기존 1 + 미당첨 4, `hasWon`으로 제외) 후 `predict2`는 정렬된 6개·`seen`·과거 당첨 조합 제외 후 필터.
+## 전체 아키텍처
 
-## 실행 (miniconda **ncue**)
+1. 데이터 수집/갱신
+   - `DataCrawler.py`가 로또 API를 호출해 `resources/lotto_history.json`, `resources/lotto_history.txt` 갱신
+2. 필터 엔진 로딩
+   - `final_BallFilter.py`의 `BallFilter`가 과거 당첨 이력을 메모리로 적재
+3. 운영 후보 생성
+   - `final_practice.py`가 다음 회차 기준 전체 조합을 순회하며 `BallFilter.filter()`로 통과 조합만 저장
+4. 필터 성능 검증
+   - `final_FilterTest.py`가 과거 당첨번호를 기준으로 어떤 필터가 당첨을 걸렀는지/통과시켰는지 분석
+
+## 핵심 파일 설명
+
+- `final_BallFilter.py`
+  - 프로젝트 핵심 엔진
+  - `extract_final_candidates()`에서 규칙 기반 탈락 사유(`set`)를 생성
+  - `filter()`는 실사용 진입점이며, 반환 `set`이 비어 있으면 통과
+- `final_practice.py`
+  - 운영 실행 스크립트
+  - `predict1()` 고정 11조합을 유지
+  - `predict2()`는 1차 필터 통과 조합을 만든 뒤, 2차 포트폴리오 선별로 최종 추천 수를 제한
+  - 총 추천 개수는 고정수 포함 최대 70게임(70,000원) 상한을 적용
+  - 결과를 `resources/recommend_ball.biz_25.json`에 저장하고 Telegram 전송
+- `final_FilterTest.py`
+  - 검증/분석 스크립트
+  - `find_filter_method()`로 회차별 필터 적중 통계 확인
+  - `find_final_candidates()`로 특정 회차 후보군 재생성
+- `DataCrawler.py`
+  - 과거 이력 파일 수집/보강
+  - 네트워크 실패 재시도/백오프 및 누락 회차 보완 처리
+- `TelegramBot.py`
+  - 추천 결과 메시지 전송
+- `resources/`
+  - `lotto_history.json`: 회차별 원본 JSON 라인 데이터
+  - `lotto_history.txt`: 회차별 CSV 형태 요약 데이터
+  - `recommend_ball.biz_25.json`: 회차별 추천 결과 저장 파일
+
+## 실행 방법
+
+Python 실행은 Miniconda `ncue` 환경을 사용합니다.
 
 ```bash
 conda activate ncue
-python train.py
-python valid.py
-python final_filterTest.py
-# 특정 회차 생존 조합 수 Monte Carlo 근사
-python final_filterTest.py --mc-no 900 --mc-samples 12000
+python DataCrawler.py
+python final_FilterTest.py
 python final_practice.py
 ```
 
-동일 환경을 셸 스크립트로:
+## 동작 방식 상세
 
-```bash
-./scripts/run_with_ncue.sh train.py
-./scripts/run_with_ncue.sh valid.py
-```
+- 입력: 1~45에서 6개 조합 전체
+- 처리:
+  - 1차: `BallFilter` 규칙 필터 적용
+  - 2차: 고정 11조합을 유지한 채, 겹침도 기반 포트폴리오 선별로 후보 축소
+- 출력:
+  - 탈락 조합: 탈락 사유 집합 반환
+  - 최종 추천 조합: 예산 상한(최대 70,000원) 내에서 저장/전송
 
-## 설계 요약
+주요 규칙 범주 예시:
 
-- **6개 합 / 전주 합 차이**는 `final_filter_params.TRAIN_ALLOW`로 학습 구간 분포에 맞춤.
-- 그 외 통계·배수·용지 패턴·쌍/3조합 등은 `BallFilter_25`와 동일한 고정 규칙을 유지해 과도하게 느슨해지지 않도록 함.
-- `filterOneDigitPattern`에서 인자 `ball`이 예시 배열로 덮어쓰이던 버그를 수정함.
+- 합/평균 및 전주 대비 차이
+- 앞 3개/뒤 3개 합 패턴
+- 고저 비율, 끝자리 패턴, AC 값
+- 배수 개수(3/4/5/6 등)
+- 최근 N주 출현 빈도/중복 관련 규칙
+- 비선호 2개/3개 조합 제거 규칙
 
-## 참고
+## 디렉터리 현재 상태 (2026-05-08)
 
-로또는 무작위에 가깝고, 본 저장소의 필터는 **구매 조합 수를 줄이기 위한 휴리스틱**이며 당첨을 보장하지 않습니다.
+### 최상위 파일/디렉터리 현황
+
+- 실행/핵심
+  - `DataCrawler.py`
+  - `final_BallFilter.py`
+  - `final_FilterTest.py`
+  - `final_practice.py`
+  - `final_Practice.py` (구버전 스크립트)
+  - `TelegramBot.py`
+- 레거시 참조 파일
+  - `BallFilter_22.py`, `BallFilter_25.py`
+  - `1_FilterTest_22.py`, `1_FilterTest_25.py`
+  - `2_FilterTestReview_22.py`, `2_FilterTestReview_25.py`
+  - `3_Practice_22.py`, `3_Practice_25.py`
+  - `fixed10.py`
+- 데이터/설정
+  - `resources/`
+  - `requirements.txt`
+  - `scripts/`
+
+### Git 작업 트리 상태(요약)
+
+- 수정됨: `DataCrawler.py`, `README.md`, `final_BallFilter.py`, `final_practice.py`, `resources/lotto_history.json`, `resources/lotto_history.txt`
+- 삭제됨: `filter_model.py`, `final_filter_params.py`, `train.py`, `valid.py`
+- 신규(미추적): `resources/recommend_ball.biz_25.json`
+
+## 주의 사항
+
+- 이 프로젝트는 통계적 휴리스틱 기반의 후보 축소 도구이며 당첨을 보장하지 않습니다.
+- 필터가 강해질수록 후보 수는 줄지만, 실제 당첨 조합을 배제할 위험도 함께 증가합니다.