프로젝트 소개

본 프로젝트는 중국 A주 거래 규칙에 최적화된 로컬 우선 시뮬레이션 및 퀀트 연구 인프라입니다. 증권사와 연결되지 않으며 실제 자금을 다루지 않으며, 공개 저장소에는 소스 코드, 컨테이너 설정 및 비식별화된 문서만 포함되어 있습니다. 핵심 아이디어는 A주 규칙을 백테스트 종료 후 근사치로 수정하는 것이 아니라, 체결 및 주문 검증 경로에 직접 반영하는 것입니다. 주식 T+1, 100주 정수 단위, 상하한가, 거래 정지, 수수료, 인지세 및 슬리피지가 주문 전 검증 단계에 포함됩니다. 시세 데이터는 기본적으로 fail-closed 방식으로 작동하여, 오래되었거나 누락되었거나 커버리지가 부족한 시세가 '실시간 가격'으로 조용히 합성되지 않으며, 근거가 부족할 경우 시뮬레이션 체결을 거부합니다. 시세 측면에서는 다중 소스 수집 및 독립 검증을 채택하여, 실시간 가격에 명확한 타임스탬프와 출처를 부여합니다. 전 시장 스냅샷에는 커버리지 게이트가 설정되어 있어, 데이터 소스 장애 시 신호 풍부도를 낮추거나 해당 경로를 차단하는 방식으로 우선 대응합니다. 리스크 관리는 계층형 상태 머신으로 구현되었습니다. 모든 매매는 독립적인 리스크 관리 계층을 먼저 거쳐 approved, rejected, deferred_capacity, downside_warning 등의 구조화된 결과를 생성합니다. 하드 스톱로스, 트레일링 스톱, 단계적 익절, 퀄리티 로테이션, 용량 압축 및 집중도 가드를 지원합니다. 하방 보호는 분할 매도에서 전량 청산까지 이어지는 상태 머신을 사용하며, 리스크 관리 사유는 안정적인 태그와 감사 원장으로 기록됩니다. 자금 관리는 공유 자금 풀이 전략별로 예산을 귀속시키며, 계좌 상한, 종목별 예산, 공정성 보호 및 자금 하드 상한을 포함합니다. 자금 예약과 실제 차감은 분리되어 있으며, SQLite savepoint를 통해 동시 스캔 시의 중복 점유를 방지합니다. 스케줄링은 auction, open, risk, intraday, close, weekly-review의 6가지 슬롯을 통합 지원합니다. 원클릭 실행 시 기본적으로 내장된 3분 단위 장중 스케줄러가 활성화되며, 외부 스케줄러가 있을 경우 끌 수 있습니다. 런타임 리스(lease), heartbeat 및 fencing token을 사용하여 중복 주문, 좀비 라이터 및 동시 덮어쓰기를 방지합니다. 전략 수준에서는 tq_breakout(강세 돌파), trend_pullback(추세 되돌림), sector_rotation(섹터 로테이션), reported_profit_breakout(퀄리티 돌파), main_force_top10(주력 자금) 등 5가지 정의를 완전히 유지하며, 이를 전략 레지스트리, 히스토리 재생 및 감사 전시 시스템에 통합했습니다. 이들은 체결, 자금 풀, 리스크 관리 및 감사 인프라를 공유하지만, 각각 독립적인 후보 레인, 포지션 슬롯 및 청산 규칙을 가집니다. 본 프로젝트는 실거래 라우팅, 레버리지, 공매도 및 일반 주식의 T+0 당일 회전 매매는 지원하지 않습니다. 신호, 후보, 리스크 결정, 주문, 체결, 포지션, NAV 및 라운드별 스캔 결과는 모두 추적 가능한 증거로 형성됩니다. adaptive_*, news_learning, neural_shadow, dual_ai_tuner 등 연구 모듈은 독립적인 섀도우 관측치를 저장하며, 정식 체결 경로를 우회하지 않습니다. LLM 관련 기능은 선택 사항이며, 기본 시뮬레이션 판은 LLM에 의존하지 않습니다. 배포는 Python 3.11+를 요구하며, Windows용 start.ps1/start.bat 및 Linux/macOS용 start.sh를 제공합니다. Docker 또는 로컬 모드를 자동 선택할 수 있으며, 포트, 브라우저 실행 여부, 내장 스케줄러 활성화 여부를 지정할 수 있습니다. Docker Compose는 애플리케이션 이미지와 명명된 볼륨을 제공하며, 기본적으로 8600 포트를 매핑합니다. 현재 Compose 매핑이 모든 네트워크 인터페이스를 리스닝하므로, 개인 사용 시 127.0.0.1로 변경할 것을 권장하며, 애플리케이션에 아직 완전한 내장 인증 기능이 없음을 명시합니다. 실제 시세를 먼저 연결하고 싶지 않은 사용자를 위해 ASTOCK_DEMO=1 설정을 통해 최초 실행 시 완전히 합성된 데모 데이터를 주입할 수 있습니다. 네트워크와 API 키가 필요 없으며, 10개의 합성 종목과 정상 매수 체결, T+1 당일 매도 거부, 오래된 호가 거부, 하드 스톱로스 매도, 상한가 매수 등의 시나리오를 포함한 완전한 서사 원장을 제공합니다. 이 주입 과정은 멱등성을 가지며, 구조화된 내용은 CI에서 golden replay를 통해 바이트 단위로 비교되어 서사 표류를 방지합니다. 저장소에는 백엔드 체결/리스크 관리/감사 메인 엔진, 대시보드 읽기 모델, 시세 수집, 결정 엔진, 전략 정의, HTTP API 및 FastAPI/Web 대시보드 진입점, 그리고 오프라인 회귀 테스트가 포함되어 있습니다. CI는 Python 3.11/3.12에서 회귀 테스트, Ruff 정적 검사, 락 파일 일관성 검사, pip-audit 및 Docker 스모크 테스트를 수행합니다. 프로젝트는 MIT 라이선스를 채택했으며, README의 리스크 고지 사항을 통해 시뮬레이션, 백테스트 및 과거 결과가 미래 수익을 보장하거나 투자 권유가 아님을 강조합니다.