trex-core/.proofline/criteria/ac-0002.md

id, status

id	status
ac-0002	active

불완전하거나 진행하지 않는 잔고 페이지 체인의 fail-closed 처리

Criterion

KISBroker.get_balance()는 최초 페이지를 포함한 어느 페이지에서든 HTTP/transport 실패, KIS rt_cd 실패, malformed JSON/body/row, response header tr_cont 누락 또는 지원하지 않는 값, F/M이 다음 페이지를 지시하면서 continuation key pair가 비어 있는 상태, 또는 하나의 호출에서 이미 방문한 정규화된 (ctx_area_fk100, ctx_area_nk100) pair가 즉시 또는 비인접하게 다시 나타나는 상태를 만나면 누적한 BalanceItem을 반환해서는 안 된다. non-object row, 누락되거나 정수 변환 불가능한 hldg_qty, 양수 수량인데 빈 pdno인 row는 malformed로 처리하고, hldg_qty <= 0 row는 기존 normalization대로 제외한다. 해당 호출은 유한한 요청 횟수 안에 기존 allow-list의 정제된 BrokerBalanceError로 실패해야 하며, pagination 계약 위반을 이유로 새 public error taxonomy를 추가하거나 partial snapshot을 소비자에 전달해서는 안 된다.

Verification

• 오류 matrix: HTTP status/transport, rt_cd != 0, JSON decode 실패, body non-object, output1 non-list, row non-object, hldg_qty 누락·non-numeric, 양수 수량과 빈 pdno, tr_cont 누락·미지원, F/M과 빈 key pair를 각각 독립 fixture로 검증한다.
• 진행성 조건: 즉시 반복 A → A와 비인접 순환 A → B → A key-pair fixture가 모두 유한한 요청 횟수 안에 BrokerBalanceError를 발생시키고 결과 list를 반환하지 않아야 한다.
• 보존 조건: hldg_qty <= 0 row는 실패가 아니라 제외로 유지하고, 검증된 정상 빈 잔고는 실패로 오인하지 않아야 한다.
• 안전 조건: 예외 code는 기존 BrokerBalanceError allow-list 안에 있어야 하며 pagination/shape 계약 위반은 기존의 정제된 malformed-response 계열로 귀결되어야 한다. 오류 객체나 메시지는 token, credential, raw payload 등 민감한 값을 노출하지 않아야 한다.
• 검사 방법: tests/adapters/broker/test_kis.py에 오류 종류별 parameterized test와 순환 fixture를 두고 예외 code, 호출 횟수, partial-return 부재, 기존 normalization과 민감정보 비노출을 단언한다.