trex-core/docs/batches/bat-053_20260628_daystart-credential-fetch-failsafe/implementation.md

BAT-053: Implementation

변경 파일 목록

신규/확장 모듈

파일	변경 유형	관련 REQ
trex_core/application/portfolio.py	확장	REQ-112
trex_core/adapters/portfolio/hub_read.py	확장	REQ-112
trex_core/adapters/portfolio/stub_read.py	확장	REQ-112
trex_core/runtime/config.py	확장	REQ-113
trex_core/application/snapshot_scheduler.py	확장	REQ-113/114/115
trex_core/application/intents.py	확장	REQ-114
trex_core/runtime/daemon.py	확장 (조립)	REQ-113/114

신규 테스트

파일	관련 REQ
tests/adapters/portfolio/test_hub_read.py (확장)	REQ-112 AC-1~7
tests/adapters/portfolio/test_stub_read.py (확장)	REQ-112 AC-6
tests/runtime/test_instance_config.py (확장)	REQ-113 AC-1,7
tests/application/test_snapshot_scheduler.py (확장)	REQ-114 AC-1~9, REQ-115 AC-3/6

REQ별 구현 요약

REQ-112: BrokerCredentialPayload + TradingContext + 포트 메서드 + 어댑터

• application/portfolio.py:
  • BrokerCredentialPayload(account_ref, app_key, app_secret, credential_version) frozen dataclass 추가
  • TradingContext(broker, trading_enabled) frozen dataclass 추가
  • PortfolioHubReadPort.fetch_broker_credential() -> TradingContext 포트 메서드 추가
• adapters/portfolio/hub_read.py:
  • whoami() 내부 로직을 _fetch_user_info() -> dict 헬퍼로 추출 — 외부 동작 불변(AC-5 회귀 보존)
  • fetch_broker_credential() 구현: broker null → TradingContext(broker=None), credential_payload null → TradingContext(broker=None), 성공 → BrokerCredentialPayload 반환
  • NFR-2: app_secret 평문 로그 없음 — 어댑터 내 로깅 코드에 app_secret 미포함
• adapters/portfolio/stub_read.py:
  • trading_context: Optional[TradingContext], fetch_broker_raises: bool 인자 추가
  • fetch_broker_credential() stub 구현 — 네트워크 없이 결정론적 반환/예외

REQ-113: credential_fetch_enabled opt-in + break-glass

• runtime/config.py:
  • DaemonInstanceConfig.credential_fetch_enabled: bool = False 추가 (TOML opt-in, 기본 False)
  • DaemonInstanceConfig.from_toml(): credential_fetch_enabled 파싱 (부재 시 False)
  • DaemonConfig.credential_fetch_enabled: bool = False 추가
  • DaemonConfig.from_config(): inst.credential_fetch_enabled → DaemonConfig 전파
  • DaemonConfig.from_env(): 변경 없음 → 항상 False (AC-1 회귀 0)
• application/snapshot_scheduler.py:
  • 생성자 credential_fetch_enabled: bool = False 인자 추가
  • 초기화 시 TREX_KIS_BROKER_BREAK_GLASS env 감지(break-glass 플래그)
  • break-glass: INFO 로그 후 env-only 경로(fetch 없이 entry_allowed=True)

REQ-114: 그날-시작 로드 게이트 + fail-closed + 알람

• application/snapshot_scheduler.py:
  • _entry_allowed: bool = True 상태 추가
  • _maybe_fetch_credential(): fail-closed 3조건 처리 + CRITICAL 알람 DAY_START_LOAD_FAILED 발신
  • run_once() 선두: credential_fetch_enabled=True이면 _maybe_fetch_credential() 호출
  • get_entry_allowed() -> bool 노출
• application/intents.py:
  • IntentService 생성자 entry_allowed_fn: Optional[Callable[[], bool]] = None 추가
  • _admit_buy() 선두: entry_allowed_fn is not None and not entry_allowed_fn() → reject day_start_load_failed
  • SellIntent(_admit_sell) 변경 없음 — 청산 경로 영향 없음 (AC-5)
• runtime/daemon.py:
  • SnapshotScheduler 생성 후 entry_allowed_fn = scheduler.get_entry_allowed를 IntentService에 주입
  • credential_fetch_enabled=False(기본) → entry_allowed_fn=None → 게이트 비활성

REQ-115: 그날 고정 캐시 + 장중 무중단

• application/snapshot_scheduler.py:
  • _cached_credential: Optional[BrokerCredentialPayload], _credential_date: Optional[date] 추가
  • _maybe_fetch_credential(): _credential_date == today 시 재fetch 생략 (그날 고정 캐시, AC-3)
  • 성공 시 캐시 저장 + INFO 로그(account_ref/trading_enabled/credential_version; app_secret 미포함)
  • Redis 등 외부 저장소 기록 없음 — 메모리 한정 (AC-5)

설계 결정 반영 확인

• D1(entry_allowed 위치): SnapshotScheduler 내 + IntentService callable 주입 — 구현됨
• D2(credential_fetch_enabled 전파): DaemonInstanceConfig → DaemonConfig → SnapshotScheduler — 구현됨
• D3(우선순위 로직 위치): SnapshotScheduler._maybe_fetch_credential() — 구현됨
• D4(그날 고정 캐시): _credential_date 비교로 동일 날짜 재fetch 방지 — 구현됨
• D5(중장기 후크): BAT-053에서는 단기 07:30 경로(run_once())만 구현. 중장기는 동일 run_once() 경유로 처리됨 — 확인
• D6(AlarmEmitter): publish_alarm("DAY_START_LOAD_FAILED", ...) 직접 호출 패턴 — 구현됨

주요 설계 메모

• credential_fetch_enabled=False(기본)일 때: _maybe_fetch_credential() 미호출 → _entry_allowed=True 고정 → IntentService entry_allowed_fn=None → 게이트 완전 비활성. 기존 동작 byte-for-byte 보존(회귀 0).
• KISBroker 재조립(fetch 결과를 실제 KIS API에 적용)은 BAT-053 범위 외 — M3 별도 batch. 현재 _cached_credential이 메모리에 저장되어 있으며 다음 batch에서 KISBroker 재초기화에 활용.
• REQ-115 AC-2(ledger_outbox 무손실): 기존 REQ-019 구현 속성 재확인. 별도 구현 불필요, 기존 테스트 그린(745 passed).