19 lines
2.3 KiB
Markdown
19 lines
2.3 KiB
Markdown
---
|
|
id: "ac-0002"
|
|
status: 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과 민감정보 비노출을 단언한다.
|