docs/plans/2026-03-03-398-400-401-integration-design.md

@@ -0,0 +1,62 @@
+# 398/400/401 통합 처리 설계
+
+## 개요
+이 문서는 이슈 #398, #400, #401을 `origin/main` 기반 통합 브랜치에서 순차적으로 처리하고,
+각 PR을 셀프 리뷰 및 CI 게이트로 검증한 뒤 머지하는 운영 설계를 정의한다.
+최종 머지된 통합 브랜치에서 overnight 스크립트를 실행하고, 모니터링 이후에도 프로그램은 계속 실행 상태를 유지한다.
+
+## 목표
+- 통합 브랜치: `feature/398-400-401`
+- 작업 브랜치: `fix/398`, `fix/400`, `fix/401`
+- PR base: 모두 `feature/398-400-401`
+- 머지 조건: `CI 전체 통과` + `셀프 리뷰에서 minor 포함 이슈 0건`
+- 최종 확인: 통합 브랜치에서 overnight 실행 및 모니터링, 프로세스 지속 실행
+
+## 아키텍처
+- `origin/main`에서 `feature/398-400-401` 생성
+- 각 이슈는 독립 브랜치(`fix/398`, `fix/400`, `fix/401`)에서 구현
+- PR은 순차적으로 생성/검증/머지 (`398 -> 400 -> 401`)
+- 각 PR은 셀프 리뷰 코멘트를 남기고, minor 이상 발견 시 수정 후 재검증
+- 3개 PR 머지 완료 후 통합 브랜치에서 overnight 백그라운드 실행 및 로그 모니터링
+- 모니터링 완료 후에도 프로세스는 종료하지 않음
+
+## 컴포넌트
+- Git/브랜치 컴포넌트: 브랜치 생성, 리베이스, 충돌 해결
+- 이슈 구현 컴포넌트:
+  - #398: KR 주문 `rt_cd` 실패 처리, 오알림/오기록 차단
+  - #400: US 세션 전환 감지, US_DAY 억제, US_REG 진입 이벤트/강제 재스캔
+  - #401: 시장 단위 병렬 처리 및 공유 상태 동시성 보호
+- PR 운영 컴포넌트: PR 생성, 셀프 리뷰 코멘트 작성, 승인 기준 확인
+- CI 게이트 컴포넌트: 체크 상태 폴링 및 pass 확인
+- 머지 컴포넌트: 게이트 통과 PR만 머지
+- 런타임 검증 컴포넌트: overnight 실행, 로그 추적, 프로세스 생존 확인
+
+## 데이터/제어 흐름
+1. `feature/398-400-401` 생성
+2. `fix/398` 구현 -> 테스트 -> 커밋 -> PR 생성
+3. 셀프 리뷰 코멘트 작성(결함 레벨 포함)
+4. CI 완료 대기 후 `CI pass && minor 0`이면 머지
+5. `fix/400`, `fix/401`에 대해 동일 절차 반복
+6. 통합 브랜치에서 overnight 백그라운드 실행
+7. 로그/상태 모니터링으로 실제 동작 확인
+8. 결과 보고 후에도 프로세스는 계속 실행
+
+## 에러 처리/복구
+- PR 생성/충돌 실패: 해당 브랜치만 중단 후 해결, 다른 브랜치와 격리 유지
+- 셀프 리뷰 실패(minor 포함): 머지 금지, 수정 커밋 후 리뷰 갱신
+- CI 실패: 실패 원인 수정 후 재푸시, 재검증
+- 머지 실패: base 최신화 및 재시도
+- overnight 시작 실패: 로그 분석 후 재기동
+- 모니터링 중 오류: 오류 보고는 하되 자동 종료하지 않고 실행 유지
+
+## 테스트/검증
+- PR별 관련 단위/통합 테스트 실행
+- 필요 시 `tests/test_main.py`, `tests/test_runtime_overnight_scripts.py` 포함 회귀 실행
+- 셀프 리뷰는 `Critical/Major/Minor` 기준으로 작성
+- minor 0건 명시된 경우에만 머지 진행
+- 최종 통합 브랜치에서 overnight 기동/루프 진입/에러 로그 확인
+- PID/프로세스 생존 확인 후 실행 지속 상태 보고
+
+## 비목표
+- 본 문서는 구현 상세 코드 변경 자체를 다루지 않는다.
+- 본 문서는 외부 리뷰어 승인 프로세스를 다루지 않는다(셀프 리뷰만 대상).