trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
91fee4808d4fccfc2fafc593356d7d39d5dd330d
trex-core/docs/srs/Exception/req-120_kis-balance-auth-failure-fail-loud-lifecycle-policy.md
T

6.7 KiB
Raw Blame History

REQ-120: KIS balance 인증 실패 fail-loud 및 broker/token lifecycle 정책

  • Status: Implemented
  • Type: Exception
  • Priority: High
  • Owner: trex-core-dev

Intent

  • 현재 KIS balance 조회의 token/auth/transport 실패가 빈 잔고와 같은 []로 해석되면 broker_qty_zero, sync skip 또는 잘못된 reconcile 판단으로 이어질 수 있다.
  • 실제 empty holdings와 broker-read 실패를 명확히 분리하고, fetched credential operator 경로의 token/broker lifecycle을 throttle-safe·secret-safe 제약 아래 설계 가능하게 한다.

Requirement

  • 시스템은 KIS token issuance, authentication/authorization, HTTP transport 및 malformed balance response 실패를 성공적인 empty balance와 구별되는 typed 또는 동등하게 식별 가능한 sanitized failure로 표면화해야 한다.
  • sync/verify를 포함한 operator broker-read 경로는 이러한 실패 시 비0 종료하고 broker_qty_zero, sync skip, verify success 또는 slot state write를 생성하지 않아야 한다.
  • fetched credential broker/token lifecycle의 구현 설계는 다음 제약을 충족해야 한다: ownership 경계와 재사용 범위가 명시될 것, 반복 read가 매번 fresh broker/token을 강제해 throttle을 유발하지 않을 것, retry 여부·횟수·backoff/즉시 실패 기준이 failure class별로 문서화될 것, token/credential은 로그·CLI JSON·fixture에 기록되지 않을 것.

Acceptance Criteria

  1. Given KIS token issuance, auth/authorization, transport 또는 malformed response failure fixture, When get_balance()와 sync --dry-run 또는 verify를 실행하면, Then 성공 empty balance와 구별되는 sanitized failure가 반환되고 CLI는 비0으로 종료한다.
  2. Given AC-1의 각 failure, When 결과와 persistence/log side effect를 검사하면, Then broker_qty_zero, sync skip, verify success, slot state write 또는 empty-holdings 판정이 생성되지 않는다.
  3. Given 정상적으로 성공한 KIS balance response가 실제로 holdings 없이 반환됨, When 동일 경로를 실행하면, Then success empty balance semantics는 auth/transport failure와 구별되어 기존 정상 판단이 유지된다.
  4. Given 반복 fetched-credential broker read와 token throttle 재현 fixture, When 구현된 lifecycle 정책을 적용해 읽기를 수행하면, Then fresh-object 생성이 반복되어 throttle을 유발하는 경로에 의존하지 않고, throttle이 발생해도 fail-loud semantics가 유지된다.
  5. Given lifecycle 설계 검토, When implementation-ready decision을 기록하면, Then ownership/reuse scope, cache 또는 reuse 무효화 조건, failure class별 retry/no-retry 정책 및 regression test seam이 명시되며 process-local reuse, shared cache 또는 다른 공통 provider 중 특정 방식을 사전 근거 없이 요구하지 않는다.
  6. Given 오류 출력, 구조화 로그 및 테스트 artifact, When auth/token failure를 검증하면, Then token, authorization header, app key/app secret, raw credential payload 및 raw account number가 노출되지 않는다.

Impacted Area

  • Docs: docs/runtime-flows.md, docs/interface-contract.md, docs/operations.md, docs/srs/Non-Functional/req-115_daystart-intraday-resilience-credential-cache.md
  • Modules: trex_core/adapters/broker/kis.py, trex_core/runtime/cli.py, trex_core/runtime/daemon.py, 공통 broker provider/factory
  • Tests: KIS adapter unit tests; CLI failure/no-write tests; lifecycle/throttle regression fixture; sanitized logging/JSON assertions

Notes

  • Source Discovery: docs/discovery/dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md (FR-2~3, OQ-2; GitHub #40).
  • REQ-115의 day-start/intraday cache 목표와 충돌하지 않아야 한다. 본 REQ는 OQ-2의 구현 방식을 확정하지 않고, 설계 선택의 안전 제약과 검증 가능한 결과를 고정한다.
  • Production live sync target 또는 실행은 OQ-3 release gate로서 범위 밖이다.

Change Log

CHG-20260714-01

  • Date: 2026-07-14
  • Author: delivery-runner

Change Summary

  • dcy-037 #40의 auth/token failure empty-balance masking과 OQ-2 lifecycle 제약을 Proposed REQ로 초안화했다.

Intent

  • false-zero 기반 상태 수렴을 막고 lifecycle 구현 선택을 근거 기반 설계 단계로 남긴다.

Acceptance Criteria Delta

  • Added:
    • fail-loud/no-write, true-empty 분리, throttle 회귀, lifecycle decision constraints 및 secret-safe 증거.
  • Updated:
    • 없음.
  • Removed:
    • 없음.

Impacted Area Delta

  • Docs:
    • runtime/interface/operations 및 REQ-115 정합 대상.
  • Modules:
    • KIS adapter와 daemon/CLI broker-read 경계.
  • Tests:
    • failure injection, no-write, throttle 및 redaction regression.

Delivery Trace Delta

  • Batches:
    • none (draft only; dcy-037 emergency scope의 향후 입력).
  • Releases:
    • none (production 접근 또는 live sync 실행 없음).

Revalidation Impact

  • Reverification Needed: yes
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: confirm-req 전 현재 KIS token cache와 daemon/CLI lifetime evidence를 설계 결정에 연결한다.

Validation Plan

  • mocked KIS failure classes와 repeated-read throttle fixture에서 exit code, semantic result, no-write 및 artifact redaction을 확인한다.

CHG-20260714-02

  • Date: 2026-07-14
  • Author: Justin (TREX lead)

Change Summary

  • Proposed에서 Approved로 승인했다.

Intent

  • dcy-037 #40의 false-zero 방지와 OQ-2 lifecycle 설계 제약을 구현 가능한 safety contract로 확정한다.

Acceptance Criteria Delta

  • Added:
    • 없음.
  • Updated:
    • 없음.
  • Removed:
    • 없음.

Impacted Area Delta

  • Docs:
    • 없음.
  • Modules:
    • 없음.
  • Tests:
    • 없음.

Delivery Trace Delta

  • Batches:
    • dcy-037의 #39/#40/#41 단일 emergency batch (아직 미생성).
  • Releases:
    • none; sync --live는 별도 release approval gate 유지.

Revalidation Impact

  • Reverification Needed: yes
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: batch design에서 lifecycle ownership/reuse와 failure-class별 retry 정책을 code evidence로 결정한다.

Validation Plan

  • batch verification과 독립 QC에서 failure/no-write·true-empty·throttle·redaction AC를 실제 fixture로 재검증한다.

CHG-20260715-03

  • Date: 2026-07-15
  • Author: TREX lead

Change Summary

  • Approved → Implemented (confirm-req-implemented).

Delivery Trace

  • BAT-057 verification confirmed; PR #42 merged to main as 94e148940adb008db0bbd215052a1e984f7c566b.
  • Independent QC: PASS-WITH-NOTES, acceptance blocker 0. Production live sync/deploy remains a separate release gate.
Reference in New Issue View Git Blame Copy Permalink