Compare commits
19 Commits
feature/is
...
feature/is
| Author | SHA1 | Date | |
|---|---|---|---|
|
5050a4cf84 | ||
|
|
4987b6393a | ||
| 8faf974522 | |||
|
|
d524159ad0 | ||
|
|
c7c740f446 | ||
|
|
1333c65455 | ||
| 9db7f903f8 | |||
|
|
4660310ee4 | ||
|
|
c383a411ff | ||
| 7b3ba27ef7 | |||
|
|
6ff887c047 | ||
| 219eef6388 | |||
|
|
9d7ca12275 | ||
|
|
ccb00ee77d | ||
| b1b728f62e | |||
|
|
df12be1305 | ||
| 6a6d3bd631 | |||
| 6f93258983 | |||
|
|
82167c5b8a |
56
docs/ouroboros/00_validation_system.md
Normal file
56
docs/ouroboros/00_validation_system.md
Normal file
@@ -0,0 +1,56 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-VAL-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# 문서 검증 시스템
|
||||||
|
|
||||||
|
본 문서는 문서 간 허위 내용, 수치 충돌, 구현 불가능 지시를 사전에 제거하기 위한 검증 규칙이다.
|
||||||
|
|
||||||
|
## 검증 목표
|
||||||
|
|
||||||
|
- 단일 진실원장 기준으로 모든 지시서의 수치/규칙 정합성 보장
|
||||||
|
- 설계 문장과 코드 작업 지시 간 추적성 보장
|
||||||
|
- 테스트 미정의 상태에서 구현 착수 금지
|
||||||
|
|
||||||
|
## 불일치 유형 정의
|
||||||
|
|
||||||
|
- `RULE-DOC-001`: 정의되지 않은 요구사항 ID 사용
|
||||||
|
- `RULE-DOC-002`: 동일 요구사항 ID에 상충되는 값(예: 슬리피지 수치) 기술
|
||||||
|
- `RULE-DOC-003`: 시간대 미표기 또는 KST/UTC 혼용 지시
|
||||||
|
- `RULE-DOC-004`: 주문 정책과 리스크 정책 충돌(예: 저유동 세션 시장가 허용)
|
||||||
|
- `RULE-DOC-005`: 구현 태스크에 테스트 ID 미연결
|
||||||
|
- `RULE-DOC-006`: 문서 라우팅 링크 깨짐
|
||||||
|
|
||||||
|
## 검증 파이프라인
|
||||||
|
|
||||||
|
1. 정적 검사 (자동)
|
||||||
|
- 대상: `docs/ouroboros/*.md`
|
||||||
|
- 검사: 메타데이터, 링크 유효성, ID 정의/참조 일치, REQ-추적성 매핑
|
||||||
|
- 도구: `scripts/validate_ouroboros_docs.py`
|
||||||
|
|
||||||
|
2. 추적성 검사 (자동 + 수동)
|
||||||
|
- 자동: `REQ-*`가 최소 1개 `TASK-*`와 1개 `TEST-*`에 연결되었는지 확인
|
||||||
|
- 수동: 정책 충돌 후보를 PR 체크리스트로 검토
|
||||||
|
|
||||||
|
3. 도메인 무결성 검사 (수동)
|
||||||
|
- KIS 점검시간 회피, 주문 유형 강제, Kill Switch 순서, 환율 정책이 동시에 존재하는지 점검
|
||||||
|
- 백테스트 체결가가 보수 가정인지 점검
|
||||||
|
|
||||||
|
## 변경 통제 규칙
|
||||||
|
|
||||||
|
- `REQ-*` 추가/수정 시 반드시 `01_requirements_registry.md` 먼저 변경
|
||||||
|
- `TASK-*` 수정 시 반드시 `40_acceptance_and_test_plan.md`의 대응 테스트를 동시 수정
|
||||||
|
- 충돌 발생 시 우선순위: `requirements_registry > phase execution > code work order`
|
||||||
|
|
||||||
|
적용 룰셋:
|
||||||
|
- `RULE-DOC-001` `RULE-DOC-002` `RULE-DOC-003` `RULE-DOC-004` `RULE-DOC-005` `RULE-DOC-006`
|
||||||
|
|
||||||
|
## PR 게이트
|
||||||
|
|
||||||
|
- `python3 scripts/validate_ouroboros_docs.py` 성공
|
||||||
|
- 신규/변경 `REQ-*`가 테스트 기준(`TEST-*`)과 연결됨
|
||||||
|
- 원본 계획(v2/v3)과 모순 없음
|
||||||
39
docs/ouroboros/01_requirements_registry.md
Normal file
39
docs/ouroboros/01_requirements_registry.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-REQ-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# 요구사항 원장 (Single Source of Truth)
|
||||||
|
|
||||||
|
이 문서의 ID가 계획/구현/테스트 전 문서에서 참조되는 유일한 요구사항 집합이다.
|
||||||
|
|
||||||
|
## v2 핵심 요구사항
|
||||||
|
|
||||||
|
- `REQ-V2-001`: 상태는 `HOLDING`, `BE_LOCK`, `ARMED`, `EXITED` 4단계여야 한다.
|
||||||
|
- `REQ-V2-002`: 상태 전이는 매 틱/바 평가 시 최상위 상태로 즉시 승격되어야 한다.
|
||||||
|
- `REQ-V2-003`: `EXITED` 조건은 모든 상태보다 우선 평가되어야 한다.
|
||||||
|
- `REQ-V2-004`: 청산 로직은 Hard Stop, BE Lock, ATR Trailing, 모델 확률 보조 트리거를 포함해야 한다.
|
||||||
|
- `REQ-V2-005`: 라벨링은 Triple Barrier(Upper/Lower/Time) 방식이어야 한다.
|
||||||
|
- `REQ-V2-006`: 검증은 Walk-forward + Purge/Embargo를 강제한다.
|
||||||
|
- `REQ-V2-007`: 백테스트는 비용/슬리피지/체결실패를 반영하지 않으면 채택 불가다.
|
||||||
|
- `REQ-V2-008`: Kill Switch는 신규주문차단 -> 미체결취소 -> 재조회 -> 리스크축소 -> 스냅샷 순서다.
|
||||||
|
|
||||||
|
## v3 핵심 요구사항
|
||||||
|
|
||||||
|
- `REQ-V3-001`: 모든 신호/주문/로그는 `session_id`를 포함해야 한다.
|
||||||
|
- `REQ-V3-002`: 세션 전환 시 리스크 파라미터 재로딩이 수행되어야 한다.
|
||||||
|
- `REQ-V3-003`: 브로커 블랙아웃 시간대에는 신규 주문이 금지되어야 한다.
|
||||||
|
- `REQ-V3-004`: 블랙아웃 중 신호는 Queue에 적재되고, 복구 후 유효성 재검증을 거친다.
|
||||||
|
- `REQ-V3-005`: 저유동 세션(`NXT_AFTER`, `US_PRE`, `US_DAY`, `US_AFTER`)은 시장가 주문 금지다.
|
||||||
|
- `REQ-V3-006`: 백테스트 체결가는 불리한 방향 체결 가정을 기본으로 한다.
|
||||||
|
- `REQ-V3-007`: US 운용은 환율 손익 분리 추적과 통화 버퍼 정책을 포함해야 한다.
|
||||||
|
- `REQ-V3-008`: 마감/오버나잇 규칙은 Kill Switch와 충돌 없이 연동되어야 한다.
|
||||||
|
|
||||||
|
## 공통 운영 요구사항
|
||||||
|
|
||||||
|
- `REQ-OPS-001`: 타임존은 모든 시간 필드에 명시(KST/UTC)되어야 한다.
|
||||||
|
- `REQ-OPS-002`: 문서의 수치 정책은 원장에서만 변경한다.
|
||||||
|
- `REQ-OPS-003`: 구현 태스크는 반드시 테스트 태스크를 동반한다.
|
||||||
63
docs/ouroboros/10_phase_v2_execution.md
Normal file
63
docs/ouroboros/10_phase_v2_execution.md
Normal file
@@ -0,0 +1,63 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-PHASE-V2-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# v2 실행 지시서 (설계 -> 코드)
|
||||||
|
|
||||||
|
참조 요구사항: `REQ-V2-001` `REQ-V2-002` `REQ-V2-003` `REQ-V2-004` `REQ-V2-005` `REQ-V2-006` `REQ-V2-007` `REQ-V2-008` `REQ-OPS-001` `REQ-OPS-002` `REQ-OPS-003`
|
||||||
|
|
||||||
|
## 단계 1: 도메인 모델 확정
|
||||||
|
|
||||||
|
- `TASK-V2-001`: 상태머신 enum/전이 이벤트/전이 사유 스키마 설계
|
||||||
|
- `TASK-V2-002`: `position_state` 스냅샷 구조(현재상태, peak, stops, last_reason) 정의
|
||||||
|
- `TASK-V2-003`: 청산 판단 입력 DTO(가격, ATR, pred_prob, liquidity_signal) 정의
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- 상태와 전이 사유가 로그/DB에서 재현 가능
|
||||||
|
- `REQ-V2-001`~`003`을 코드 타입 수준에서 강제
|
||||||
|
|
||||||
|
## 단계 2: 청산 엔진 구현
|
||||||
|
|
||||||
|
- `TASK-V2-004`: 우선순위 기반 전이 함수 구현(`evaluate_exit_first` -> `promote_state`)
|
||||||
|
- `TASK-V2-005`: Hard Stop/BE Lock/ATR Trailing 결합 로직 구현
|
||||||
|
- `TASK-V2-006`: 모델 확률 신호를 보조 트리거로 결합(단독 청산 금지)
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- 갭 상황에서 다중 조건 동시 충족 시 최상위 상태로 단번 전이
|
||||||
|
- `REQ-V2-004` 준수
|
||||||
|
|
||||||
|
## 단계 3: 라벨링/학습 데이터 파이프라인
|
||||||
|
|
||||||
|
- `TASK-V2-007`: Triple Barrier 라벨러 구현(장벽 선터치 우선)
|
||||||
|
- `TASK-V2-008`: 피처 구간/라벨 구간 분리 검증 유틸 구현
|
||||||
|
- `TASK-V2-009`: 라벨 생성 로그(진입시각, 터치장벽, 만기장벽) 기록
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- look-ahead 차단 증빙 로그 확보
|
||||||
|
- `REQ-V2-005` 충족
|
||||||
|
|
||||||
|
## 단계 4: 검증 프레임워크
|
||||||
|
|
||||||
|
- `TASK-V2-010`: Walk-forward split + Purge/Embargo 분할기 구현
|
||||||
|
- `TASK-V2-011`: 베이스라인(`B0`,`B1`,`M1`) 비교 리포트 포맷 구현
|
||||||
|
- `TASK-V2-012`: 체결 비용/슬리피지/실패 반영 백테스트 옵션 강제
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V2-006`, `REQ-V2-007` 충족
|
||||||
|
|
||||||
|
## 단계 5: Kill Switch 통합
|
||||||
|
|
||||||
|
- `TASK-V2-013`: Kill Switch 순차 실행 오케스트레이터 구현 (`src/core/risk_manager.py` 수정 금지)
|
||||||
|
- `TASK-V2-014`: 주문 차단 플래그/미체결 취소/재조회 재시도 로직 구현
|
||||||
|
- `TASK-V2-015`: 스냅샷/알림/복구 진입 절차 구현
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V2-008` 순서 일치
|
||||||
|
|
||||||
|
라우팅:
|
||||||
|
- 코드 지시 상세: [30_code_level_work_orders.md](./30_code_level_work_orders.md)
|
||||||
|
- 테스트 상세: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)
|
||||||
60
docs/ouroboros/20_phase_v3_execution.md
Normal file
60
docs/ouroboros/20_phase_v3_execution.md
Normal file
@@ -0,0 +1,60 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-PHASE-V3-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# v3 실행 지시서 (세션 확장)
|
||||||
|
|
||||||
|
참조 요구사항: `REQ-V3-001` `REQ-V3-002` `REQ-V3-003` `REQ-V3-004` `REQ-V3-005` `REQ-V3-006` `REQ-V3-007` `REQ-V3-008` `REQ-OPS-001` `REQ-OPS-002` `REQ-OPS-003`
|
||||||
|
|
||||||
|
## 단계 1: 세션 엔진
|
||||||
|
|
||||||
|
- `TASK-V3-001`: `session_id` 분류기 구현(KR/US 확장 세션)
|
||||||
|
- `TASK-V3-002`: 세션 전환 훅에서 리스크 파라미터 재로딩 구현
|
||||||
|
- `TASK-V3-003`: 로그/DB 스키마에 `session_id` 필드 강제
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V3-001`, `REQ-V3-002` 충족
|
||||||
|
|
||||||
|
## 단계 2: 블랙아웃/복구 제어
|
||||||
|
|
||||||
|
- `TASK-V3-004`: 블랙아웃 윈도우 정책 로더 구현(설정 기반)
|
||||||
|
- `TASK-V3-005`: 블랙아웃 중 신규 주문 차단 + 의도 큐 적재 구현
|
||||||
|
- `TASK-V3-006`: 복구 시 동기화(잔고/미체결/체결) 후 큐 재검증 실행
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V3-003`, `REQ-V3-004` 충족
|
||||||
|
|
||||||
|
## 단계 3: 주문 정책 강화
|
||||||
|
|
||||||
|
- `TASK-V3-007`: 세션별 주문 타입 매트릭스 구현
|
||||||
|
- `TASK-V3-008`: 저유동 세션 시장가 주문 하드 차단
|
||||||
|
- `TASK-V3-009`: 재호가 간격/횟수 제한 및 주문 철회 조건 구현
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V3-005` 충족
|
||||||
|
|
||||||
|
## 단계 4: 비용/체결 모델 정교화
|
||||||
|
|
||||||
|
- `TASK-V3-010`: 세션별 슬리피지/비용 테이블 엔진 반영
|
||||||
|
- `TASK-V3-011`: 불리한 체결 가정(상대 호가 방향) 체결기 구현
|
||||||
|
- `TASK-V3-012`: 시나리오별 체결 실패/부분체결 모델 반영
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V3-006` 충족
|
||||||
|
|
||||||
|
## 단계 5: 환율/오버나잇/Kill Switch 연동
|
||||||
|
|
||||||
|
- `TASK-V3-013`: 전략 PnL과 FX PnL 분리 회계 구현
|
||||||
|
- `TASK-V3-014`: USD/KRW 버퍼 규칙 위반 시 신규 진입 제한 구현
|
||||||
|
- `TASK-V3-015`: 오버나잇 예외와 Kill Switch 우선순위 통합
|
||||||
|
|
||||||
|
완료 기준:
|
||||||
|
- `REQ-V3-007`, `REQ-V3-008` 충족
|
||||||
|
|
||||||
|
라우팅:
|
||||||
|
- 코드 지시 상세: [30_code_level_work_orders.md](./30_code_level_work_orders.md)
|
||||||
|
- 테스트 상세: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)
|
||||||
59
docs/ouroboros/30_code_level_work_orders.md
Normal file
59
docs/ouroboros/30_code_level_work_orders.md
Normal file
@@ -0,0 +1,59 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-CODE-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# 코드 레벨 작업 지시서
|
||||||
|
|
||||||
|
본 문서는 파일 단위 구현 지시서다. 모든 작업은 요구사항 ID와 테스트 ID를 포함해야 한다.
|
||||||
|
|
||||||
|
제약:
|
||||||
|
- `src/core/risk_manager.py`는 READ-ONLY로 간주하고 수정하지 않는다.
|
||||||
|
- Kill Switch는 별도 모듈(예: `src/core/kill_switch.py`)로 추가하고 상위 실행 루프에서 연동한다.
|
||||||
|
|
||||||
|
## 구현 단위 A: 상태기계/청산
|
||||||
|
|
||||||
|
- `TASK-CODE-001` (`REQ-V2-001`,`REQ-V2-002`,`REQ-V2-003`): `src/strategy/`에 상태기계 모듈 추가
|
||||||
|
- `TASK-CODE-002` (`REQ-V2-004`): ATR/BE/Hard Stop 결합 청산 함수 추가
|
||||||
|
- `TASK-CODE-003` (`REQ-V2-008`): Kill Switch 오케스트레이터를 `src/core/kill_switch.py`에 추가
|
||||||
|
- `TEST-CODE-001`: 갭 점프 시 최고상태 승격 테스트
|
||||||
|
- `TEST-CODE-002`: EXIT 우선순위 테스트
|
||||||
|
|
||||||
|
## 구현 단위 B: 라벨링/검증
|
||||||
|
|
||||||
|
- `TASK-CODE-004` (`REQ-V2-005`): Triple Barrier 라벨러 모듈 추가(`src/analysis/` 또는 `src/strategy/`)
|
||||||
|
- `TASK-CODE-005` (`REQ-V2-006`): Walk-forward + Purge/Embargo 분할 유틸 추가
|
||||||
|
- `TASK-CODE-006` (`REQ-V2-007`): 백테스트 실행기에서 비용/슬리피지 옵션 필수화
|
||||||
|
- `TEST-CODE-003`: 라벨 선터치 우선 테스트
|
||||||
|
- `TEST-CODE-004`: 누수 차단 테스트
|
||||||
|
|
||||||
|
## 구현 단위 C: 세션/주문 정책
|
||||||
|
|
||||||
|
- `TASK-CODE-007` (`REQ-V3-001`,`REQ-V3-002`): 세션 분류/전환 훅을 `src/markets/schedule.py` 연동
|
||||||
|
- `TASK-CODE-008` (`REQ-V3-003`,`REQ-V3-004`): 블랙아웃 큐 처리기를 `src/broker/`에 추가
|
||||||
|
- `TASK-CODE-009` (`REQ-V3-005`): 세션별 주문 타입 검증기 추가
|
||||||
|
- `TEST-CODE-005`: 블랙아웃 신규주문 차단 테스트
|
||||||
|
- `TEST-CODE-006`: 저유동 세션 시장가 거부 테스트
|
||||||
|
|
||||||
|
## 구현 단위 D: 체결/환율/오버나잇
|
||||||
|
|
||||||
|
- `TASK-CODE-010` (`REQ-V3-006`): 불리한 체결가 모델을 백테스트 체결기로 구현
|
||||||
|
- `TASK-CODE-011` (`REQ-V3-007`): FX PnL 분리 회계 테이블/컬럼 추가
|
||||||
|
- `TASK-CODE-012` (`REQ-V3-008`): 오버나잇 예외와 Kill Switch 충돌 해소 로직 구현
|
||||||
|
- `TEST-CODE-007`: 불리한 체결가 모델 테스트
|
||||||
|
- `TEST-CODE-008`: FX 버퍼 위반 시 신규진입 제한 테스트
|
||||||
|
|
||||||
|
## 구현 단위 E: 운영/문서 거버넌스
|
||||||
|
|
||||||
|
- `TASK-OPS-001` (`REQ-OPS-001`): 시간 필드/로그 스키마의 타임존 표기 강제 규칙 구현
|
||||||
|
- `TASK-OPS-002` (`REQ-OPS-002`): 정책 수치 변경 시 `01_requirements_registry.md` 선수정 CI 체크 추가
|
||||||
|
- `TASK-OPS-003` (`REQ-OPS-003`): `TASK-*` 없는 `REQ-*` 또는 `TEST-*` 없는 `REQ-*`를 차단하는 문서 검증 게이트 유지
|
||||||
|
|
||||||
|
## 커밋 규칙
|
||||||
|
|
||||||
|
- 커밋 메시지에 `TASK-*` 포함
|
||||||
|
- PR 본문에 `REQ-*`, `TEST-*` 매핑 표 포함
|
||||||
|
- 변경 파일마다 최소 1개 테스트 연결
|
||||||
57
docs/ouroboros/40_acceptance_and_test_plan.md
Normal file
57
docs/ouroboros/40_acceptance_and_test_plan.md
Normal file
@@ -0,0 +1,57 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-TEST-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# 수용 기준 및 테스트 계획
|
||||||
|
|
||||||
|
## 수용 기준
|
||||||
|
|
||||||
|
- `TEST-ACC-000` (`REQ-V2-001`): 상태 enum은 4개(`HOLDING`,`BE_LOCK`,`ARMED`,`EXITED`)만 허용한다.
|
||||||
|
- `TEST-ACC-001` (`REQ-V2-002`): 상태 전이는 순차 if-else가 아닌 우선순위 승격으로 동작한다.
|
||||||
|
- `TEST-ACC-010` (`REQ-V2-003`): `EXITED` 조건은 어떤 상태보다 먼저 평가된다.
|
||||||
|
- `TEST-ACC-011` (`REQ-V2-004`): 청산 판단은 Hard Stop/BE Lock/ATR/모델보조 4요소를 모두 포함한다.
|
||||||
|
- `TEST-ACC-012` (`REQ-V2-005`): Triple Barrier 라벨은 first-touch 규칙으로 결정된다.
|
||||||
|
- `TEST-ACC-013` (`REQ-V2-006`): 학습/검증 분할은 Walk-forward + Purge/Embargo를 적용한다.
|
||||||
|
- `TEST-ACC-014` (`REQ-V2-007`): 비용/슬리피지/체결실패 옵션 비활성 시 백테스트 실행을 거부한다.
|
||||||
|
- `TEST-ACC-002` (`REQ-V2-008`): Kill Switch 실행 순서가 고정 순서를 위반하지 않는다.
|
||||||
|
- `TEST-ACC-015` (`REQ-V3-001`): 모든 주문/로그 레코드에 `session_id`가 저장된다.
|
||||||
|
- `TEST-ACC-016` (`REQ-V3-002`): 세션 전환 이벤트 시 리스크 파라미터가 재로딩된다.
|
||||||
|
- `TEST-ACC-003` (`REQ-V3-003`): 블랙아웃 중 신규 주문 API 호출이 발생하지 않는다.
|
||||||
|
- `TEST-ACC-017` (`REQ-V3-004`): 블랙아웃 큐는 복구 후 재검증을 통과한 주문만 실행한다.
|
||||||
|
- `TEST-ACC-004` (`REQ-V3-005`): 저유동 세션 시장가 주문은 항상 거부된다.
|
||||||
|
- `TEST-ACC-005` (`REQ-V3-006`): 백테스트 체결가가 단순 종가 체결보다 보수적 손익을 낸다.
|
||||||
|
- `TEST-ACC-006` (`REQ-V3-007`): 전략 손익과 환율 손익이 별도 집계된다.
|
||||||
|
- `TEST-ACC-018` (`REQ-V3-008`): 오버나잇 예외 상태에서도 Kill Switch 우선순위가 유지된다.
|
||||||
|
- `TEST-ACC-007` (`REQ-OPS-001`): 시간 관련 필드는 타임존(KST/UTC)이 누락되면 검증 실패한다.
|
||||||
|
- `TEST-ACC-008` (`REQ-OPS-002`): 정책 수치 변경이 원장 미반영이면 검증 실패한다.
|
||||||
|
- `TEST-ACC-009` (`REQ-OPS-003`): `REQ-*`가 `TASK-*`/`TEST-*` 매핑 없이 존재하면 검증 실패한다.
|
||||||
|
|
||||||
|
## 테스트 계층
|
||||||
|
|
||||||
|
1. 단위 테스트
|
||||||
|
- 상태 전이, 주문타입 검증, 큐 복구 로직, 체결가 모델
|
||||||
|
|
||||||
|
2. 통합 테스트
|
||||||
|
- 세션 전환 -> 주문 정책 -> 리스크 엔진 연동
|
||||||
|
- 블랙아웃 시작/해제 이벤트 연동
|
||||||
|
|
||||||
|
3. 회귀 테스트
|
||||||
|
- 기존 `tests/` 스위트 전량 실행
|
||||||
|
- 신규 기능 플래그 ON/OFF 비교
|
||||||
|
|
||||||
|
## 실행 명령
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pytest -q
|
||||||
|
python3 scripts/validate_ouroboros_docs.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## 실패 처리 규칙
|
||||||
|
|
||||||
|
- 문서 검증 실패 시 구현 PR 병합 금지
|
||||||
|
- `REQ-*` 변경 후 테스트 매핑 누락 시 병합 금지
|
||||||
|
- 회귀 실패 시 원인 모듈 분리 후 재검증
|
||||||
68
docs/ouroboros/50_scenario_matrix_and_issue_taxonomy.md
Normal file
68
docs/ouroboros/50_scenario_matrix_and_issue_taxonomy.md
Normal file
@@ -0,0 +1,68 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-PM-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# 실전 시나리오 매트릭스 + 이슈 분류 체계
|
||||||
|
|
||||||
|
목표: 운영에서 바로 사용할 수 있는 형태로 Happy Path / Failure Path / Ops Incident를 추적 가능한 ID 체계(`REQ-*`, `TASK-*`, `TEST-*`)에 매핑한다.
|
||||||
|
|
||||||
|
## 1) 시나리오 매트릭스
|
||||||
|
|
||||||
|
| Scenario ID | Type | Trigger | Expected System Behavior | Primary IDs (REQ/TASK/TEST) | Ticket Priority |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| `SCN-HAPPY-001` | Happy Path | KR 정규 세션에서 진입 신호 발생, 블랙아웃 아님 | 주문/로그에 `session_id` 저장 후 정책에 맞는 주문 전송 | `REQ-V3-001`, `TASK-V3-001`, `TASK-V3-003`, `TEST-ACC-015` | P1 |
|
||||||
|
| `SCN-HAPPY-002` | Happy Path | 보유 포지션에서 BE/ATR/Hard Stop 조건 순차 도달 | 상태가 즉시 상위 단계로 승격, `EXITED` 우선 평가 보장 | `REQ-V2-002`, `REQ-V2-003`, `TASK-V2-004`, `TEST-ACC-001`, `TEST-ACC-010` | P0 |
|
||||||
|
| `SCN-HAPPY-003` | Happy Path | 세션 전환(KR->US) 이벤트 발생 | 리스크 파라미터 자동 재로딩, 새 세션 정책으로 즉시 전환 | `REQ-V3-002`, `TASK-V3-002`, `TEST-ACC-016` | P0 |
|
||||||
|
| `SCN-HAPPY-004` | Happy Path | 백테스트 실행 요청 | 비용/슬리피지/체결실패 옵션 누락 시 실행 거부, 포함 시 실행 | `REQ-V2-007`, `TASK-V2-012`, `TEST-ACC-014` | P1 |
|
||||||
|
| `SCN-FAIL-001` | Failure Path | 블랙아웃 중 신규 주문 신호 발생 | 신규 주문 차단 + 주문 의도 큐 적재, API 직접 호출 금지 | `REQ-V3-003`, `REQ-V3-004`, `TASK-V3-005`, `TEST-ACC-003`, `TEST-ACC-017` | P0 |
|
||||||
|
| `SCN-FAIL-002` | Failure Path | 저유동 세션에 시장가 주문 요청 | 시장가 하드 거부, 지정가 대체 또는 주문 취소 | `REQ-V3-005`, `TASK-V3-007`, `TASK-V3-008`, `TEST-ACC-004` | P0 |
|
||||||
|
| `SCN-FAIL-003` | Failure Path | Kill Switch 트리거(손실/연결/리스크 한도) | 신규주문차단->미체결취소->재조회->리스크축소->스냅샷 순서 강제 | `REQ-V2-008`, `TASK-V2-013`, `TEST-ACC-002` | P0 |
|
||||||
|
| `SCN-FAIL-004` | Failure Path | FX 버퍼 부족 상태에서 US 진입 신호 | 전략 PnL/FX PnL 분리 집계 유지, 신규 진입 제한 | `REQ-V3-007`, `TASK-V3-013`, `TASK-V3-014`, `TEST-ACC-006` | P1 |
|
||||||
|
| `SCN-OPS-001` | Ops Incident | 브로커 점검/블랙아웃 종료 직후 | 잔고/미체결/체결 동기화 후 큐 재검증 통과 주문만 집행 | `REQ-V3-004`, `TASK-V3-006`, `TEST-ACC-017` | P0 |
|
||||||
|
| `SCN-OPS-002` | Ops Incident | 정책 수치가 코드에만 반영되고 원장 미수정 | 문서 검증에서 실패 처리, PR 병합 차단 | `REQ-OPS-002`, `TASK-OPS-002`, `TEST-ACC-008` | P0 |
|
||||||
|
| `SCN-OPS-003` | Ops Incident | 타임존 누락 로그/스케줄 데이터 유입 | KST/UTC 미표기 레코드 검증 실패 처리 | `REQ-OPS-001`, `TASK-OPS-001`, `TEST-ACC-007` | P1 |
|
||||||
|
| `SCN-OPS-004` | Ops Incident | 신규 REQ 추가 후 TASK/TEST 누락 | 추적성 게이트 실패, 구현 PR 병합 차단 | `REQ-OPS-003`, `TASK-OPS-003`, `TEST-ACC-009` | P0 |
|
||||||
|
| `SCN-OPS-005` | Ops Incident | 배포 후 런타임 이상 동작(주문오류/상태전이오류/정책위반) 탐지 | Runtime Verifier가 즉시 이슈 발행, Dev 수정 후 재관측으로 클로즈 판정 | `REQ-V2-008`, `REQ-V3-003`, `REQ-V3-005`, `TEST-ACC-002`, `TEST-ACC-003`, `TEST-ACC-004` | P0 |
|
||||||
|
|
||||||
|
## 2) 이슈 분류 체계 (Issue Taxonomy)
|
||||||
|
|
||||||
|
| Taxonomy | Definition | Typical Symptoms | Default Owner | Mapping Baseline |
|
||||||
|
|---|---|---|---|---|
|
||||||
|
| `EXEC-STATE` | 상태기계/청산 우선순위 위반 | EXIT 우선순위 깨짐, 상태 역행, 갭 대응 실패 | Strategy | `REQ-V2-001`~`REQ-V2-004`, `TASK-V2-004`~`TASK-V2-006`, `TEST-ACC-000`,`001`,`010`,`011` |
|
||||||
|
| `EXEC-POLICY` | 세션/주문 정책 위반 | 블랙아웃 주문 전송, 저유동 시장가 허용 | Broker/Execution | `REQ-V3-003`~`REQ-V3-005`, `TASK-V3-004`~`TASK-V3-009`, `TEST-ACC-003`,`004`,`017` |
|
||||||
|
| `BACKTEST-MODEL` | 백테스트 현실성/검증 무결성 위반 | 비용 옵션 off로 실행, 체결가 과낙관 | Research | `REQ-V2-006`,`REQ-V2-007`,`REQ-V3-006`, `TASK-V2-010`~`012`, `TASK-V3-010`~`012`, `TEST-ACC-013`,`014`,`005` |
|
||||||
|
| `RISK-EMERGENCY` | Kill Switch/리스크 비상 대응 실패 | 순서 위반, 차단 누락, 복구 절차 누락 | Risk | `REQ-V2-008`,`REQ-V3-008`, `TASK-V2-013`~`015`, `TASK-V3-015`, `TEST-ACC-002`,`018` |
|
||||||
|
| `FX-ACCOUNTING` | 환율/통화 버퍼 정책 위반 | 전략손익/환차손익 혼합 집계, 버퍼 미적용 | Risk + Data | `REQ-V3-007`, `TASK-V3-013`,`014`, `TEST-ACC-006` |
|
||||||
|
| `OPS-GOVERNANCE` | 문서/추적성/타임존 거버넌스 위반 | 원장 미수정, TEST 누락, 타임존 미표기 | PM + QA | `REQ-OPS-001`~`003`, `TASK-OPS-001`~`003`, `TEST-ACC-007`~`009` |
|
||||||
|
| `RUNTIME-VERIFY` | 실동작 모니터링 검증 | 배포 후 이상 현상, 간헐 오류, 테스트 미포착 회귀 | Runtime Verifier + TPM | 관련 `REQ/TASK/TEST`와 런타임 로그 증적 필수 |
|
||||||
|
|
||||||
|
## 3) 티켓 생성 규칙 (Implementable)
|
||||||
|
|
||||||
|
1. 모든 이슈는 `taxonomy + scenario_id`를 제목에 포함한다.
|
||||||
|
예: `[EXEC-POLICY][SCN-FAIL-001] blackout 주문 차단 누락`
|
||||||
|
2. 본문 필수 항목: 재현절차, 기대결과, 실제결과, 영향범위, 롤백/완화책.
|
||||||
|
3. 본문에 최소 1개 `REQ-*`, 1개 `TASK-*`, 1개 `TEST-*`를 명시한다.
|
||||||
|
4. 우선순위 기준:
|
||||||
|
- P0: 실주문 위험, Kill Switch, 블랙아웃/시장가 정책, 추적성 게이트 실패
|
||||||
|
- P1: 손익 왜곡 가능성(체결/FX/시간대), 운영 리스크 증가
|
||||||
|
- P2: 보고서/관측성 품질 이슈(거래 안전성 영향 없음)
|
||||||
|
5. Runtime Verifier가 발행한 `RUNTIME-VERIFY` 이슈는 Main Agent 확인 전 클로즈 금지.
|
||||||
|
|
||||||
|
## 4) 즉시 생성 권장 티켓 (초기 백로그)
|
||||||
|
|
||||||
|
- `TKT-P0-001`: `[EXEC-POLICY][SCN-FAIL-001]` 블랙아웃 차단 + 큐적재 + 복구 재검증 e2e 점검 (`REQ-V3-003`,`REQ-V3-004`)
|
||||||
|
- `TKT-P0-002`: `[RISK-EMERGENCY][SCN-FAIL-003]` Kill Switch 순서 강제 검증 자동화 (`REQ-V2-008`)
|
||||||
|
- `TKT-P0-003`: `[OPS-GOVERNANCE][SCN-OPS-004]` REQ/TASK/TEST 누락 시 PR 차단 게이트 상시 점검 (`REQ-OPS-003`)
|
||||||
|
- `TKT-P1-001`: `[FX-ACCOUNTING][SCN-FAIL-004]` FX 버퍼 위반 시 진입 제한 회귀 케이스 보강 (`REQ-V3-007`)
|
||||||
|
- `TKT-P1-002`: `[BACKTEST-MODEL][SCN-HAPPY-004]` 비용/슬리피지 미설정 백테스트 거부 UX 명확화 (`REQ-V2-007`)
|
||||||
|
- `TKT-P0-004`: `[RUNTIME-VERIFY][SCN-OPS-005]` 배포 후 런타임 이상 탐지/재현/클로즈 판정 절차 자동화
|
||||||
|
|
||||||
|
## 5) 운영 체크포인트
|
||||||
|
|
||||||
|
- 스프린트 계획 시 `P0` 시나리오 100% 테스트 통과를 출발 조건으로 둔다.
|
||||||
|
- 배포 승인 시 `SCN-FAIL-*`, `SCN-OPS-*` 관련 `TEST-ACC-*`를 우선 확인한다.
|
||||||
|
- 정책 변경 PR은 반드시 원장(`01_requirements_registry.md`) 선수정 후 진행한다.
|
||||||
176
docs/ouroboros/50_tpm_control_protocol.md
Normal file
176
docs/ouroboros/50_tpm_control_protocol.md
Normal file
@@ -0,0 +1,176 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-TPM-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: tpm
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# TPM Control Protocol (Main <-> PM <-> TPM <-> Dev <-> Verifier <-> Runtime Verifier)
|
||||||
|
|
||||||
|
목적:
|
||||||
|
- PM 시나리오가 구현 가능한 단위로 분해되고, 개발/검증이 동일 ID 체계(`REQ-*`, `TASK-*`, `TEST-*`)로 닫히도록 강제한다.
|
||||||
|
- 각 단계는 Entry/Exit gate를 통과해야 다음 단계로 이동 가능하다.
|
||||||
|
- 주요 의사결정 포인트마다 Main Agent의 승인/의견 확인을 강제한다.
|
||||||
|
|
||||||
|
## Team Roles
|
||||||
|
|
||||||
|
- Main Agent: 최종 취합/우선순위/승인 게이트 오너
|
||||||
|
- PM Agent: 시나리오/요구사항/티켓 관리
|
||||||
|
- TPM Agent: PM-Dev-검증 간 구현 가능성/달성률 통제
|
||||||
|
- Dev Agent: 구현 수행, 블로커 발생 시 재계획 요청
|
||||||
|
- Verifier Agent: 문서/코드/테스트 산출물 검증
|
||||||
|
- Runtime Verifier Agent: 실제 동작 모니터링, 이상 징후 이슈 발행, 수정 후 이슈 클로즈 판정
|
||||||
|
|
||||||
|
## Main Decision Checkpoints (Mandatory)
|
||||||
|
|
||||||
|
- DCP-01 범위 확정: Phase 0 종료 전 Main Agent 승인 필수
|
||||||
|
- DCP-02 요구사항 확정: Phase 1 종료 전 Main Agent 승인 필수
|
||||||
|
- DCP-03 구현 착수: Phase 2 종료 전 Main Agent 승인 필수
|
||||||
|
- DCP-04 배포 승인: Phase 4 종료 후 Main Agent 최종 승인 필수
|
||||||
|
|
||||||
|
## Phase Control Gates
|
||||||
|
|
||||||
|
### Phase 0: Scenario Intake and Scope Lock
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
- PM 시나리오가 사용자 가치, 실패 모드, 우선순위를 포함해 제출됨
|
||||||
|
- 영향 범위(모듈/세션/KR-US 시장)가 명시됨
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
- 시나리오가 `REQ-*` 후보에 1:1 또는 1:N 매핑됨
|
||||||
|
- 모호한 표현("개선", "최적화")은 측정 가능한 조건으로 치환됨
|
||||||
|
- 비범위 항목(out-of-scope) 명시
|
||||||
|
|
||||||
|
Control checks:
|
||||||
|
- PM/TPM 합의 완료
|
||||||
|
- Main Agent 승인(DCP-01)
|
||||||
|
- 산출물: 시나리오 카드, 초기 매핑 메모
|
||||||
|
|
||||||
|
### Phase 1: Requirement Registry Gate
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
- Phase 0 산출물 승인
|
||||||
|
- 변경 대상 요구사항 문서 식별 완료
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
- [01_requirements_registry.md](./01_requirements_registry.md)에 `REQ-*` 정의/수정 반영
|
||||||
|
- 각 `REQ-*`가 최소 1개 `TASK-*`, 1개 `TEST-*`와 연결 가능 상태
|
||||||
|
- 시간/정책 수치는 원장 단일 소스로 확정(`REQ-OPS-001`,`REQ-OPS-002`)
|
||||||
|
|
||||||
|
Control checks:
|
||||||
|
- `python3 scripts/validate_ouroboros_docs.py` 통과
|
||||||
|
- Main Agent 승인(DCP-02)
|
||||||
|
- 산출물: 업데이트된 요구사항 원장
|
||||||
|
|
||||||
|
### Phase 2: Design and Work-Order Gate
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
- 요구사항 원장 갱신 완료
|
||||||
|
- 영향 모듈 분석 완료(상태기계, 주문정책, 백테스트, 세션)
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
- [10_phase_v2_execution.md](./10_phase_v2_execution.md), [20_phase_v3_execution.md](./20_phase_v3_execution.md), [30_code_level_work_orders.md](./30_code_level_work_orders.md)에 작업 분해 완료
|
||||||
|
- 각 작업은 구현 위치/제약/완료 조건을 가짐
|
||||||
|
- 위험 작업(Kill Switch, blackout, session transition)은 별도 롤백 절차 포함
|
||||||
|
|
||||||
|
Control checks:
|
||||||
|
- TPM이 `REQ -> TASK` 누락 여부 검토
|
||||||
|
- Main Agent 승인(DCP-03)
|
||||||
|
- 산출물: 승인된 Work Order 세트
|
||||||
|
|
||||||
|
### Phase 3: Implementation Gate
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
- 승인된 `TASK-*`가 브랜치 작업 단위로 분리됨
|
||||||
|
- 변경 범위별 테스트 계획이 PR 본문에 링크됨
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
- 코드 변경이 `TASK-*`에 대응되어 추적 가능
|
||||||
|
- 제약 준수(`src/core/risk_manager.py` 직접 수정 금지 등) 확인
|
||||||
|
- 신규 로직마다 최소 1개 테스트 추가 또는 기존 테스트 확장
|
||||||
|
|
||||||
|
Control checks:
|
||||||
|
- PR 템플릿 내 `REQ-*`/`TASK-*`/`TEST-*` 매핑 확인
|
||||||
|
- 산출물: 리뷰 가능한 PR
|
||||||
|
|
||||||
|
### Phase 4: Verification and Acceptance Gate
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
- 구현 PR ready 상태
|
||||||
|
- 테스트 케이스/픽스처 준비 완료
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
- [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)의 해당 `TEST-ACC-*` 전부 통과
|
||||||
|
- 회귀 테스트 통과(`pytest -q`)
|
||||||
|
- 문서 검증 통과(`python3 scripts/validate_ouroboros_docs.py`)
|
||||||
|
|
||||||
|
Control checks:
|
||||||
|
- Verifier가 테스트 증적(로그/리포트/실행 커맨드) 첨부
|
||||||
|
- Runtime Verifier가 스테이징/실운영 모니터링 계획 승인
|
||||||
|
- 산출물: 수용 승인 레코드
|
||||||
|
|
||||||
|
### Phase 5: Release and Post-Release Control
|
||||||
|
|
||||||
|
Entry criteria:
|
||||||
|
- Phase 4 승인
|
||||||
|
- 운영 체크리스트 준비(세션 전환, 블랙아웃, Kill Switch)
|
||||||
|
|
||||||
|
Exit criteria:
|
||||||
|
- 배포 후 초기 관찰 윈도우에서 치명 경보 없음
|
||||||
|
- 신규 시나리오/회귀 이슈는 다음 Cycle의 Phase 0 입력으로 환류
|
||||||
|
- 요구사항/테스트 문서 버전 동기화 완료
|
||||||
|
|
||||||
|
Control checks:
|
||||||
|
- PM/TPM/Dev 3자 종료 확인
|
||||||
|
- Runtime Verifier가 운영 모니터링 이슈 상태(신규/진행/해결)를 리포트
|
||||||
|
- Main Agent 최종 승인(DCP-04)
|
||||||
|
- 산출물: 릴리즈 노트 + 후속 액션 목록
|
||||||
|
|
||||||
|
## Replan Protocol (Dev -> TPM)
|
||||||
|
|
||||||
|
- 트리거:
|
||||||
|
- 구현 불가능(기술적 제약/외부 API 제약)
|
||||||
|
- 예상 대비 개발 리소스 과다(공수/인력/의존성 급증)
|
||||||
|
- 절차:
|
||||||
|
1) Dev Agent가 `REPLAN-REQUEST` 발행(영향 REQ/TASK, 원인, 대안, 추가 공수 포함)
|
||||||
|
2) TPM Agent가 1차 심사(범위 축소/단계 분할/요구사항 조정안)
|
||||||
|
3) Verifier/PM 의견 수렴 후 Main Agent 승인으로 재계획 확정
|
||||||
|
- 규칙:
|
||||||
|
- Main Agent 승인 없는 재계획은 실행 금지
|
||||||
|
- 재계획 반영 시 문서(`REQ/TASK/TEST`) 동시 갱신 필수
|
||||||
|
|
||||||
|
## Runtime Verification Protocol
|
||||||
|
|
||||||
|
- Runtime Verifier는 테스트 통과 이후 실제 동작(스테이징/실운영)을 모니터링한다.
|
||||||
|
- 이상 동작/현상 발견 시 즉시 이슈 발행:
|
||||||
|
- 제목 규칙: `[RUNTIME-VERIFY][SCN-*] ...`
|
||||||
|
- 본문 필수: 재현조건, 관측 로그, 영향 범위, 임시 완화책, 관련 `REQ/TASK/TEST`
|
||||||
|
- 이슈 클로즈 규칙:
|
||||||
|
- Dev 수정 완료 + Verifier 재검증 통과 + Runtime Verifier 재관측 정상
|
||||||
|
- 최종 클로즈 승인자는 Main Agent
|
||||||
|
|
||||||
|
## Acceptance Matrix (PM Scenario -> Dev Tasks -> Verifier Checks)
|
||||||
|
|
||||||
|
| PM Scenario | Requirement Coverage | Dev Tasks (Primary) | Verifier Checks (Must Pass) |
|
||||||
|
|---|---|---|---|
|
||||||
|
| 갭 급락/급등에서 청산 우선 처리 필요 | `REQ-V2-001`,`REQ-V2-002`,`REQ-V2-003` | `TASK-V2-004`,`TASK-CODE-001` | `TEST-ACC-000`,`TEST-ACC-001`,`TEST-ACC-010`,`TEST-CODE-001`,`TEST-CODE-002` |
|
||||||
|
| 하드스탑 + BE락 + ATR + 모델보조를 한 엔진으로 통합 | `REQ-V2-004` | `TASK-V2-005`,`TASK-V2-006`,`TASK-CODE-002` | `TEST-ACC-011` |
|
||||||
|
| 라벨 누수 없는 학습데이터 생성 | `REQ-V2-005` | `TASK-V2-007`,`TASK-CODE-004` | `TEST-ACC-012`,`TEST-CODE-003` |
|
||||||
|
| 검증 프레임워크를 시계열 누수 방지 구조로 강제 | `REQ-V2-006` | `TASK-V2-010`,`TASK-CODE-005` | `TEST-ACC-013`,`TEST-CODE-004` |
|
||||||
|
| 과낙관 백테스트 방지(비용/슬리피지/실패 강제) | `REQ-V2-007` | `TASK-V2-012`,`TASK-CODE-006` | `TEST-ACC-014` |
|
||||||
|
| 장애 시 Kill Switch 실행 순서 고정 | `REQ-V2-008` | `TASK-V2-013`,`TASK-V2-014`,`TASK-V2-015`,`TASK-CODE-003` | `TEST-ACC-002`,`TEST-ACC-018` |
|
||||||
|
| 세션 전환 단위 리스크/로그 추적 일관화 | `REQ-V3-001`,`REQ-V3-002` | `TASK-V3-001`,`TASK-V3-002`,`TASK-V3-003`,`TASK-CODE-007` | `TEST-ACC-015`,`TEST-ACC-016` |
|
||||||
|
| 블랙아웃 중 주문 차단 + 복구 후 재검증 실행 | `REQ-V3-003`,`REQ-V3-004` | `TASK-V3-004`,`TASK-V3-005`,`TASK-V3-006`,`TASK-CODE-008` | `TEST-ACC-003`,`TEST-ACC-017`,`TEST-CODE-005` |
|
||||||
|
| 저유동 세션 시장가 주문 금지 | `REQ-V3-005` | `TASK-V3-007`,`TASK-V3-008`,`TASK-CODE-009` | `TEST-ACC-004`,`TEST-CODE-006` |
|
||||||
|
| 보수적 체결 모델을 백테스트 기본으로 설정 | `REQ-V3-006` | `TASK-V3-010`,`TASK-V3-011`,`TASK-V3-012`,`TASK-CODE-010` | `TEST-ACC-005`,`TEST-CODE-007` |
|
||||||
|
| 전략손익/환율손익 분리 + 통화 버퍼 통제 | `REQ-V3-007` | `TASK-V3-013`,`TASK-V3-014`,`TASK-CODE-011` | `TEST-ACC-006`,`TEST-CODE-008` |
|
||||||
|
| 오버나잇 규칙과 Kill Switch 충돌 방지 | `REQ-V3-008` | `TASK-V3-015`,`TASK-CODE-012` | `TEST-ACC-018` |
|
||||||
|
| 타임존/정책변경/추적성 문서 거버넌스 | `REQ-OPS-001`,`REQ-OPS-002`,`REQ-OPS-003` | `TASK-OPS-001`,`TASK-OPS-002`,`TASK-OPS-003` | `TEST-ACC-007`,`TEST-ACC-008`,`TEST-ACC-009` |
|
||||||
|
|
||||||
|
## 운영 규율 (TPM Enforcement Rules)
|
||||||
|
|
||||||
|
- 어떤 PM 시나리오도 `REQ-*` 없는 구현 착수 금지.
|
||||||
|
- 어떤 `REQ-*`도 `TASK-*`,`TEST-*` 없는 승인 금지.
|
||||||
|
- Verifier는 "코드 리뷰 통과"만으로 승인 불가, 반드시 `TEST-ACC-*` 증적 필요.
|
||||||
|
- 배포 승인권자는 Phase 4 체크리스트 미충족 시 릴리즈 보류 권한을 행사해야 한다.
|
||||||
88
docs/ouroboros/60_repo_enforcement_checklist.md
Normal file
88
docs/ouroboros/60_repo_enforcement_checklist.md
Normal file
@@ -0,0 +1,88 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-OPS-002
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: tpm
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# 저장소 강제 설정 체크리스트
|
||||||
|
|
||||||
|
목표: "엄격 검증 운영"을 문서가 아니라 저장소 설정으로 강제한다.
|
||||||
|
|
||||||
|
## 1) main 브랜치 보호 (필수)
|
||||||
|
|
||||||
|
적용 항목:
|
||||||
|
- direct push 금지
|
||||||
|
- force push 금지
|
||||||
|
- branch 삭제 금지
|
||||||
|
- merge는 PR 경로만 허용
|
||||||
|
|
||||||
|
검증:
|
||||||
|
- `main`에 대해 직접 `git push origin main` 시 거부되는지 확인
|
||||||
|
|
||||||
|
## 2) 필수 상태 체크 (필수)
|
||||||
|
|
||||||
|
필수 CI 항목:
|
||||||
|
- `validate_ouroboros_docs` (명령: `python3 scripts/validate_ouroboros_docs.py`)
|
||||||
|
- `test` (명령: `pytest -q`)
|
||||||
|
|
||||||
|
설정 기준:
|
||||||
|
- 위 2개 체크가 `success` 아니면 머지 금지
|
||||||
|
- 체크 스킵/중립 상태 허용 금지
|
||||||
|
|
||||||
|
## 3) 필수 리뷰어 규칙 (권장 -> 필수)
|
||||||
|
|
||||||
|
역할 기반 승인:
|
||||||
|
- Verifier 1명 승인 필수
|
||||||
|
- TPM 또는 PM 1명 승인 필수
|
||||||
|
- Runtime Verifier 관련 변경(PR 본문에 runtime 영향 있음) 시 Runtime Verifier 승인 필수
|
||||||
|
|
||||||
|
설정 기준:
|
||||||
|
- 최소 승인 수: 2
|
||||||
|
- 작성자 self-approval 불가
|
||||||
|
- 새 커밋 푸시 시 기존 승인 재검토 요구
|
||||||
|
|
||||||
|
## 4) 워크플로우 게이트
|
||||||
|
|
||||||
|
병합 전 체크리스트:
|
||||||
|
- 이슈 연결(`Closes #N`) 존재
|
||||||
|
- PR 본문에 `REQ-*`, `TASK-*`, `TEST-*` 매핑 표 존재
|
||||||
|
- `src/core/risk_manager.py` 변경 없음
|
||||||
|
- 주요 의사결정 체크포인트(DCP-01~04) 중 해당 단계 Main Agent 확인 기록 존재
|
||||||
|
|
||||||
|
자동 점검:
|
||||||
|
- 문서 검증 스크립트 통과
|
||||||
|
- 테스트 통과
|
||||||
|
|
||||||
|
## 5) 감사 추적
|
||||||
|
|
||||||
|
필수 보존 증적:
|
||||||
|
- CI 실행 로그 링크
|
||||||
|
- 검증 실패/복구 기록
|
||||||
|
- 머지 승인 코멘트(Verifier/TPM)
|
||||||
|
|
||||||
|
분기별 점검:
|
||||||
|
- 브랜치 보호 규칙 drift 여부
|
||||||
|
- 필수 CI 이름 변경/누락 여부
|
||||||
|
|
||||||
|
## 6) 적용 순서 (운영 절차)
|
||||||
|
|
||||||
|
1. 브랜치 보호 활성화
|
||||||
|
2. 필수 CI 체크 연결
|
||||||
|
3. 리뷰어 규칙 적용
|
||||||
|
4. 샘플 PR로 거부 시나리오 테스트
|
||||||
|
5. 정상 머지 시나리오 테스트
|
||||||
|
|
||||||
|
## 7) 실패 시 조치
|
||||||
|
|
||||||
|
- 브랜치 보호 미적용 발견 시: 즉시 릴리즈 중지
|
||||||
|
- 필수 CI 우회 발견 시: 관리자 권한 점검 및 감사 이슈 발행
|
||||||
|
- 리뷰 규칙 무효화 발견 시: 규칙 복구 후 재머지 정책 시행
|
||||||
|
- Runtime 이상 이슈 미해결 상태에서 클로즈 시도 발견 시: 즉시 이슈 재오픈 + 릴리즈 중지
|
||||||
|
|
||||||
|
## 8) 재계획(Dev Replan) 운영 규칙
|
||||||
|
|
||||||
|
- Dev가 `REPLAN-REQUEST` 발행 시 TPM 심사 없이는 스코프/일정 변경 금지
|
||||||
|
- `REPLAN-REQUEST`는 Main Agent 승인 전 \"제안\" 상태로 유지
|
||||||
|
- 승인된 재계획은 `REQ/TASK/TEST` 문서를 동시 갱신해야 유효
|
||||||
39
docs/ouroboros/README.md
Normal file
39
docs/ouroboros/README.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
<!--
|
||||||
|
Doc-ID: DOC-ROOT-001
|
||||||
|
Version: 1.0.0
|
||||||
|
Status: active
|
||||||
|
Owner: strategy
|
||||||
|
Updated: 2026-02-26
|
||||||
|
-->
|
||||||
|
|
||||||
|
# The Ouroboros 실행 문서 허브
|
||||||
|
|
||||||
|
이 폴더는 `ouroboros_plan_v2.txt`, `ouroboros_plan_v3.txt`를 구현 가능한 작업 지시서 수준으로 분해한 문서 허브다.
|
||||||
|
|
||||||
|
## 읽기 순서 (Routing)
|
||||||
|
|
||||||
|
1. 검증 체계부터 확정: [00_validation_system.md](./00_validation_system.md)
|
||||||
|
2. 단일 진실원장(요구사항): [01_requirements_registry.md](./01_requirements_registry.md)
|
||||||
|
3. v2 실행 지시서: [10_phase_v2_execution.md](./10_phase_v2_execution.md)
|
||||||
|
4. v3 실행 지시서: [20_phase_v3_execution.md](./20_phase_v3_execution.md)
|
||||||
|
5. 코드 레벨 작업 지시: [30_code_level_work_orders.md](./30_code_level_work_orders.md)
|
||||||
|
6. 수용 기준/테스트 계획: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)
|
||||||
|
7. PM 시나리오/이슈 분류: [50_scenario_matrix_and_issue_taxonomy.md](./50_scenario_matrix_and_issue_taxonomy.md)
|
||||||
|
8. TPM 제어 프로토콜/수용 매트릭스: [50_tpm_control_protocol.md](./50_tpm_control_protocol.md)
|
||||||
|
9. 저장소 강제 설정 체크리스트: [60_repo_enforcement_checklist.md](./60_repo_enforcement_checklist.md)
|
||||||
|
|
||||||
|
## 운영 규칙
|
||||||
|
|
||||||
|
- 계획 변경은 반드시 `01_requirements_registry.md`의 ID 정의부터 수정한다.
|
||||||
|
- 구현 문서는 원장 ID만 참조하고 자체 숫자/정책을 새로 만들지 않는다.
|
||||||
|
- 문서 품질 룰셋(`RULE-DOC-001` `RULE-DOC-002` `RULE-DOC-003` `RULE-DOC-004` `RULE-DOC-005` `RULE-DOC-006`)은 [00_validation_system.md](./00_validation_system.md)를 기준으로 적용한다.
|
||||||
|
- 문서 병합 전 아래 검증을 통과해야 한다.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 scripts/validate_ouroboros_docs.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## 원본 계획 문서
|
||||||
|
|
||||||
|
- [v2](/home/agentson/repos/The-Ouroboros/ouroboros_plan_v2.txt)
|
||||||
|
- [v3](/home/agentson/repos/The-Ouroboros/ouroboros_plan_v3.txt)
|
||||||
@@ -13,6 +13,57 @@
|
|||||||
|
|
||||||
**Never commit directly to `main`.** This policy applies to all changes, no exceptions.
|
**Never commit directly to `main`.** This policy applies to all changes, no exceptions.
|
||||||
|
|
||||||
|
## Gitea CLI Formatting Troubleshooting
|
||||||
|
|
||||||
|
Issue/PR 본문 작성 시 줄바꿈(`\n`)이 문자열 그대로 저장되는 문제가 반복될 수 있다. 원인은 `-d "...\n..."` 형태에서 쉘/CLI가 이스케이프를 실제 개행으로 해석하지 않기 때문이다.
|
||||||
|
|
||||||
|
권장 패턴:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ISSUE_BODY=$(cat <<'EOF'
|
||||||
|
## Summary
|
||||||
|
- 변경 내용 1
|
||||||
|
- 변경 내용 2
|
||||||
|
|
||||||
|
## Why
|
||||||
|
- 배경 1
|
||||||
|
- 배경 2
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
- 포함 범위
|
||||||
|
- 제외 범위
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
|
||||||
|
tea issues create \
|
||||||
|
-t "docs: 제목" \
|
||||||
|
-d "$ISSUE_BODY"
|
||||||
|
```
|
||||||
|
|
||||||
|
PR도 동일하게 적용:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
PR_BODY=$(cat <<'EOF'
|
||||||
|
## Summary
|
||||||
|
- ...
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
- python3 scripts/validate_ouroboros_docs.py
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
|
||||||
|
tea pr create \
|
||||||
|
--base main \
|
||||||
|
--head feature/issue-N-something \
|
||||||
|
--title "docs: ... (#N)" \
|
||||||
|
--description "$PR_BODY"
|
||||||
|
```
|
||||||
|
|
||||||
|
금지 패턴:
|
||||||
|
|
||||||
|
- `-d "line1\nline2"` (웹 UI에 `\n` 문자 그대로 노출될 수 있음)
|
||||||
|
- 본문에 백틱/괄호를 인라인로 넣고 적절한 quoting 없이 즉시 실행
|
||||||
|
|
||||||
## Agent Workflow
|
## Agent Workflow
|
||||||
|
|
||||||
**Modern AI development leverages specialized agents for concurrent, efficient task execution.**
|
**Modern AI development leverages specialized agents for concurrent, efficient task execution.**
|
||||||
|
|||||||
165
ouroboros_plan_v2.txt
Normal file
165
ouroboros_plan_v2.txt
Normal file
@@ -0,0 +1,165 @@
|
|||||||
|
[The Ouroboros] 운영/전략 계획서 v2
|
||||||
|
작성일: 2026-02-26
|
||||||
|
상태: 코드 구현 전 설계안(전략/검증 중심)
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
0) 목적
|
||||||
|
==================================================
|
||||||
|
고정 익절(+3%) 중심 로직에서 벗어나, 다음을 만족하는 실전형 청산 체계로 전환한다.
|
||||||
|
- 수익 구간 보호 (손익 역전 방지)
|
||||||
|
- 변동성 적응형 청산
|
||||||
|
- 예측 모델의 확률 신호를 보조적으로 결합
|
||||||
|
- 과적합 방지를 최우선으로 한 검증 프레임워크
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
1) 핵심 설계 원칙
|
||||||
|
==================================================
|
||||||
|
1. 예측 성능과 전략 성능을 분리 평가
|
||||||
|
- 예측 성능: PR-AUC, Brier, Calibration
|
||||||
|
- 전략 성능: Net PnL, Sharpe, MDD, Profit Factor, Turnover
|
||||||
|
|
||||||
|
2. 시계열 검증 규율 강제
|
||||||
|
- Walk-forward 분할
|
||||||
|
- Purge/Embargo 적용
|
||||||
|
- Random split 금지
|
||||||
|
|
||||||
|
3. 실거래 리얼리즘 우선
|
||||||
|
- 거래비용/슬리피지/체결실패 반영 없는 백테스트 결과는 채택 금지
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
2) 매도 상태기계 (State Machine)
|
||||||
|
==================================================
|
||||||
|
상태:
|
||||||
|
- HOLDING
|
||||||
|
- BE_LOCK
|
||||||
|
- ARMED
|
||||||
|
- EXITED
|
||||||
|
|
||||||
|
정의:
|
||||||
|
- HOLDING: 일반 보유 상태
|
||||||
|
- BE_LOCK: 일정 수익권 진입 시 손절선을 본전(또는 비용 반영 본전)으로 상향
|
||||||
|
- ARMED: 추세 추적(피크 추적) 기반 청산 준비 상태
|
||||||
|
- EXITED: 청산 완료
|
||||||
|
|
||||||
|
전이 규칙(개념):
|
||||||
|
- HOLDING -> BE_LOCK: unrealized_pnl_pct >= be_arm_pct
|
||||||
|
- BE_LOCK -> ARMED: unrealized_pnl_pct >= arm_pct
|
||||||
|
- ARMED -> EXITED: 아래 조건 중 하나 충족
|
||||||
|
1) hard stop 도달
|
||||||
|
2) trailing stop 도달 (peak 대비 하락)
|
||||||
|
3) 모델 하락확률 + 유동성 약화 조건 충족
|
||||||
|
|
||||||
|
상태 전이 구현 규칙(필수):
|
||||||
|
- 매 틱/바 평가 시 "현재 조건이 허용하는 최상위 상태"로 즉시 승격
|
||||||
|
- 순차 if-else로 인한 전이 누락 금지 (예: 갭으로 BE_LOCK/ARMED 동시 충족)
|
||||||
|
- EXITED 조건은 모든 상태보다 우선 평가
|
||||||
|
- 상태 전이 로그에 이전/이후 상태, 전이 사유, 기준 가격/수익률 기록
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
3) 청산 로직 구성 (4중 안전장치)
|
||||||
|
==================================================
|
||||||
|
A. Hard Stop
|
||||||
|
- 계좌/포지션 보호용 절대 하한
|
||||||
|
- 항상 활성화
|
||||||
|
|
||||||
|
B. Dynamic Stop (Break-even Lock)
|
||||||
|
- BE_LOCK 진입 시 손절선을 본전 이상으로 상향
|
||||||
|
- "수익 포지션이 손실로 반전"되는 구조적 리스크 차단
|
||||||
|
|
||||||
|
C. ATR 기반 Trailing Stop
|
||||||
|
- 고정 trail_pct 대신 변동성 적응형 사용
|
||||||
|
- 예시: ExitPrice = PeakPrice - (k * ATR)
|
||||||
|
|
||||||
|
D. 모델 확률 신호
|
||||||
|
- 하락전환 확률(pred_prob)이 임계값 이상일 때 청산 가중
|
||||||
|
- 단독 트리거가 아닌 trailing/리스크 룰 보조 트리거로 사용
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
4) 라벨링 체계 (Triple Barrier)
|
||||||
|
==================================================
|
||||||
|
목표:
|
||||||
|
고정 H-window 라벨 편향을 줄이고, 금융 시계열의 경로 의존성을 반영한다.
|
||||||
|
|
||||||
|
라벨 정의:
|
||||||
|
- Upper barrier (익절)
|
||||||
|
- Lower barrier (손절)
|
||||||
|
- Time barrier (만기)
|
||||||
|
|
||||||
|
규칙:
|
||||||
|
- 세 장벽 중 "먼저 터치한 장벽"으로 라벨 확정
|
||||||
|
- 라벨은 entry 시점 이후 데이터만 사용해 생성
|
||||||
|
- 피처 생성 구간과 라벨 구간을 엄격 분리해 look-ahead bias 방지
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
5) 검증 프레임워크
|
||||||
|
==================================================
|
||||||
|
5.1 분할 방식
|
||||||
|
- Fold 단위 Walk-forward
|
||||||
|
- Purge/Embargo로 인접 샘플 누수 차단
|
||||||
|
|
||||||
|
5.2 비교군(Baseline) 구조
|
||||||
|
- B0: 기존 고정 손절/익절
|
||||||
|
- B1: 모델 없는 trailing only
|
||||||
|
- M1: trailing + 모델 확률 결합
|
||||||
|
|
||||||
|
5.3 채택 기준
|
||||||
|
- M1이 B0/B1 대비 OOS(Out-of-sample)에서 일관된 우위
|
||||||
|
- 단일 구간 성과가 아닌 fold 분포 기준으로 판단
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
6) 실행 아키텍처 원칙
|
||||||
|
==================================================
|
||||||
|
1. 저지연 실행 경로
|
||||||
|
- 실시간 청산 판단은 경량 엔진(룰/GBDT) 담당
|
||||||
|
- LLM은 레짐 판단/비중 조절/상위 의사결정 보조
|
||||||
|
|
||||||
|
2. 체결 현실 반영
|
||||||
|
- 세션 유동성에 따른 슬리피지 페널티 차등 적용
|
||||||
|
- 미체결/재호가/재접수 시나리오를 백테스트에 반영
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
7) 운영 리스크 관리
|
||||||
|
==================================================
|
||||||
|
승격 단계:
|
||||||
|
- Offline backtest -> Paper shadow -> Small-capital live
|
||||||
|
|
||||||
|
중단(Kill Switch):
|
||||||
|
- rolling Sharpe 악화
|
||||||
|
- MDD 한도 초과
|
||||||
|
- 체결 실패율/슬리피지 급등
|
||||||
|
|
||||||
|
Kill Switch 실행 순서(원자적):
|
||||||
|
1) 모든 신규 주문 차단 플래그 ON
|
||||||
|
2) 모든 미체결 주문 취소 요청
|
||||||
|
3) 취소 결과 재조회(실패 건 재시도)
|
||||||
|
4) 포지션 리스크 재계산 후 강제 축소/청산 판단
|
||||||
|
5) 상태/로그 스냅샷 저장 및 운영 경보 발송
|
||||||
|
|
||||||
|
원칙:
|
||||||
|
- 모델이 실패해도 hard stop 기반 보수 모드로 즉시 디그레이드 가능해야 함
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
8) 고정 파라미터(초기안)
|
||||||
|
==================================================
|
||||||
|
(15분봉 단기 스윙 기준 제안)
|
||||||
|
- KR: be_arm_pct=1.2, arm_pct=2.8, atr_period=14, atr_multiplier_k=2.2,
|
||||||
|
time_barrier_bars=26, p_thresh=0.62
|
||||||
|
- US: be_arm_pct=1.0, arm_pct=2.4, atr_period=14, atr_multiplier_k=2.0,
|
||||||
|
time_barrier_bars=32, p_thresh=0.60
|
||||||
|
|
||||||
|
민감도 범위(초기 탐색):
|
||||||
|
- be_arm_pct: KR 0.9~1.8 / US 0.7~1.5
|
||||||
|
- arm_pct: KR 2.2~3.8 / US 1.8~3.2
|
||||||
|
- atr_multiplier_k: KR 1.8~2.8 / US 1.6~2.4
|
||||||
|
- time_barrier_bars: KR 20~36 / US 24~48
|
||||||
|
- p_thresh: 0.55~0.70
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
9) 구현 전 체크리스트
|
||||||
|
==================================================
|
||||||
|
- 파라미터 튜닝 시 nested leakage 방지
|
||||||
|
- 수수료/세금/슬리피지 전부 반영 여부 확인
|
||||||
|
- 세션/타임존/DST 처리 일관성 확인
|
||||||
|
- 모델 버전/설정 해시/실험 로그 재현성 확보
|
||||||
|
|
||||||
|
끝.
|
||||||
185
ouroboros_plan_v3.txt
Normal file
185
ouroboros_plan_v3.txt
Normal file
@@ -0,0 +1,185 @@
|
|||||||
|
[The Ouroboros] 운영확장 v3
|
||||||
|
작성일: 2026-02-26
|
||||||
|
상태: v2 확장판 / 야간·프리마켓 포함 글로벌 세션 운영 설계안
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
0) 목적
|
||||||
|
==================================================
|
||||||
|
"24시간 무중단 자산 증식" 비전을 위해 거래 세션 범위를 KR 정규장 중심에서
|
||||||
|
NXT/미국 확장 세션까지 확대한다. 핵심은 다음 3가지다.
|
||||||
|
- 세션 인지형 의사결정
|
||||||
|
- 세션별 리스크/비용 차등 적용
|
||||||
|
- 시간장벽의 현실적 재정의
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
1) 세션 모델 (Session-aware Engine)
|
||||||
|
==================================================
|
||||||
|
KR 세션:
|
||||||
|
- NXT_PRE : 08:00 ~ 08:50 (KST)
|
||||||
|
- KRX_REG : 09:00 ~ 15:30 (KST)
|
||||||
|
- NXT_AFTER : 15:30 ~ 20:00 (KST)
|
||||||
|
|
||||||
|
US 세션(KST 관점 운영):
|
||||||
|
- US_DAY : 10:00 ~ 18:00
|
||||||
|
- US_PRE : 18:00 ~ 23:30
|
||||||
|
- US_REG : 23:30 ~ 06:00
|
||||||
|
- US_AFTER : 06:00 ~ 07:00
|
||||||
|
|
||||||
|
원칙:
|
||||||
|
- 모든 피처/신호/주문/로그에 session_id를 명시적으로 포함
|
||||||
|
- 세션 전환 시 상태 업데이트 및 리스크 파라미터 재로딩
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
2) 캘린더/휴장/DST 고정 소스
|
||||||
|
==================================================
|
||||||
|
KR:
|
||||||
|
- 기본: pykrx 또는 FinanceDataReader (KRX 기준)
|
||||||
|
- 예외: 연휴/임시 휴장/NXT 특이 운영은 KIS 공지 기반 보완
|
||||||
|
|
||||||
|
US:
|
||||||
|
- pandas_market_calendars (NYSE 기준)
|
||||||
|
- 2026 DST:
|
||||||
|
- 시작: 2026-03-08
|
||||||
|
- 종료: 2026-11-01
|
||||||
|
|
||||||
|
정합성 규칙:
|
||||||
|
- 스케줄 충돌 시 "거래소 캘린더 > 로컬 추정" 우선
|
||||||
|
- 시장 상태(open/close/half-day)는 주문 엔진 진입 전 최종 검증
|
||||||
|
|
||||||
|
KIS 점검시간 회피 정책(필수):
|
||||||
|
- 브로커 점검/장애 블랙아웃 윈도우는 운영 설정으로 별도 관리
|
||||||
|
- 블랙아웃 구간에는 신규 주문 전송 금지, 취소/정정도 정책적으로 제한
|
||||||
|
- 신호는 유지하되 주문 의도는 Queue에 적재, 복구 후 유효성 재검증 뒤 실행
|
||||||
|
- 복구 직후에는 잔고/미체결/체결내역을 우선 동기화한 뒤 주문 엔진 재가동
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
3) 시간장벽 재정의
|
||||||
|
==================================================
|
||||||
|
v2의 time_barrier_bars 고정값을 v3에서 다음으로 확장:
|
||||||
|
- max_holding_minutes (시장별 기본 만기)
|
||||||
|
- 봉 개수는 세션 길이/간격으로 동적 계산
|
||||||
|
|
||||||
|
기본값:
|
||||||
|
- KR: max_holding_minutes = 2160 (약 3거래일, NXT 포함 관점)
|
||||||
|
- US: max_holding_minutes = 4320 (약 72시간)
|
||||||
|
|
||||||
|
운영 주의:
|
||||||
|
- 고정 "일중 청산"보다 "포지션 유지 시간" 기준 만기 적용
|
||||||
|
- 세션 종료 강제청산 규칙과 충돌 시 우선순위 명시 필요
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
4) 세션별 비용/슬리피지 모델 (보수적)
|
||||||
|
==================================================
|
||||||
|
KRX_REG:
|
||||||
|
- 슬리피지: 2~3틱 (약 0.05%)
|
||||||
|
- 수수료+세금: 0.20% ~ 0.23%
|
||||||
|
|
||||||
|
NXT_AFTER:
|
||||||
|
- 슬리피지: 5~8틱 (약 0.15%)
|
||||||
|
- 수수료+세금: 0.20% ~ 0.23%
|
||||||
|
|
||||||
|
US_REG:
|
||||||
|
- 슬리피지: 2~3틱 (약 0.03%)
|
||||||
|
- 수수료+기타 비용: 0.07% ~ 0.15%
|
||||||
|
|
||||||
|
US_PRE / US_DAY:
|
||||||
|
- 슬리피지: 10틱+ (약 0.3% ~ 0.5%)
|
||||||
|
- 수수료+기타 비용: 0.07% ~ 0.15%
|
||||||
|
|
||||||
|
원칙:
|
||||||
|
- 백테스트 체결가는 세션별 보수 가정 적용
|
||||||
|
- 저유동 세션은 자동 보수 모드(p_thresh 상향, atr_k 상향) 권장
|
||||||
|
- 백테스트 체결가 기본은 "불리한 방향 체결" 가정 (단순 close 체결 금지)
|
||||||
|
|
||||||
|
세션별 주문 유형 강제(필수):
|
||||||
|
- KRX_REG / US_REG: 지정가 우선, 시장가 제한적 허용
|
||||||
|
- NXT_AFTER / US_PRE / US_DAY / US_AFTER: 시장가 금지
|
||||||
|
- 저유동 세션은 최우선 지정가 또는 IOC/FOK(가격 보호 한도 포함)만 허용
|
||||||
|
- 주문 실패 시 재호가 간격/횟수 상한을 두고, 초과 시 주문 철회
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
5) 포지션/잔고 통합 규칙 (KIS 특성 반영)
|
||||||
|
==================================================
|
||||||
|
문제:
|
||||||
|
- KRX/NXT 잔고 조회가 venue 단위로 분리되거나 반영 지연 가능
|
||||||
|
|
||||||
|
규칙:
|
||||||
|
- 종목 식별은 동일 종목코드(또는 ISIN) 기준 통합 포지션으로 관리
|
||||||
|
- 다만 주문 가능 수량은 venue별 API 응답을 최종 기준으로 사용
|
||||||
|
- 매도 가능 수량 검증은 주문 직전 재조회로 확정
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
6) 마감 강제청산/오버나잇 예외 규칙
|
||||||
|
==================================================
|
||||||
|
기본 원칙:
|
||||||
|
- 모든 포지션에 대해 세션 종료 10분 전 REDUCE_ALL 검토
|
||||||
|
|
||||||
|
오버나잇 예외 허용 (모두 충족 시):
|
||||||
|
1) ARMED 상태 (예: +2.8% 이상)
|
||||||
|
2) 모델 하락확률 < 0.30
|
||||||
|
3) 포트폴리오 현금 비중 >= 50%
|
||||||
|
|
||||||
|
갭 리스크 통제:
|
||||||
|
- 다음 개장 시 hard stop를 시가 기준으로 재산정
|
||||||
|
- 조건 위반 시 즉시 청산 우선
|
||||||
|
|
||||||
|
Kill Switch 연동:
|
||||||
|
- MDD/실패율 임계치 초과 시 "미체결 전량 취소 -> 신규 주문 차단 -> 리스크 축소" 순서 강제
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
7) 데이터 저장/용량 정책
|
||||||
|
==================================================
|
||||||
|
핵심 테이블(계획):
|
||||||
|
- feature_snapshots
|
||||||
|
- position_states
|
||||||
|
- model_predictions
|
||||||
|
|
||||||
|
저장 규칙:
|
||||||
|
- feature_hash 기반 중복 제거
|
||||||
|
- 가격 변화가 작아도 session_id 변경 시 강제 스냅샷
|
||||||
|
- 월 단위 DB 로테이션 권장 (예: trading_YYYY_MM.db)
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
8) 환율/정산 리스크 정책 (US 필수)
|
||||||
|
==================================================
|
||||||
|
원칙:
|
||||||
|
- USD 노출은 전략 손익과 별도로 환율 손익을 분리 추적
|
||||||
|
- 원화 주문 서비스 사용 시 가환율 체결/익일 정산 리스크를 예수금 규칙에 반영
|
||||||
|
|
||||||
|
운영 규칙:
|
||||||
|
- 환전 시점 정책(사전 환전/수시 환전)을 고정하고 로그에 기록
|
||||||
|
- 최소 USD 버퍼와 KRW 버퍼를 각각 설정해 주문 가능금 부족 리스크 완화
|
||||||
|
- 환율 급변 구간에는 포지션 한도 축소 또는 신규 진입 제한
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
9) v3 실험 매트릭스 (우선 3선)
|
||||||
|
==================================================
|
||||||
|
EXP-KR-01:
|
||||||
|
- 시장: KR
|
||||||
|
- 포커스: NXT 야간 특화
|
||||||
|
- 제안: time barrier 확장(예: 48 bars 상당), p_thresh 상향(0.65)
|
||||||
|
|
||||||
|
EXP-US-01:
|
||||||
|
- 시장: US
|
||||||
|
- 포커스: 21h 준연속 운용
|
||||||
|
- 제안: time barrier 확장(예: 80 bars 상당), atr_k 상향(2.5)
|
||||||
|
|
||||||
|
EXP-HYB-01:
|
||||||
|
- 시장: Global
|
||||||
|
- 포커스: KR 낮 + US 밤 연계
|
||||||
|
- 제안: 레짐 기반 자산배분 자동조절
|
||||||
|
|
||||||
|
==================================================
|
||||||
|
10) 코드 착수 전 최종 확정 체크
|
||||||
|
==================================================
|
||||||
|
1) 세션별 공식 캘린더 소스/우선순위
|
||||||
|
2) 세션별 슬리피지/비용 테이블 수치
|
||||||
|
3) 시장별 max_holding_minutes
|
||||||
|
4) 마감 강제청산 예외 조건 임계값
|
||||||
|
5) 블랙아웃(점검/장애) 시간대와 주문 큐 처리 규칙
|
||||||
|
6) 세션별 허용 주문 유형(시장가 허용 범위 포함)
|
||||||
|
7) 환전/정산 정책 및 통화 버퍼 임계값
|
||||||
|
|
||||||
|
모든 항목 확정 후 Step 1 구현(코드)로 이동.
|
||||||
|
|
||||||
|
끝.
|
||||||
140
scripts/validate_ouroboros_docs.py
Executable file
140
scripts/validate_ouroboros_docs.py
Executable file
@@ -0,0 +1,140 @@
|
|||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Validate Ouroboros planning docs for metadata, links, and ID consistency."""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import re
|
||||||
|
import sys
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
DOC_DIR = Path("docs/ouroboros")
|
||||||
|
META_PATTERN = re.compile(
|
||||||
|
r"<!--\n"
|
||||||
|
r"Doc-ID: (?P<doc_id>[^\n]+)\n"
|
||||||
|
r"Version: (?P<version>[^\n]+)\n"
|
||||||
|
r"Status: (?P<status>[^\n]+)\n"
|
||||||
|
r"Owner: (?P<owner>[^\n]+)\n"
|
||||||
|
r"Updated: (?P<updated>\d{4}-\d{2}-\d{2})\n"
|
||||||
|
r"-->",
|
||||||
|
re.MULTILINE,
|
||||||
|
)
|
||||||
|
ID_PATTERN = re.compile(r"\b(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3}\b")
|
||||||
|
DEF_PATTERN = re.compile(r"^-\s+`(?P<id>(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3})`", re.MULTILINE)
|
||||||
|
LINK_PATTERN = re.compile(r"\[[^\]]+\]\((?P<link>[^)]+)\)")
|
||||||
|
LINE_DEF_PATTERN = re.compile(r"^-\s+`(?P<id>(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3})`.*$", re.MULTILINE)
|
||||||
|
|
||||||
|
|
||||||
|
def iter_docs() -> list[Path]:
|
||||||
|
return sorted([p for p in DOC_DIR.glob("*.md") if p.is_file()])
|
||||||
|
|
||||||
|
|
||||||
|
def validate_metadata(path: Path, text: str, errors: list[str], doc_ids: dict[str, Path]) -> None:
|
||||||
|
match = META_PATTERN.search(text)
|
||||||
|
if not match:
|
||||||
|
errors.append(f"{path}: missing or malformed metadata block")
|
||||||
|
return
|
||||||
|
doc_id = match.group("doc_id").strip()
|
||||||
|
if doc_id in doc_ids:
|
||||||
|
errors.append(f"{path}: duplicate Doc-ID {doc_id} (already in {doc_ids[doc_id]})")
|
||||||
|
else:
|
||||||
|
doc_ids[doc_id] = path
|
||||||
|
|
||||||
|
|
||||||
|
def validate_links(path: Path, text: str, errors: list[str]) -> None:
|
||||||
|
for m in LINK_PATTERN.finditer(text):
|
||||||
|
link = m.group("link").strip()
|
||||||
|
if not link or link.startswith("http") or link.startswith("#"):
|
||||||
|
continue
|
||||||
|
if link.startswith("/"):
|
||||||
|
target = Path(link)
|
||||||
|
else:
|
||||||
|
target = (path.parent / link).resolve()
|
||||||
|
if not target.exists():
|
||||||
|
errors.append(f"{path}: broken link -> {link}")
|
||||||
|
|
||||||
|
|
||||||
|
def collect_ids(path: Path, text: str, defs: dict[str, Path], refs: dict[str, set[Path]]) -> None:
|
||||||
|
for m in DEF_PATTERN.finditer(text):
|
||||||
|
defs[m.group("id")] = path
|
||||||
|
for m in ID_PATTERN.finditer(text):
|
||||||
|
idv = m.group(0)
|
||||||
|
refs.setdefault(idv, set()).add(path)
|
||||||
|
|
||||||
|
|
||||||
|
def collect_req_traceability(text: str, req_to_task: dict[str, set[str]], req_to_test: dict[str, set[str]]) -> None:
|
||||||
|
for m in LINE_DEF_PATTERN.finditer(text):
|
||||||
|
line = m.group(0)
|
||||||
|
item_id = m.group("id")
|
||||||
|
req_ids = [rid for rid in ID_PATTERN.findall(line) if rid.startswith("REQ-")]
|
||||||
|
if item_id.startswith("TASK-"):
|
||||||
|
for req_id in req_ids:
|
||||||
|
req_to_task.setdefault(req_id, set()).add(item_id)
|
||||||
|
if item_id.startswith("TEST-"):
|
||||||
|
for req_id in req_ids:
|
||||||
|
req_to_test.setdefault(req_id, set()).add(item_id)
|
||||||
|
|
||||||
|
|
||||||
|
def main() -> int:
|
||||||
|
if not DOC_DIR.exists():
|
||||||
|
print(f"ERROR: missing directory {DOC_DIR}")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
docs = iter_docs()
|
||||||
|
if not docs:
|
||||||
|
print(f"ERROR: no markdown docs found in {DOC_DIR}")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
errors: list[str] = []
|
||||||
|
doc_ids: dict[str, Path] = {}
|
||||||
|
defs: dict[str, Path] = {}
|
||||||
|
refs: dict[str, set[Path]] = {}
|
||||||
|
req_to_task: dict[str, set[str]] = {}
|
||||||
|
req_to_test: dict[str, set[str]] = {}
|
||||||
|
|
||||||
|
for path in docs:
|
||||||
|
text = path.read_text(encoding="utf-8")
|
||||||
|
validate_metadata(path, text, errors, doc_ids)
|
||||||
|
validate_links(path, text, errors)
|
||||||
|
collect_ids(path, text, defs, refs)
|
||||||
|
collect_req_traceability(text, req_to_task, req_to_test)
|
||||||
|
|
||||||
|
for idv, where_used in sorted(refs.items()):
|
||||||
|
if idv.startswith("DOC-"):
|
||||||
|
continue
|
||||||
|
if idv not in defs:
|
||||||
|
files = ", ".join(str(p) for p in sorted(where_used))
|
||||||
|
errors.append(f"undefined ID {idv}, used in: {files}")
|
||||||
|
|
||||||
|
for idv in sorted(defs):
|
||||||
|
if not idv.startswith("REQ-"):
|
||||||
|
continue
|
||||||
|
if idv not in req_to_task:
|
||||||
|
errors.append(f"REQ without TASK mapping: {idv}")
|
||||||
|
if idv not in req_to_test:
|
||||||
|
errors.append(f"REQ without TEST mapping: {idv}")
|
||||||
|
|
||||||
|
warnings: list[str] = []
|
||||||
|
for idv, where_def in sorted(defs.items()):
|
||||||
|
if len(refs.get(idv, set())) <= 1 and (idv.startswith("REQ-") or idv.startswith("RULE-")):
|
||||||
|
warnings.append(f"orphan ID {idv} defined in {where_def} (not referenced elsewhere)")
|
||||||
|
|
||||||
|
if errors:
|
||||||
|
print("[FAIL] Ouroboros docs validation failed")
|
||||||
|
for err in errors:
|
||||||
|
print(f"- {err}")
|
||||||
|
return 1
|
||||||
|
|
||||||
|
print(f"[OK] validated {len(docs)} docs in {DOC_DIR}")
|
||||||
|
print(f"[OK] unique Doc-ID: {len(doc_ids)}")
|
||||||
|
print(f"[OK] definitions: {len(defs)}, references: {len(refs)}")
|
||||||
|
print(f"[OK] req->task mappings: {len(req_to_task)}")
|
||||||
|
print(f"[OK] req->test mappings: {len(req_to_test)}")
|
||||||
|
if warnings:
|
||||||
|
print(f"[WARN] orphan IDs: {len(warnings)}")
|
||||||
|
for w in warnings:
|
||||||
|
print(f"- {w}")
|
||||||
|
return 0
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
sys.exit(main())
|
||||||
@@ -222,6 +222,59 @@ class OverseasBroker:
|
|||||||
f"Network error fetching overseas balance: {exc}"
|
f"Network error fetching overseas balance: {exc}"
|
||||||
) from exc
|
) from exc
|
||||||
|
|
||||||
|
async def get_overseas_buying_power(
|
||||||
|
self,
|
||||||
|
exchange_code: str,
|
||||||
|
stock_code: str,
|
||||||
|
price: float,
|
||||||
|
) -> dict[str, Any]:
|
||||||
|
"""
|
||||||
|
Fetch overseas buying power for a specific stock and price.
|
||||||
|
|
||||||
|
Args:
|
||||||
|
exchange_code: Exchange code (e.g., "NASD", "NYSE")
|
||||||
|
stock_code: Stock ticker symbol
|
||||||
|
price: Current stock price (used for quantity calculation)
|
||||||
|
|
||||||
|
Returns:
|
||||||
|
API response; key field: output.ord_psbl_frcr_amt (주문가능외화금액)
|
||||||
|
|
||||||
|
Raises:
|
||||||
|
ConnectionError: On network or API errors
|
||||||
|
"""
|
||||||
|
await self._broker._rate_limiter.acquire()
|
||||||
|
session = self._broker._get_session()
|
||||||
|
|
||||||
|
# TR_ID: 실전 TTTS3007R, 모의 VTTS3007R
|
||||||
|
# Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 매수가능금액조회' 시트
|
||||||
|
ps_tr_id = (
|
||||||
|
"TTTS3007R" if self._broker._settings.MODE == "live" else "VTTS3007R"
|
||||||
|
)
|
||||||
|
headers = await self._broker._auth_headers(ps_tr_id)
|
||||||
|
params = {
|
||||||
|
"CANO": self._broker._account_no,
|
||||||
|
"ACNT_PRDT_CD": self._broker._product_cd,
|
||||||
|
"OVRS_EXCG_CD": exchange_code,
|
||||||
|
"OVRS_ORD_UNPR": f"{price:.2f}",
|
||||||
|
"ITEM_CD": stock_code,
|
||||||
|
}
|
||||||
|
url = (
|
||||||
|
f"{self._broker._base_url}/uapi/overseas-stock/v1/trading/inquire-psamount"
|
||||||
|
)
|
||||||
|
|
||||||
|
try:
|
||||||
|
async with session.get(url, headers=headers, params=params) as resp:
|
||||||
|
if resp.status != 200:
|
||||||
|
text = await resp.text()
|
||||||
|
raise ConnectionError(
|
||||||
|
f"get_overseas_buying_power failed ({resp.status}): {text}"
|
||||||
|
)
|
||||||
|
return await resp.json()
|
||||||
|
except (TimeoutError, aiohttp.ClientError) as exc:
|
||||||
|
raise ConnectionError(
|
||||||
|
f"Network error fetching overseas buying power: {exc}"
|
||||||
|
) from exc
|
||||||
|
|
||||||
async def send_overseas_order(
|
async def send_overseas_order(
|
||||||
self,
|
self,
|
||||||
exchange_code: str,
|
exchange_code: str,
|
||||||
|
|||||||
71
src/core/kill_switch.py
Normal file
71
src/core/kill_switch.py
Normal file
@@ -0,0 +1,71 @@
|
|||||||
|
"""Kill switch orchestration for emergency risk actions.
|
||||||
|
|
||||||
|
Order is fixed:
|
||||||
|
1) block new orders
|
||||||
|
2) cancel pending orders
|
||||||
|
3) refresh order state
|
||||||
|
4) reduce risk
|
||||||
|
5) snapshot and notify
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import inspect
|
||||||
|
from dataclasses import dataclass, field
|
||||||
|
from typing import Any, Awaitable, Callable
|
||||||
|
|
||||||
|
StepCallable = Callable[[], Any | Awaitable[Any]]
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass
|
||||||
|
class KillSwitchReport:
|
||||||
|
reason: str
|
||||||
|
steps: list[str] = field(default_factory=list)
|
||||||
|
errors: list[str] = field(default_factory=list)
|
||||||
|
|
||||||
|
|
||||||
|
class KillSwitchOrchestrator:
|
||||||
|
def __init__(self) -> None:
|
||||||
|
self.new_orders_blocked = False
|
||||||
|
|
||||||
|
async def _run_step(
|
||||||
|
self,
|
||||||
|
report: KillSwitchReport,
|
||||||
|
name: str,
|
||||||
|
fn: StepCallable | None,
|
||||||
|
) -> None:
|
||||||
|
report.steps.append(name)
|
||||||
|
if fn is None:
|
||||||
|
return
|
||||||
|
try:
|
||||||
|
result = fn()
|
||||||
|
if inspect.isawaitable(result):
|
||||||
|
await result
|
||||||
|
except Exception as exc: # pragma: no cover - intentionally resilient
|
||||||
|
report.errors.append(f"{name}: {exc}")
|
||||||
|
|
||||||
|
async def trigger(
|
||||||
|
self,
|
||||||
|
*,
|
||||||
|
reason: str,
|
||||||
|
cancel_pending_orders: StepCallable | None = None,
|
||||||
|
refresh_order_state: StepCallable | None = None,
|
||||||
|
reduce_risk: StepCallable | None = None,
|
||||||
|
snapshot_state: StepCallable | None = None,
|
||||||
|
notify: StepCallable | None = None,
|
||||||
|
) -> KillSwitchReport:
|
||||||
|
report = KillSwitchReport(reason=reason)
|
||||||
|
|
||||||
|
self.new_orders_blocked = True
|
||||||
|
report.steps.append("block_new_orders")
|
||||||
|
|
||||||
|
await self._run_step(report, "cancel_pending_orders", cancel_pending_orders)
|
||||||
|
await self._run_step(report, "refresh_order_state", refresh_order_state)
|
||||||
|
await self._run_step(report, "reduce_risk", reduce_risk)
|
||||||
|
await self._run_step(report, "snapshot_state", snapshot_state)
|
||||||
|
await self._run_step(report, "notify", notify)
|
||||||
|
|
||||||
|
return report
|
||||||
|
|
||||||
|
def clear_block(self) -> None:
|
||||||
|
self.new_orders_blocked = False
|
||||||
@@ -258,6 +258,7 @@ def get_open_position(
|
|||||||
FROM trades
|
FROM trades
|
||||||
WHERE stock_code = ?
|
WHERE stock_code = ?
|
||||||
AND market = ?
|
AND market = ?
|
||||||
|
AND action IN ('BUY', 'SELL')
|
||||||
ORDER BY timestamp DESC
|
ORDER BY timestamp DESC
|
||||||
LIMIT 1
|
LIMIT 1
|
||||||
""",
|
""",
|
||||||
|
|||||||
203
src/main.py
203
src/main.py
@@ -27,6 +27,7 @@ from src.context.layer import ContextLayer
|
|||||||
from src.context.scheduler import ContextScheduler
|
from src.context.scheduler import ContextScheduler
|
||||||
from src.context.store import ContextStore
|
from src.context.store import ContextStore
|
||||||
from src.core.criticality import CriticalityAssessor
|
from src.core.criticality import CriticalityAssessor
|
||||||
|
from src.core.kill_switch import KillSwitchOrchestrator
|
||||||
from src.core.priority_queue import PriorityTaskQueue
|
from src.core.priority_queue import PriorityTaskQueue
|
||||||
from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected, RiskManager
|
from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected, RiskManager
|
||||||
from src.db import (
|
from src.db import (
|
||||||
@@ -43,11 +44,14 @@ from src.logging_config import setup_logging
|
|||||||
from src.markets.schedule import MARKETS, MarketInfo, get_next_market_open, get_open_markets
|
from src.markets.schedule import MARKETS, MarketInfo, get_next_market_open, get_open_markets
|
||||||
from src.notifications.telegram_client import NotificationFilter, TelegramClient, TelegramCommandHandler
|
from src.notifications.telegram_client import NotificationFilter, TelegramClient, TelegramCommandHandler
|
||||||
from src.strategy.models import DayPlaybook, MarketOutlook
|
from src.strategy.models import DayPlaybook, MarketOutlook
|
||||||
|
from src.strategy.exit_rules import ExitRuleConfig, ExitRuleInput, evaluate_exit
|
||||||
from src.strategy.playbook_store import PlaybookStore
|
from src.strategy.playbook_store import PlaybookStore
|
||||||
from src.strategy.pre_market_planner import PreMarketPlanner
|
from src.strategy.pre_market_planner import PreMarketPlanner
|
||||||
|
from src.strategy.position_state_machine import PositionState
|
||||||
from src.strategy.scenario_engine import ScenarioEngine
|
from src.strategy.scenario_engine import ScenarioEngine
|
||||||
|
|
||||||
logger = logging.getLogger(__name__)
|
logger = logging.getLogger(__name__)
|
||||||
|
KILL_SWITCH = KillSwitchOrchestrator()
|
||||||
|
|
||||||
|
|
||||||
def safe_float(value: str | float | None, default: float = 0.0) -> float:
|
def safe_float(value: str | float | None, default: float = 0.0) -> float:
|
||||||
@@ -477,6 +481,7 @@ async def trading_cycle(
|
|||||||
cycle_start_time = asyncio.get_event_loop().time()
|
cycle_start_time = asyncio.get_event_loop().time()
|
||||||
|
|
||||||
# 1. Fetch market data
|
# 1. Fetch market data
|
||||||
|
price_output: dict[str, Any] = {} # Populated for overseas markets; used for fallback metrics
|
||||||
if market.is_domestic:
|
if market.is_domestic:
|
||||||
current_price, price_change_pct, foreigner_net = await broker.get_current_price(
|
current_price, price_change_pct, foreigner_net = await broker.get_current_price(
|
||||||
stock_code
|
stock_code
|
||||||
@@ -508,9 +513,44 @@ async def trading_cycle(
|
|||||||
balance_info = {}
|
balance_info = {}
|
||||||
|
|
||||||
total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
|
total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
|
||||||
total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
|
|
||||||
purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
|
purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
|
||||||
|
|
||||||
|
# Resolve current price first (needed for buying power API)
|
||||||
|
price_output = price_data.get("output", {})
|
||||||
|
current_price = safe_float(price_output.get("last", "0"))
|
||||||
|
if current_price <= 0:
|
||||||
|
market_candidates_lookup = scan_candidates.get(market.code, {})
|
||||||
|
cand_lookup = market_candidates_lookup.get(stock_code)
|
||||||
|
if cand_lookup and cand_lookup.price > 0:
|
||||||
|
logger.debug(
|
||||||
|
"Price API returned 0 for %s; using scanner candidate price %.4f",
|
||||||
|
stock_code,
|
||||||
|
cand_lookup.price,
|
||||||
|
)
|
||||||
|
current_price = cand_lookup.price
|
||||||
|
foreigner_net = 0.0 # Not available for overseas
|
||||||
|
price_change_pct = safe_float(price_output.get("rate", "0"))
|
||||||
|
|
||||||
|
# Fetch available foreign currency cash via inquire-psamount (TTTS3007R/VTTS3007R).
|
||||||
|
# TTTS3012R output2 does not include a cash/deposit field — frcr_dncl_amt_2 does not exist.
|
||||||
|
# Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 매수가능금액조회' 시트
|
||||||
|
total_cash = 0.0
|
||||||
|
if current_price > 0:
|
||||||
|
try:
|
||||||
|
ps_data = await overseas_broker.get_overseas_buying_power(
|
||||||
|
market.exchange_code, stock_code, current_price
|
||||||
|
)
|
||||||
|
total_cash = safe_float(
|
||||||
|
ps_data.get("output", {}).get("ovrs_ord_psbl_amt", "0") or "0"
|
||||||
|
)
|
||||||
|
except ConnectionError as exc:
|
||||||
|
logger.warning(
|
||||||
|
"Could not fetch overseas buying power for %s/%s: %s",
|
||||||
|
market.exchange_code,
|
||||||
|
stock_code,
|
||||||
|
exc,
|
||||||
|
)
|
||||||
|
|
||||||
# Paper mode fallback: VTS overseas balance API often fails for many accounts.
|
# Paper mode fallback: VTS overseas balance API often fails for many accounts.
|
||||||
# Only activate in paper mode — live mode must use real balance from KIS.
|
# Only activate in paper mode — live mode must use real balance from KIS.
|
||||||
if (
|
if (
|
||||||
@@ -526,34 +566,6 @@ async def trading_cycle(
|
|||||||
)
|
)
|
||||||
total_cash = settings.PAPER_OVERSEAS_CASH
|
total_cash = settings.PAPER_OVERSEAS_CASH
|
||||||
|
|
||||||
current_price = safe_float(price_data.get("output", {}).get("last", "0"))
|
|
||||||
# Fallback: if price API returns 0, use scanner candidate price
|
|
||||||
if current_price <= 0:
|
|
||||||
market_candidates_lookup = scan_candidates.get(market.code, {})
|
|
||||||
cand_lookup = market_candidates_lookup.get(stock_code)
|
|
||||||
if cand_lookup and cand_lookup.price > 0:
|
|
||||||
logger.debug(
|
|
||||||
"Price API returned 0 for %s; using scanner candidate price %.4f",
|
|
||||||
stock_code,
|
|
||||||
cand_lookup.price,
|
|
||||||
)
|
|
||||||
current_price = cand_lookup.price
|
|
||||||
foreigner_net = 0.0 # Not available for overseas
|
|
||||||
price_change_pct = safe_float(price_data.get("output", {}).get("rate", "0"))
|
|
||||||
|
|
||||||
# Price API may return 0/empty for certain VTS exchange codes.
|
|
||||||
# Fall back to the scanner candidate's price so order sizing still works.
|
|
||||||
if current_price <= 0:
|
|
||||||
market_candidates_lookup = scan_candidates.get(market.code, {})
|
|
||||||
cand_lookup = market_candidates_lookup.get(stock_code)
|
|
||||||
if cand_lookup and cand_lookup.price > 0:
|
|
||||||
current_price = cand_lookup.price
|
|
||||||
logger.debug(
|
|
||||||
"Price API returned 0 for %s; using scanner price %.4f",
|
|
||||||
stock_code,
|
|
||||||
current_price,
|
|
||||||
)
|
|
||||||
|
|
||||||
# Calculate daily P&L %
|
# Calculate daily P&L %
|
||||||
pnl_pct = (
|
pnl_pct = (
|
||||||
((total_eval - purchase_total) / purchase_total * 100)
|
((total_eval - purchase_total) / purchase_total * 100)
|
||||||
@@ -575,6 +587,28 @@ async def trading_cycle(
|
|||||||
if candidate:
|
if candidate:
|
||||||
market_data["rsi"] = candidate.rsi
|
market_data["rsi"] = candidate.rsi
|
||||||
market_data["volume_ratio"] = candidate.volume_ratio
|
market_data["volume_ratio"] = candidate.volume_ratio
|
||||||
|
else:
|
||||||
|
# Holding stocks not in scanner: derive metrics from price API data already fetched.
|
||||||
|
# For overseas stocks, price_output contains high/low/rate from get_overseas_price.
|
||||||
|
# For domestic stocks, only price_change_pct is available from get_current_price.
|
||||||
|
market_data["rsi"] = max(0.0, min(100.0, 50.0 + price_change_pct * 2.0))
|
||||||
|
if price_output and current_price > 0:
|
||||||
|
pr_high = safe_float(
|
||||||
|
price_output.get("high") or price_output.get("ovrs_hgpr")
|
||||||
|
or price_output.get("stck_hgpr")
|
||||||
|
)
|
||||||
|
pr_low = safe_float(
|
||||||
|
price_output.get("low") or price_output.get("ovrs_lwpr")
|
||||||
|
or price_output.get("stck_lwpr")
|
||||||
|
)
|
||||||
|
if pr_high > 0 and pr_low > 0 and pr_high >= pr_low:
|
||||||
|
intraday_range_pct = (pr_high - pr_low) / current_price * 100.0
|
||||||
|
volatility_pct = max(abs(price_change_pct), intraday_range_pct)
|
||||||
|
market_data["volume_ratio"] = max(1.0, volatility_pct / 2.0)
|
||||||
|
else:
|
||||||
|
market_data["volume_ratio"] = 1.0
|
||||||
|
else:
|
||||||
|
market_data["volume_ratio"] = 1.0
|
||||||
|
|
||||||
# Enrich market_data with holding info for SELL/HOLD scenario conditions
|
# Enrich market_data with holding info for SELL/HOLD scenario conditions
|
||||||
open_pos = get_open_position(db_conn, stock_code, market.code)
|
open_pos = get_open_position(db_conn, stock_code, market.code)
|
||||||
@@ -754,7 +788,24 @@ async def trading_cycle(
|
|||||||
stop_loss_threshold = stock_playbook.scenarios[0].stop_loss_pct
|
stop_loss_threshold = stock_playbook.scenarios[0].stop_loss_pct
|
||||||
take_profit_threshold = stock_playbook.scenarios[0].take_profit_pct
|
take_profit_threshold = stock_playbook.scenarios[0].take_profit_pct
|
||||||
|
|
||||||
if loss_pct <= stop_loss_threshold:
|
exit_eval = evaluate_exit(
|
||||||
|
current_state=PositionState.HOLDING,
|
||||||
|
config=ExitRuleConfig(
|
||||||
|
hard_stop_pct=stop_loss_threshold,
|
||||||
|
be_arm_pct=max(0.5, take_profit_threshold * 0.4),
|
||||||
|
arm_pct=take_profit_threshold,
|
||||||
|
),
|
||||||
|
inp=ExitRuleInput(
|
||||||
|
current_price=current_price,
|
||||||
|
entry_price=entry_price,
|
||||||
|
peak_price=max(entry_price, current_price),
|
||||||
|
atr_value=0.0,
|
||||||
|
pred_down_prob=0.0,
|
||||||
|
liquidity_weak=market_data.get("volume_ratio", 1.0) < 1.0,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
if exit_eval.reason == "hard_stop":
|
||||||
decision = TradeDecision(
|
decision = TradeDecision(
|
||||||
action="SELL",
|
action="SELL",
|
||||||
confidence=95,
|
confidence=95,
|
||||||
@@ -770,7 +821,7 @@ async def trading_cycle(
|
|||||||
loss_pct,
|
loss_pct,
|
||||||
stop_loss_threshold,
|
stop_loss_threshold,
|
||||||
)
|
)
|
||||||
elif loss_pct >= take_profit_threshold:
|
elif exit_eval.reason == "arm_take_profit":
|
||||||
decision = TradeDecision(
|
decision = TradeDecision(
|
||||||
action="SELL",
|
action="SELL",
|
||||||
confidence=90,
|
confidence=90,
|
||||||
@@ -846,6 +897,15 @@ async def trading_cycle(
|
|||||||
trade_price = current_price
|
trade_price = current_price
|
||||||
trade_pnl = 0.0
|
trade_pnl = 0.0
|
||||||
if decision.action in ("BUY", "SELL"):
|
if decision.action in ("BUY", "SELL"):
|
||||||
|
if KILL_SWITCH.new_orders_blocked:
|
||||||
|
logger.critical(
|
||||||
|
"KillSwitch block active: skip %s order for %s (%s)",
|
||||||
|
decision.action,
|
||||||
|
stock_code,
|
||||||
|
market.name,
|
||||||
|
)
|
||||||
|
return
|
||||||
|
|
||||||
broker_held_qty = (
|
broker_held_qty = (
|
||||||
_extract_held_qty_from_balance(
|
_extract_held_qty_from_balance(
|
||||||
balance_data, stock_code, is_domestic=market.is_domestic
|
balance_data, stock_code, is_domestic=market.is_domestic
|
||||||
@@ -914,6 +974,25 @@ async def trading_cycle(
|
|||||||
except Exception as notify_exc:
|
except Exception as notify_exc:
|
||||||
logger.warning("Fat finger notification failed: %s", notify_exc)
|
logger.warning("Fat finger notification failed: %s", notify_exc)
|
||||||
raise # Re-raise to prevent trade
|
raise # Re-raise to prevent trade
|
||||||
|
except CircuitBreakerTripped as exc:
|
||||||
|
ks_report = await KILL_SWITCH.trigger(
|
||||||
|
reason=f"circuit_breaker:{market.code}:{stock_code}:{exc.pnl_pct:.2f}",
|
||||||
|
snapshot_state=lambda: logger.critical(
|
||||||
|
"KillSwitch snapshot %s/%s pnl=%.2f threshold=%.2f",
|
||||||
|
market.code,
|
||||||
|
stock_code,
|
||||||
|
exc.pnl_pct,
|
||||||
|
exc.threshold,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
if ks_report.errors:
|
||||||
|
logger.critical(
|
||||||
|
"KillSwitch step errors for %s/%s: %s",
|
||||||
|
market.code,
|
||||||
|
stock_code,
|
||||||
|
"; ".join(ks_report.errors),
|
||||||
|
)
|
||||||
|
raise
|
||||||
|
|
||||||
# 5. Send order
|
# 5. Send order
|
||||||
order_succeeded = True
|
order_succeeded = True
|
||||||
@@ -1493,8 +1572,9 @@ async def run_daily_session(
|
|||||||
active_stocks={},
|
active_stocks={},
|
||||||
)
|
)
|
||||||
if not fallback_stocks:
|
if not fallback_stocks:
|
||||||
logger.warning(
|
logger.debug(
|
||||||
"No dynamic overseas symbol universe for %s; scanner cannot run",
|
"No dynamic overseas symbol universe for %s;"
|
||||||
|
" scanner will use overseas ranking API",
|
||||||
market.code,
|
market.code,
|
||||||
)
|
)
|
||||||
try:
|
try:
|
||||||
@@ -1659,10 +1739,35 @@ async def run_daily_session(
|
|||||||
balance_info = {}
|
balance_info = {}
|
||||||
|
|
||||||
total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
|
total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
|
||||||
total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
|
|
||||||
purchase_total = safe_float(
|
purchase_total = safe_float(
|
||||||
balance_info.get("frcr_buy_amt_smtl", "0") or "0"
|
balance_info.get("frcr_buy_amt_smtl", "0") or "0"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
# Fetch available foreign currency cash via inquire-psamount (TTTS3007R/VTTS3007R).
|
||||||
|
# TTTS3012R output2 does not include a cash/deposit field — frcr_dncl_amt_2 does not exist.
|
||||||
|
# Use the first stock with a valid price as the reference for the buying power query.
|
||||||
|
# Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 매수가능금액조회' 시트
|
||||||
|
total_cash = 0.0
|
||||||
|
ref_stock = next(
|
||||||
|
(s for s in stocks_data if s.get("current_price", 0) > 0), None
|
||||||
|
)
|
||||||
|
if ref_stock:
|
||||||
|
try:
|
||||||
|
ps_data = await overseas_broker.get_overseas_buying_power(
|
||||||
|
market.exchange_code,
|
||||||
|
ref_stock["stock_code"],
|
||||||
|
ref_stock["current_price"],
|
||||||
|
)
|
||||||
|
total_cash = safe_float(
|
||||||
|
ps_data.get("output", {}).get("ovrs_ord_psbl_amt", "0") or "0"
|
||||||
|
)
|
||||||
|
except ConnectionError as exc:
|
||||||
|
logger.warning(
|
||||||
|
"Could not fetch overseas buying power for %s: %s",
|
||||||
|
market.exchange_code,
|
||||||
|
exc,
|
||||||
|
)
|
||||||
|
|
||||||
# Paper mode fallback: VTS overseas balance API often fails for many accounts.
|
# Paper mode fallback: VTS overseas balance API often fails for many accounts.
|
||||||
# Only activate in paper mode — live mode must use real balance from KIS.
|
# Only activate in paper mode — live mode must use real balance from KIS.
|
||||||
if (
|
if (
|
||||||
@@ -1789,6 +1894,15 @@ async def run_daily_session(
|
|||||||
trade_pnl = 0.0
|
trade_pnl = 0.0
|
||||||
order_succeeded = True
|
order_succeeded = True
|
||||||
if decision.action in ("BUY", "SELL"):
|
if decision.action in ("BUY", "SELL"):
|
||||||
|
if KILL_SWITCH.new_orders_blocked:
|
||||||
|
logger.critical(
|
||||||
|
"KillSwitch block active: skip %s order for %s (%s)",
|
||||||
|
decision.action,
|
||||||
|
stock_code,
|
||||||
|
market.name,
|
||||||
|
)
|
||||||
|
continue
|
||||||
|
|
||||||
daily_broker_held_qty = (
|
daily_broker_held_qty = (
|
||||||
_extract_held_qty_from_balance(
|
_extract_held_qty_from_balance(
|
||||||
balance_data, stock_code, is_domestic=market.is_domestic
|
balance_data, stock_code, is_domestic=market.is_domestic
|
||||||
@@ -1855,6 +1969,16 @@ async def run_daily_session(
|
|||||||
logger.warning("Fat finger notification failed: %s", notify_exc)
|
logger.warning("Fat finger notification failed: %s", notify_exc)
|
||||||
continue # Skip this order
|
continue # Skip this order
|
||||||
except CircuitBreakerTripped as exc:
|
except CircuitBreakerTripped as exc:
|
||||||
|
ks_report = await KILL_SWITCH.trigger(
|
||||||
|
reason=f"daily_circuit_breaker:{market.code}:{stock_code}:{exc.pnl_pct:.2f}",
|
||||||
|
snapshot_state=lambda: logger.critical(
|
||||||
|
"Daily KillSwitch snapshot %s/%s pnl=%.2f threshold=%.2f",
|
||||||
|
market.code,
|
||||||
|
stock_code,
|
||||||
|
exc.pnl_pct,
|
||||||
|
exc.threshold,
|
||||||
|
),
|
||||||
|
)
|
||||||
logger.critical("Circuit breaker tripped — stopping session")
|
logger.critical("Circuit breaker tripped — stopping session")
|
||||||
try:
|
try:
|
||||||
await telegram.notify_circuit_breaker(
|
await telegram.notify_circuit_breaker(
|
||||||
@@ -1865,6 +1989,13 @@ async def run_daily_session(
|
|||||||
logger.warning(
|
logger.warning(
|
||||||
"Circuit breaker notification failed: %s", notify_exc
|
"Circuit breaker notification failed: %s", notify_exc
|
||||||
)
|
)
|
||||||
|
if ks_report.errors:
|
||||||
|
logger.critical(
|
||||||
|
"Daily KillSwitch step errors for %s/%s: %s",
|
||||||
|
market.code,
|
||||||
|
stock_code,
|
||||||
|
"; ".join(ks_report.errors),
|
||||||
|
)
|
||||||
raise
|
raise
|
||||||
|
|
||||||
# Send order
|
# Send order
|
||||||
@@ -2781,9 +2912,9 @@ async def run(settings: Settings) -> None:
|
|||||||
active_stocks=active_stocks,
|
active_stocks=active_stocks,
|
||||||
)
|
)
|
||||||
if not fallback_stocks:
|
if not fallback_stocks:
|
||||||
logger.warning(
|
logger.debug(
|
||||||
"No dynamic overseas symbol universe for %s;"
|
"No dynamic overseas symbol universe for %s;"
|
||||||
" scanner cannot run",
|
" scanner will use overseas ranking API",
|
||||||
market.code,
|
market.code,
|
||||||
)
|
)
|
||||||
|
|
||||||
|
|||||||
104
src/strategy/exit_rules.py
Normal file
104
src/strategy/exit_rules.py
Normal file
@@ -0,0 +1,104 @@
|
|||||||
|
"""Composite exit rules: hard stop, break-even lock, ATR trailing, model assist."""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from dataclasses import dataclass
|
||||||
|
|
||||||
|
from src.strategy.position_state_machine import PositionState, StateTransitionInput, promote_state
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class ExitRuleConfig:
|
||||||
|
hard_stop_pct: float = -2.0
|
||||||
|
be_arm_pct: float = 1.2
|
||||||
|
arm_pct: float = 3.0
|
||||||
|
atr_multiplier_k: float = 2.2
|
||||||
|
model_prob_threshold: float = 0.62
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class ExitRuleInput:
|
||||||
|
current_price: float
|
||||||
|
entry_price: float
|
||||||
|
peak_price: float
|
||||||
|
atr_value: float = 0.0
|
||||||
|
pred_down_prob: float = 0.0
|
||||||
|
liquidity_weak: bool = False
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class ExitEvaluation:
|
||||||
|
state: PositionState
|
||||||
|
should_exit: bool
|
||||||
|
reason: str
|
||||||
|
unrealized_pnl_pct: float
|
||||||
|
trailing_stop_price: float | None
|
||||||
|
|
||||||
|
|
||||||
|
def evaluate_exit(
|
||||||
|
*,
|
||||||
|
current_state: PositionState,
|
||||||
|
config: ExitRuleConfig,
|
||||||
|
inp: ExitRuleInput,
|
||||||
|
) -> ExitEvaluation:
|
||||||
|
"""Evaluate composite exit logic and return updated state."""
|
||||||
|
if inp.entry_price <= 0 or inp.current_price <= 0:
|
||||||
|
return ExitEvaluation(
|
||||||
|
state=current_state,
|
||||||
|
should_exit=False,
|
||||||
|
reason="invalid_price",
|
||||||
|
unrealized_pnl_pct=0.0,
|
||||||
|
trailing_stop_price=None,
|
||||||
|
)
|
||||||
|
|
||||||
|
unrealized = (inp.current_price - inp.entry_price) / inp.entry_price * 100.0
|
||||||
|
hard_stop_hit = unrealized <= config.hard_stop_pct
|
||||||
|
take_profit_hit = unrealized >= config.arm_pct
|
||||||
|
|
||||||
|
trailing_stop_price: float | None = None
|
||||||
|
trailing_stop_hit = False
|
||||||
|
if inp.atr_value > 0 and inp.peak_price > 0:
|
||||||
|
trailing_stop_price = inp.peak_price - (config.atr_multiplier_k * inp.atr_value)
|
||||||
|
trailing_stop_hit = inp.current_price <= trailing_stop_price
|
||||||
|
|
||||||
|
be_lock_threat = current_state in (PositionState.BE_LOCK, PositionState.ARMED) and (
|
||||||
|
inp.current_price <= inp.entry_price
|
||||||
|
)
|
||||||
|
model_exit_signal = inp.pred_down_prob >= config.model_prob_threshold and inp.liquidity_weak
|
||||||
|
|
||||||
|
next_state = promote_state(
|
||||||
|
current=current_state,
|
||||||
|
inp=StateTransitionInput(
|
||||||
|
unrealized_pnl_pct=unrealized,
|
||||||
|
be_arm_pct=config.be_arm_pct,
|
||||||
|
arm_pct=config.arm_pct,
|
||||||
|
hard_stop_hit=hard_stop_hit,
|
||||||
|
trailing_stop_hit=trailing_stop_hit,
|
||||||
|
model_exit_signal=model_exit_signal,
|
||||||
|
be_lock_threat=be_lock_threat,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
|
||||||
|
if hard_stop_hit:
|
||||||
|
reason = "hard_stop"
|
||||||
|
elif trailing_stop_hit:
|
||||||
|
reason = "atr_trailing_stop"
|
||||||
|
elif be_lock_threat:
|
||||||
|
reason = "be_lock_threat"
|
||||||
|
elif model_exit_signal:
|
||||||
|
reason = "model_liquidity_exit"
|
||||||
|
elif take_profit_hit:
|
||||||
|
# Backward-compatible immediate profit-taking path.
|
||||||
|
reason = "arm_take_profit"
|
||||||
|
else:
|
||||||
|
reason = "hold"
|
||||||
|
|
||||||
|
should_exit = next_state == PositionState.EXITED or take_profit_hit
|
||||||
|
|
||||||
|
return ExitEvaluation(
|
||||||
|
state=next_state,
|
||||||
|
should_exit=should_exit,
|
||||||
|
reason=reason,
|
||||||
|
unrealized_pnl_pct=unrealized,
|
||||||
|
trailing_stop_price=trailing_stop_price,
|
||||||
|
)
|
||||||
70
src/strategy/position_state_machine.py
Normal file
70
src/strategy/position_state_machine.py
Normal file
@@ -0,0 +1,70 @@
|
|||||||
|
"""Position state machine for staged exit control.
|
||||||
|
|
||||||
|
State progression is monotonic (promotion-only) except terminal EXITED.
|
||||||
|
"""
|
||||||
|
|
||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
from dataclasses import dataclass
|
||||||
|
from enum import Enum
|
||||||
|
|
||||||
|
|
||||||
|
class PositionState(str, Enum):
|
||||||
|
HOLDING = "HOLDING"
|
||||||
|
BE_LOCK = "BE_LOCK"
|
||||||
|
ARMED = "ARMED"
|
||||||
|
EXITED = "EXITED"
|
||||||
|
|
||||||
|
|
||||||
|
_STATE_RANK: dict[PositionState, int] = {
|
||||||
|
PositionState.HOLDING: 0,
|
||||||
|
PositionState.BE_LOCK: 1,
|
||||||
|
PositionState.ARMED: 2,
|
||||||
|
PositionState.EXITED: 3,
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@dataclass(frozen=True)
|
||||||
|
class StateTransitionInput:
|
||||||
|
unrealized_pnl_pct: float
|
||||||
|
be_arm_pct: float
|
||||||
|
arm_pct: float
|
||||||
|
hard_stop_hit: bool = False
|
||||||
|
trailing_stop_hit: bool = False
|
||||||
|
model_exit_signal: bool = False
|
||||||
|
be_lock_threat: bool = False
|
||||||
|
|
||||||
|
|
||||||
|
def evaluate_exit_first(inp: StateTransitionInput) -> bool:
|
||||||
|
"""Return True when terminal exit conditions are met.
|
||||||
|
|
||||||
|
EXITED must be evaluated before any promotion.
|
||||||
|
"""
|
||||||
|
return (
|
||||||
|
inp.hard_stop_hit
|
||||||
|
or inp.trailing_stop_hit
|
||||||
|
or inp.model_exit_signal
|
||||||
|
or inp.be_lock_threat
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def promote_state(current: PositionState, inp: StateTransitionInput) -> PositionState:
|
||||||
|
"""Promote to highest admissible state for current tick/bar.
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
- EXITED has highest precedence and is terminal.
|
||||||
|
- Promotions are monotonic (no downgrade).
|
||||||
|
"""
|
||||||
|
if current == PositionState.EXITED:
|
||||||
|
return PositionState.EXITED
|
||||||
|
|
||||||
|
if evaluate_exit_first(inp):
|
||||||
|
return PositionState.EXITED
|
||||||
|
|
||||||
|
target = PositionState.HOLDING
|
||||||
|
if inp.unrealized_pnl_pct >= inp.arm_pct:
|
||||||
|
target = PositionState.ARMED
|
||||||
|
elif inp.unrealized_pnl_pct >= inp.be_arm_pct:
|
||||||
|
target = PositionState.BE_LOCK
|
||||||
|
|
||||||
|
return target if _STATE_RANK[target] > _STATE_RANK[current] else current
|
||||||
55
tests/test_kill_switch.py
Normal file
55
tests/test_kill_switch.py
Normal file
@@ -0,0 +1,55 @@
|
|||||||
|
import pytest
|
||||||
|
|
||||||
|
from src.core.kill_switch import KillSwitchOrchestrator
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_kill_switch_executes_steps_in_order() -> None:
|
||||||
|
ks = KillSwitchOrchestrator()
|
||||||
|
calls: list[str] = []
|
||||||
|
|
||||||
|
async def _cancel() -> None:
|
||||||
|
calls.append("cancel")
|
||||||
|
|
||||||
|
def _refresh() -> None:
|
||||||
|
calls.append("refresh")
|
||||||
|
|
||||||
|
def _reduce() -> None:
|
||||||
|
calls.append("reduce")
|
||||||
|
|
||||||
|
def _snapshot() -> None:
|
||||||
|
calls.append("snapshot")
|
||||||
|
|
||||||
|
def _notify() -> None:
|
||||||
|
calls.append("notify")
|
||||||
|
|
||||||
|
report = await ks.trigger(
|
||||||
|
reason="test",
|
||||||
|
cancel_pending_orders=_cancel,
|
||||||
|
refresh_order_state=_refresh,
|
||||||
|
reduce_risk=_reduce,
|
||||||
|
snapshot_state=_snapshot,
|
||||||
|
notify=_notify,
|
||||||
|
)
|
||||||
|
|
||||||
|
assert report.steps == [
|
||||||
|
"block_new_orders",
|
||||||
|
"cancel_pending_orders",
|
||||||
|
"refresh_order_state",
|
||||||
|
"reduce_risk",
|
||||||
|
"snapshot_state",
|
||||||
|
"notify",
|
||||||
|
]
|
||||||
|
assert calls == ["cancel", "refresh", "reduce", "snapshot", "notify"]
|
||||||
|
assert report.errors == []
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_kill_switch_collects_step_errors() -> None:
|
||||||
|
ks = KillSwitchOrchestrator()
|
||||||
|
|
||||||
|
def _boom() -> None:
|
||||||
|
raise RuntimeError("boom")
|
||||||
|
|
||||||
|
report = await ks.trigger(reason="test", cancel_pending_orders=_boom)
|
||||||
|
assert any(err.startswith("cancel_pending_orders:") for err in report.errors)
|
||||||
@@ -13,6 +13,7 @@ from src.db import init_db, log_trade
|
|||||||
from src.evolution.scorecard import DailyScorecard
|
from src.evolution.scorecard import DailyScorecard
|
||||||
from src.logging.decision_logger import DecisionLogger
|
from src.logging.decision_logger import DecisionLogger
|
||||||
from src.main import (
|
from src.main import (
|
||||||
|
KILL_SWITCH,
|
||||||
_apply_dashboard_flag,
|
_apply_dashboard_flag,
|
||||||
_determine_order_quantity,
|
_determine_order_quantity,
|
||||||
_extract_avg_price_from_balance,
|
_extract_avg_price_from_balance,
|
||||||
@@ -77,6 +78,14 @@ def _make_sell_match(stock_code: str = "005930") -> ScenarioMatch:
|
|||||||
)
|
)
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.fixture(autouse=True)
|
||||||
|
def _reset_kill_switch_state() -> None:
|
||||||
|
"""Prevent cross-test leakage from global kill-switch state."""
|
||||||
|
KILL_SWITCH.clear_block()
|
||||||
|
yield
|
||||||
|
KILL_SWITCH.clear_block()
|
||||||
|
|
||||||
|
|
||||||
class TestExtractAvgPriceFromBalance:
|
class TestExtractAvgPriceFromBalance:
|
||||||
"""Tests for _extract_avg_price_from_balance() (issue #249)."""
|
"""Tests for _extract_avg_price_from_balance() (issue #249)."""
|
||||||
|
|
||||||
@@ -903,12 +912,14 @@ class TestOverseasBalanceParsing:
|
|||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_evlu_tota": "10000.00",
|
"frcr_evlu_tota": "10000.00",
|
||||||
"frcr_dncl_amt_2": "5000.00",
|
|
||||||
"frcr_buy_amt_smtl": "4500.00",
|
"frcr_buy_amt_smtl": "4500.00",
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "5000.00"}}
|
||||||
|
)
|
||||||
return broker
|
return broker
|
||||||
|
|
||||||
@pytest.fixture
|
@pytest.fixture
|
||||||
@@ -922,11 +933,13 @@ class TestOverseasBalanceParsing:
|
|||||||
return_value={
|
return_value={
|
||||||
"output2": {
|
"output2": {
|
||||||
"frcr_evlu_tota": "10000.00",
|
"frcr_evlu_tota": "10000.00",
|
||||||
"frcr_dncl_amt_2": "5000.00",
|
|
||||||
"frcr_buy_amt_smtl": "4500.00",
|
"frcr_buy_amt_smtl": "4500.00",
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "5000.00"}}
|
||||||
|
)
|
||||||
return broker
|
return broker
|
||||||
|
|
||||||
@pytest.fixture
|
@pytest.fixture
|
||||||
@@ -937,6 +950,9 @@ class TestOverseasBalanceParsing:
|
|||||||
return_value={"output": {"last": "150.50"}}
|
return_value={"output": {"last": "150.50"}}
|
||||||
)
|
)
|
||||||
broker.get_overseas_balance = AsyncMock(return_value={"output2": []})
|
broker.get_overseas_balance = AsyncMock(return_value={"output2": []})
|
||||||
|
broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "0.00"}}
|
||||||
|
)
|
||||||
return broker
|
return broker
|
||||||
|
|
||||||
@pytest.fixture
|
@pytest.fixture
|
||||||
@@ -951,12 +967,15 @@ class TestOverseasBalanceParsing:
|
|||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_evlu_tota": "10000.00",
|
"frcr_evlu_tota": "10000.00",
|
||||||
"frcr_dncl_amt_2": "5000.00",
|
|
||||||
"frcr_buy_amt_smtl": "4500.00",
|
"frcr_buy_amt_smtl": "4500.00",
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
# get_overseas_buying_power not called when price=0, but mock for safety
|
||||||
|
broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "5000.00"}}
|
||||||
|
)
|
||||||
return broker
|
return broker
|
||||||
|
|
||||||
@pytest.fixture
|
@pytest.fixture
|
||||||
@@ -1186,12 +1205,14 @@ class TestOverseasBalanceParsing:
|
|||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_evlu_tota": "100000.00",
|
"frcr_evlu_tota": "100000.00",
|
||||||
"frcr_dncl_amt_2": "50000.00",
|
|
||||||
"frcr_buy_amt_smtl": "50000.00",
|
"frcr_buy_amt_smtl": "50000.00",
|
||||||
}
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
|
||||||
|
)
|
||||||
broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
|
broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
|
||||||
return broker
|
return broker
|
||||||
|
|
||||||
@@ -1291,12 +1312,14 @@ class TestOverseasBalanceParsing:
|
|||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_evlu_tota": "100000.00",
|
"frcr_evlu_tota": "100000.00",
|
||||||
"frcr_dncl_amt_2": "50000.00",
|
|
||||||
"frcr_buy_amt_smtl": "50000.00",
|
"frcr_buy_amt_smtl": "50000.00",
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
|
||||||
|
)
|
||||||
overseas_broker.send_overseas_order = AsyncMock(
|
overseas_broker.send_overseas_order = AsyncMock(
|
||||||
return_value={"rt_cd": "0", "msg1": "OK"}
|
return_value={"rt_cd": "0", "msg1": "OK"}
|
||||||
)
|
)
|
||||||
@@ -1355,9 +1378,12 @@ class TestOverseasBalanceParsing:
|
|||||||
overseas_broker.get_overseas_balance = AsyncMock(
|
overseas_broker.get_overseas_balance = AsyncMock(
|
||||||
return_value={
|
return_value={
|
||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [{"frcr_evlu_tota": "0", "frcr_dncl_amt_2": "10000", "frcr_buy_amt_smtl": "0"}],
|
"output2": [{"frcr_evlu_tota": "0", "frcr_buy_amt_smtl": "0"}],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "10000"}}
|
||||||
|
)
|
||||||
overseas_broker.get_overseas_price = AsyncMock(
|
overseas_broker.get_overseas_price = AsyncMock(
|
||||||
return_value={"output": {"last": "50.1234", "rate": "0"}}
|
return_value={"output": {"last": "50.1234", "rate": "0"}}
|
||||||
)
|
)
|
||||||
@@ -1413,9 +1439,12 @@ class TestOverseasBalanceParsing:
|
|||||||
overseas_broker.get_overseas_balance = AsyncMock(
|
overseas_broker.get_overseas_balance = AsyncMock(
|
||||||
return_value={
|
return_value={
|
||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [{"frcr_evlu_tota": "0", "frcr_dncl_amt_2": "10000", "frcr_buy_amt_smtl": "0"}],
|
"output2": [{"frcr_evlu_tota": "0", "frcr_buy_amt_smtl": "0"}],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "10000"}}
|
||||||
|
)
|
||||||
overseas_broker.get_overseas_price = AsyncMock(
|
overseas_broker.get_overseas_price = AsyncMock(
|
||||||
return_value={"output": {"last": "0.5678", "rate": "0"}}
|
return_value={"output": {"last": "0.5678", "rate": "0"}}
|
||||||
)
|
)
|
||||||
@@ -1648,10 +1677,10 @@ class TestScenarioEngineIntegration:
|
|||||||
scan_candidates={"US": {"005930": us_candidate}}, # Wrong market
|
scan_candidates={"US": {"005930": us_candidate}}, # Wrong market
|
||||||
)
|
)
|
||||||
|
|
||||||
# Should NOT have rsi/volume_ratio because candidate is under US, not KR
|
# Should NOT use US candidate's rsi (=15.0); fallback implied_rsi used instead
|
||||||
market_data = engine.evaluate.call_args[0][2]
|
market_data = engine.evaluate.call_args[0][2]
|
||||||
assert "rsi" not in market_data
|
assert market_data["rsi"] != 15.0 # US candidate's rsi must be ignored
|
||||||
assert "volume_ratio" not in market_data
|
assert market_data["volume_ratio"] == 1.0 # Fallback default
|
||||||
|
|
||||||
@pytest.mark.asyncio
|
@pytest.mark.asyncio
|
||||||
async def test_scenario_engine_called_without_scanner_data(
|
async def test_scenario_engine_called_without_scanner_data(
|
||||||
@@ -1682,13 +1711,70 @@ class TestScenarioEngineIntegration:
|
|||||||
scan_candidates={}, # No scanner data
|
scan_candidates={}, # No scanner data
|
||||||
)
|
)
|
||||||
|
|
||||||
# Should still work, just without rsi/volume_ratio
|
# Holding stocks without scanner data use implied_rsi (from price_change_pct)
|
||||||
|
# and volume_ratio=1.0 as fallback, so rsi/volume_ratio are always present.
|
||||||
engine.evaluate.assert_called_once()
|
engine.evaluate.assert_called_once()
|
||||||
market_data = engine.evaluate.call_args[0][2]
|
market_data = engine.evaluate.call_args[0][2]
|
||||||
assert "rsi" not in market_data
|
assert "rsi" in market_data # Implied RSI from price_change_pct=2.5 → 55.0
|
||||||
assert "volume_ratio" not in market_data
|
assert market_data["rsi"] == pytest.approx(55.0)
|
||||||
|
assert market_data["volume_ratio"] == 1.0
|
||||||
assert market_data["current_price"] == 50000.0
|
assert market_data["current_price"] == 50000.0
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_holding_overseas_stock_derives_volume_ratio_from_price_api(
|
||||||
|
self, mock_broker: MagicMock, mock_telegram: MagicMock,
|
||||||
|
) -> None:
|
||||||
|
"""Test overseas holding stocks derive volume_ratio from get_overseas_price high/low."""
|
||||||
|
engine = MagicMock(spec=ScenarioEngine)
|
||||||
|
engine.evaluate = MagicMock(return_value=_make_hold_match())
|
||||||
|
|
||||||
|
os_market = MagicMock()
|
||||||
|
os_market.name = "NASDAQ"
|
||||||
|
os_market.code = "US_NASDAQ"
|
||||||
|
os_market.exchange_code = "NAS"
|
||||||
|
os_market.is_domestic = False
|
||||||
|
os_market.timezone = UTC
|
||||||
|
|
||||||
|
os_broker = MagicMock()
|
||||||
|
# price_change_pct=5.0, high=106, low=94 → intraday_range=12% → volume_ratio=max(1,6)=6
|
||||||
|
os_broker.get_overseas_price = AsyncMock(return_value={
|
||||||
|
"output": {"last": "100.0", "rate": "5.0", "high": "106.0", "low": "94.0"}
|
||||||
|
})
|
||||||
|
os_broker.get_overseas_balance = AsyncMock(return_value={
|
||||||
|
"output2": [{"frcr_evlu_tota": "10000", "frcr_buy_amt_smtl": "9000"}]
|
||||||
|
})
|
||||||
|
os_broker.get_overseas_buying_power = AsyncMock(return_value={
|
||||||
|
"output": {"ovrs_ord_psbl_amt": "500"}
|
||||||
|
})
|
||||||
|
|
||||||
|
with patch("src.main.log_trade"):
|
||||||
|
await trading_cycle(
|
||||||
|
broker=mock_broker,
|
||||||
|
overseas_broker=os_broker,
|
||||||
|
scenario_engine=engine,
|
||||||
|
playbook=_make_playbook(),
|
||||||
|
risk=MagicMock(),
|
||||||
|
db_conn=MagicMock(),
|
||||||
|
decision_logger=MagicMock(),
|
||||||
|
context_store=MagicMock(get_latest_timeframe=MagicMock(return_value=None)),
|
||||||
|
criticality_assessor=MagicMock(
|
||||||
|
assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
|
||||||
|
get_timeout=MagicMock(return_value=5.0),
|
||||||
|
),
|
||||||
|
telegram=mock_telegram,
|
||||||
|
market=os_market,
|
||||||
|
stock_code="NVDA",
|
||||||
|
scan_candidates={}, # Not in scanner — holding stock
|
||||||
|
)
|
||||||
|
|
||||||
|
market_data = engine.evaluate.call_args[0][2]
|
||||||
|
# rsi: 50.0 + 5.0 * 2.0 = 60.0
|
||||||
|
assert market_data["rsi"] == pytest.approx(60.0)
|
||||||
|
# intraday_range = (106-94)/100 * 100 = 12.0%
|
||||||
|
# volatility_pct = max(abs(5.0), 12.0) = 12.0
|
||||||
|
# volume_ratio = max(1.0, 12.0 / 2.0) = 6.0
|
||||||
|
assert market_data["volume_ratio"] == pytest.approx(6.0)
|
||||||
|
|
||||||
@pytest.mark.asyncio
|
@pytest.mark.asyncio
|
||||||
async def test_scenario_matched_notification_sent(
|
async def test_scenario_matched_notification_sent(
|
||||||
self, mock_broker: MagicMock, mock_market: MagicMock, mock_telegram: MagicMock,
|
self, mock_broker: MagicMock, mock_market: MagicMock, mock_telegram: MagicMock,
|
||||||
@@ -2781,9 +2867,11 @@ class TestBuyCooldown:
|
|||||||
)
|
)
|
||||||
broker.get_overseas_balance = AsyncMock(return_value={
|
broker.get_overseas_balance = AsyncMock(return_value={
|
||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [{"frcr_dncl_amt_2": "50000", "frcr_evlu_tota": "50000",
|
"output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
|
||||||
"frcr_buy_amt_smtl": "0"}],
|
|
||||||
})
|
})
|
||||||
|
broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000"}}
|
||||||
|
)
|
||||||
broker.send_overseas_order = AsyncMock(
|
broker.send_overseas_order = AsyncMock(
|
||||||
return_value={"rt_cd": "1", "msg1": "모의투자 주문가능금액이 부족합니다."}
|
return_value={"rt_cd": "1", "msg1": "모의투자 주문가능금액이 부족합니다."}
|
||||||
)
|
)
|
||||||
@@ -2896,9 +2984,11 @@ class TestBuyCooldown:
|
|||||||
)
|
)
|
||||||
overseas_broker.get_overseas_balance = AsyncMock(return_value={
|
overseas_broker.get_overseas_balance = AsyncMock(return_value={
|
||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [{"frcr_dncl_amt_2": "50000", "frcr_evlu_tota": "50000",
|
"output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
|
||||||
"frcr_buy_amt_smtl": "0"}],
|
|
||||||
})
|
})
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000"}}
|
||||||
|
)
|
||||||
overseas_broker.send_overseas_order = AsyncMock(
|
overseas_broker.send_overseas_order = AsyncMock(
|
||||||
return_value={"rt_cd": "1", "msg1": "기타 오류 메시지"}
|
return_value={"rt_cd": "1", "msg1": "기타 오류 메시지"}
|
||||||
)
|
)
|
||||||
@@ -3293,9 +3383,12 @@ async def test_buy_suppressed_when_open_position_exists() -> None:
|
|||||||
overseas_broker.get_overseas_balance = AsyncMock(
|
overseas_broker.get_overseas_balance = AsyncMock(
|
||||||
return_value={
|
return_value={
|
||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [{"frcr_dncl_amt_2": "10000", "frcr_evlu_tota": "10000", "frcr_buy_amt_smtl": "0"}],
|
"output2": [{"frcr_evlu_tota": "10000", "frcr_buy_amt_smtl": "0"}],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "10000"}}
|
||||||
|
)
|
||||||
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "OK"})
|
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "OK"})
|
||||||
|
|
||||||
engine = MagicMock(spec=ScenarioEngine)
|
engine = MagicMock(spec=ScenarioEngine)
|
||||||
@@ -3357,9 +3450,12 @@ async def test_buy_proceeds_when_no_open_position() -> None:
|
|||||||
overseas_broker.get_overseas_balance = AsyncMock(
|
overseas_broker.get_overseas_balance = AsyncMock(
|
||||||
return_value={
|
return_value={
|
||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [{"frcr_dncl_amt_2": "50000", "frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
|
"output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000"}}
|
||||||
|
)
|
||||||
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "OK"})
|
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "OK"})
|
||||||
|
|
||||||
engine = MagicMock(spec=ScenarioEngine)
|
engine = MagicMock(spec=ScenarioEngine)
|
||||||
@@ -3460,13 +3556,15 @@ class TestOverseasBrokerIntegration:
|
|||||||
"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10"}],
|
"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10"}],
|
||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_dncl_amt_2": "50000.00",
|
|
||||||
"frcr_evlu_tota": "60000.00",
|
"frcr_evlu_tota": "60000.00",
|
||||||
"frcr_buy_amt_smtl": "50000.00",
|
"frcr_buy_amt_smtl": "50000.00",
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
|
||||||
|
)
|
||||||
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
|
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
|
||||||
|
|
||||||
engine = MagicMock(spec=ScenarioEngine)
|
engine = MagicMock(spec=ScenarioEngine)
|
||||||
@@ -3534,13 +3632,15 @@ class TestOverseasBrokerIntegration:
|
|||||||
"output1": [],
|
"output1": [],
|
||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_dncl_amt_2": "50000.00",
|
|
||||||
"frcr_evlu_tota": "50000.00",
|
"frcr_evlu_tota": "50000.00",
|
||||||
"frcr_buy_amt_smtl": "0.00",
|
"frcr_buy_amt_smtl": "0.00",
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
}
|
}
|
||||||
)
|
)
|
||||||
|
overseas_broker.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
|
||||||
|
)
|
||||||
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
|
overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
|
||||||
|
|
||||||
engine = MagicMock(spec=ScenarioEngine)
|
engine = MagicMock(spec=ScenarioEngine)
|
||||||
@@ -3963,7 +4063,6 @@ class TestSyncPositionsFromBroker:
|
|||||||
"output2": [
|
"output2": [
|
||||||
{
|
{
|
||||||
"frcr_evlu_tota": "50000",
|
"frcr_evlu_tota": "50000",
|
||||||
"frcr_dncl_amt_2": "10000",
|
|
||||||
"frcr_buy_amt_smtl": "40000",
|
"frcr_buy_amt_smtl": "40000",
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
@@ -4131,7 +4230,7 @@ class TestSyncPositionsFromBroker:
|
|||||||
|
|
||||||
balance = {
|
balance = {
|
||||||
"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10", "pchs_avg_pric": "170.0"}],
|
"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10", "pchs_avg_pric": "170.0"}],
|
||||||
"output2": [{"frcr_evlu_tota": "50000", "frcr_dncl_amt_2": "10000", "frcr_buy_amt_smtl": "40000"}],
|
"output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "40000"}],
|
||||||
}
|
}
|
||||||
broker = MagicMock()
|
broker = MagicMock()
|
||||||
overseas_broker = MagicMock()
|
overseas_broker = MagicMock()
|
||||||
@@ -4789,6 +4888,9 @@ class TestOverseasGhostPositionClose:
|
|||||||
return_value={"output": {"last": str(current_price), "rate": "0.0"}}
|
return_value={"output": {"last": str(current_price), "rate": "0.0"}}
|
||||||
)
|
)
|
||||||
ob.get_overseas_balance = AsyncMock(return_value=balance_data)
|
ob.get_overseas_balance = AsyncMock(return_value=balance_data)
|
||||||
|
ob.get_overseas_buying_power = AsyncMock(
|
||||||
|
return_value={"output": {"ovrs_ord_psbl_amt": "0.00"}}
|
||||||
|
)
|
||||||
ob.send_overseas_order = AsyncMock(return_value=sell_result)
|
ob.send_overseas_order = AsyncMock(return_value=sell_result)
|
||||||
return ob
|
return ob
|
||||||
|
|
||||||
@@ -4811,7 +4913,7 @@ class TestOverseasGhostPositionClose:
|
|||||||
"output1": [
|
"output1": [
|
||||||
{"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}
|
{"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}
|
||||||
],
|
],
|
||||||
"output2": [{"tot_evlu_amt": "10000", "frcr_dncl_amt_2": "10000"}],
|
"output2": [{"tot_evlu_amt": "10000"}],
|
||||||
}
|
}
|
||||||
sell_result = {"rt_cd": "1", "msg1": "모의투자 잔고내역이 없습니다"}
|
sell_result = {"rt_cd": "1", "msg1": "모의투자 잔고내역이 없습니다"}
|
||||||
|
|
||||||
@@ -4887,7 +4989,7 @@ class TestOverseasGhostPositionClose:
|
|||||||
current_price = 250.0
|
current_price = 250.0
|
||||||
balance_data = {
|
balance_data = {
|
||||||
"output1": [{"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}],
|
"output1": [{"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}],
|
||||||
"output2": [{"tot_evlu_amt": "100000", "frcr_dncl_amt_2": "100000"}],
|
"output2": [{"tot_evlu_amt": "100000"}],
|
||||||
}
|
}
|
||||||
sell_result = {"rt_cd": "1", "msg1": "일시적 오류가 발생했습니다"}
|
sell_result = {"rt_cd": "1", "msg1": "일시적 오류가 발생했습니다"}
|
||||||
|
|
||||||
@@ -4946,3 +5048,71 @@ class TestOverseasGhostPositionClose:
|
|||||||
and "[ghost-close]" in (c.kwargs.get("rationale") or "")
|
and "[ghost-close]" in (c.kwargs.get("rationale") or "")
|
||||||
]
|
]
|
||||||
assert not ghost_close_calls, "Ghost-close must NOT be triggered for non-잔고없음 errors"
|
assert not ghost_close_calls, "Ghost-close must NOT be triggered for non-잔고없음 errors"
|
||||||
|
|
||||||
|
|
||||||
|
@pytest.mark.asyncio
|
||||||
|
async def test_kill_switch_block_skips_actionable_order_execution() -> None:
|
||||||
|
"""Active kill-switch must prevent actionable order execution."""
|
||||||
|
db_conn = init_db(":memory:")
|
||||||
|
decision_logger = DecisionLogger(db_conn)
|
||||||
|
|
||||||
|
broker = MagicMock()
|
||||||
|
broker.get_current_price = AsyncMock(return_value=(100.0, 0.5, 0.0))
|
||||||
|
broker.get_balance = AsyncMock(
|
||||||
|
return_value={
|
||||||
|
"output1": [],
|
||||||
|
"output2": [
|
||||||
|
{
|
||||||
|
"tot_evlu_amt": "100000",
|
||||||
|
"dnca_tot_amt": "50000",
|
||||||
|
"pchs_amt_smtl_amt": "50000",
|
||||||
|
}
|
||||||
|
],
|
||||||
|
}
|
||||||
|
)
|
||||||
|
broker.send_order = AsyncMock(return_value={"msg1": "OK"})
|
||||||
|
|
||||||
|
market = MagicMock()
|
||||||
|
market.name = "Korea"
|
||||||
|
market.code = "KR"
|
||||||
|
market.exchange_code = "KRX"
|
||||||
|
market.is_domestic = True
|
||||||
|
|
||||||
|
telegram = MagicMock()
|
||||||
|
telegram.notify_trade_execution = AsyncMock()
|
||||||
|
telegram.notify_fat_finger = AsyncMock()
|
||||||
|
telegram.notify_circuit_breaker = AsyncMock()
|
||||||
|
telegram.notify_scenario_matched = AsyncMock()
|
||||||
|
|
||||||
|
settings = MagicMock()
|
||||||
|
settings.POSITION_SIZING_ENABLED = False
|
||||||
|
settings.CONFIDENCE_THRESHOLD = 80
|
||||||
|
|
||||||
|
try:
|
||||||
|
KILL_SWITCH.new_orders_blocked = True
|
||||||
|
await trading_cycle(
|
||||||
|
broker=broker,
|
||||||
|
overseas_broker=MagicMock(),
|
||||||
|
scenario_engine=MagicMock(evaluate=MagicMock(return_value=_make_buy_match())),
|
||||||
|
playbook=_make_playbook(),
|
||||||
|
risk=MagicMock(),
|
||||||
|
db_conn=db_conn,
|
||||||
|
decision_logger=decision_logger,
|
||||||
|
context_store=MagicMock(
|
||||||
|
get_latest_timeframe=MagicMock(return_value=None),
|
||||||
|
set_context=MagicMock(),
|
||||||
|
),
|
||||||
|
criticality_assessor=MagicMock(
|
||||||
|
assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
|
||||||
|
get_timeout=MagicMock(return_value=5.0),
|
||||||
|
),
|
||||||
|
telegram=telegram,
|
||||||
|
market=market,
|
||||||
|
stock_code="005930",
|
||||||
|
scan_candidates={},
|
||||||
|
settings=settings,
|
||||||
|
)
|
||||||
|
finally:
|
||||||
|
KILL_SWITCH.clear_block()
|
||||||
|
|
||||||
|
broker.send_order.assert_not_called()
|
||||||
|
|||||||
38
tests/test_strategy_exit_rules.py
Normal file
38
tests/test_strategy_exit_rules.py
Normal file
@@ -0,0 +1,38 @@
|
|||||||
|
from src.strategy.exit_rules import ExitRuleConfig, ExitRuleInput, evaluate_exit
|
||||||
|
from src.strategy.position_state_machine import PositionState
|
||||||
|
|
||||||
|
|
||||||
|
def test_hard_stop_exit() -> None:
|
||||||
|
out = evaluate_exit(
|
||||||
|
current_state=PositionState.HOLDING,
|
||||||
|
config=ExitRuleConfig(hard_stop_pct=-2.0, arm_pct=3.0),
|
||||||
|
inp=ExitRuleInput(current_price=97.0, entry_price=100.0, peak_price=100.0),
|
||||||
|
)
|
||||||
|
assert out.should_exit is True
|
||||||
|
assert out.reason == "hard_stop"
|
||||||
|
|
||||||
|
|
||||||
|
def test_take_profit_exit_for_backward_compatibility() -> None:
|
||||||
|
out = evaluate_exit(
|
||||||
|
current_state=PositionState.HOLDING,
|
||||||
|
config=ExitRuleConfig(hard_stop_pct=-2.0, arm_pct=3.0),
|
||||||
|
inp=ExitRuleInput(current_price=104.0, entry_price=100.0, peak_price=104.0),
|
||||||
|
)
|
||||||
|
assert out.should_exit is True
|
||||||
|
assert out.reason == "arm_take_profit"
|
||||||
|
|
||||||
|
|
||||||
|
def test_model_assist_exit_signal() -> None:
|
||||||
|
out = evaluate_exit(
|
||||||
|
current_state=PositionState.ARMED,
|
||||||
|
config=ExitRuleConfig(model_prob_threshold=0.62, arm_pct=10.0),
|
||||||
|
inp=ExitRuleInput(
|
||||||
|
current_price=101.0,
|
||||||
|
entry_price=100.0,
|
||||||
|
peak_price=105.0,
|
||||||
|
pred_down_prob=0.8,
|
||||||
|
liquidity_weak=True,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
assert out.should_exit is True
|
||||||
|
assert out.reason == "model_liquidity_exit"
|
||||||
30
tests/test_strategy_state_machine.py
Normal file
30
tests/test_strategy_state_machine.py
Normal file
@@ -0,0 +1,30 @@
|
|||||||
|
from src.strategy.position_state_machine import (
|
||||||
|
PositionState,
|
||||||
|
StateTransitionInput,
|
||||||
|
promote_state,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
def test_gap_jump_promotes_to_armed_directly() -> None:
|
||||||
|
state = promote_state(
|
||||||
|
PositionState.HOLDING,
|
||||||
|
StateTransitionInput(
|
||||||
|
unrealized_pnl_pct=4.0,
|
||||||
|
be_arm_pct=1.2,
|
||||||
|
arm_pct=2.8,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
assert state == PositionState.ARMED
|
||||||
|
|
||||||
|
|
||||||
|
def test_exited_has_priority_over_promotion() -> None:
|
||||||
|
state = promote_state(
|
||||||
|
PositionState.HOLDING,
|
||||||
|
StateTransitionInput(
|
||||||
|
unrealized_pnl_pct=5.0,
|
||||||
|
be_arm_pct=1.2,
|
||||||
|
arm_pct=2.8,
|
||||||
|
hard_stop_hit=True,
|
||||||
|
),
|
||||||
|
)
|
||||||
|
assert state == PositionState.EXITED
|
||||||
37
workflow/issue-271-runlog.md
Normal file
37
workflow/issue-271-runlog.md
Normal file
@@ -0,0 +1,37 @@
|
|||||||
|
# Issue #271 Workflow Run Log
|
||||||
|
|
||||||
|
## 2026-02-26
|
||||||
|
|
||||||
|
### Step 1: Gitea issue creation
|
||||||
|
- Attempt 1: Succeeded, but formatting degraded
|
||||||
|
- Command style: `tea issues create -t ... -d "...\n..."`
|
||||||
|
- Symptom: Issue body rendered literal `\n` text in web UI instead of line breaks
|
||||||
|
- Root cause
|
||||||
|
- `tea` does not provide `--description-file`
|
||||||
|
- Shell-escaped `\n` inside double quotes is passed as backslash+n text
|
||||||
|
- Resolution
|
||||||
|
- Build body with heredoc and pass as variable (`-d "$ISSUE_BODY"`)
|
||||||
|
|
||||||
|
### Step 2: PR description creation
|
||||||
|
- Attempt 1: Succeeded, but same newline rendering risk detected
|
||||||
|
- Resolution
|
||||||
|
- Same heredoc variable pattern applied for PR body (`--description "$PR_BODY"`)
|
||||||
|
|
||||||
|
### Preventive Action
|
||||||
|
- `docs/workflow.md` updated with "Gitea CLI Formatting Troubleshooting" section
|
||||||
|
- Standard command templates added for issues and PRs
|
||||||
|
|
||||||
|
### Reusable Safe Template
|
||||||
|
```bash
|
||||||
|
ISSUE_BODY=$(cat <<'EOF'
|
||||||
|
## Summary
|
||||||
|
- item A
|
||||||
|
- item B
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
- docs only
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
|
||||||
|
tea issues create -t "title" -d "$ISSUE_BODY"
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user