trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08fdf680bf33285903a034d68c5c2796db8c3891
trex-core/docs/srs/Exception/req-031_position-reconciliation-and-warning.md
T
genichinandClaude Opus 4.8 4746f74aae fix(broker): dcy-013 KIS 외부 취소 감지 + 부분 체결 회계 + stale 워치독 (BAT-017) 
KIS 계좌에서 직접 매도 주문을 취소하면 poll_fill 이 cncl_yn 을 파싱하지 않아
슬롯이 pending_sell 에 영구히 갇히고 죽은 주문을 무한 폴링하던 버그(issue #9)
정정.

거버넌스: 전부 change-req (신규 REQ 없음, dcy-013 OQ-3).
- REQ-012: KIS poll_fill cncl_yn 파싱 → 외부 취소 감지. FillStatus.cancelled
  /is_partial_cancel 추가. 체결 0 취소→cancelled, 부분 체결 후 취소→partial+cancelled
- REQ-013: 집행 _on_partial_cancel — 체결분 원장 1회 + qty 차감(매도 잔여/매수 체결분)
  + holding 복귀 (OQ-1 A안). 전량 취소는 기존 롤백 경로 재사용
- REQ-018: 부분 체결분 원장 1회 기록 (_record_ledger 재사용)
- REQ-031: 잔여 포지션 정합 연계 (slot.qty ↔ 실 잔고, 과매도 방지)
- REQ-014: pending stale 워치독 Alert-only (TREX_PENDING_STALE_THRESHOLD,
  WARN+카운터, 상태 미변경) — 취소 감지 누락 backstop
- REQ-015: interface-contract/runtime-flows 정합

전량 취소는 holding 자동 복구(limit_price clear→재매도 시장가, dcy-012 연계).
KIS cncl_yn 실 규약은 운영 검증(미지 값 보수 처리 + 워치독 backstop).

검증: 단위 294 passed/32 skipped, 인프라 게이트(PG+RabbitMQ) 326 passed, ruff clean.
신규 test_kis_cancel(httpx stub) + test_execution_cancel(programmable broker).
BAT-017 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 14:11:49 +09:00

6.3 KiB
Raw Blame History

req-031: 포지션 정합 검증 + warning 마스킹

  • Status: Implemented
  • Type: Exception
  • Priority: High
  • Owner: project maintainers

Intent

  • portfolio-hub 포지션이 실제 브로커 계좌 포지션과 어긋난 자산을 매매에서 보수적으로 제외해, 틀린 baseline 위에서 매매하는 위험을 막는다.

Requirement

  • 스냅샷 페치 시 각 자산에 대해 portfolio-hub 포지션과 실제 브로커 계좌 포지션을 수량 정확 일치(정수 shares, 허용 오차 없음)로 검증한다. 현금은 대상이 아니다(수량만).
  • 브로커 포지션은 KIS 주식잔고조회(실전 TTTC8434R / 모의 VTTC8434R, GET /uapi/domestic-stock/v1/trading/inquire-balance)를 BrokerPort 잔고조회로 조회한다(항목당 pdno+hldg_qty). paper broker 는 결정론 stub.
  • 브로커 잔고는 단일 계좌(불변식 B)라 symbol 단위 집계이므로, portfolio-hub per-portfolio 포지션을 symbol 로 합산해 broker per-symbol hldg_qty 와 대조한다.
  • 불일치 자산은 warning 상태로 표시·응답에서 마스킹하고, 다음 정합 성공 시 자동 해제한다. warning raise 는 매번 로깅한다.

Acceptance Criteria

  1. Given symbol 집계 수량 불일치, When 정합 검증, Then 해당 자산은 warning 으로 표시되고 응답에서 마스킹된다.
  2. Given 이전에 warning 인 자산이 다음 정합에서 수량 일치, When 재검증, Then warning 이 자동 해제되어 다시 응답에 포함된다.
  3. Given paper broker, When 정합 검증, Then 결정론 잔고 stub 로 검증이 수행된다.

Impacted Area

  • Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md
  • Modules: BrokerPort 잔고조회(KIS 주식잔고조회) 확장, 정합 검증 + warning 상태 로직
  • Tests: 수량 불일치 주입, warning 자동 해제, symbol 집계 대조

Notes

  • 정확 일치(tolerance 없음) — A-6(유일 매매 주체)상 정확 일치가 정상이며 tolerance 는 실제 이상을 가린다.
  • 영속 hold 는 pause(REQ-032)로 분리(자동 warning=일시 / 수동 pause=영속).
  • 당일 전량매도분이 hldg_qty=0 으로 D-2 까지 잔고에 남을 수 있음(KIS 015 문서) → 0 수량 잔고 처리 규칙은 설계 시 확정.
  • 참고: docs/broker/kis/rest/국내주식/주문/계좌/015_v1_국내주식-006_주식잔고조회.md. OQ-8 반영.

Change Log

CHG-20260606-01

  • Date: 2026-06-06
  • Author: project maintainers

Change Summary

  • dcy-005 FR-7 + OQ-8 분해로 최초 생성(Proposed).

Intent

  • 포지션 정합 검증 + warning 마스킹/자동 해제 정의.

Acceptance Criteria Delta

  • Added:
    • AC-1~3 신규
  • Updated:
    • none
  • Removed:
    • none

Impacted Area Delta

  • Docs:
    • dcy-005
  • Modules:
    • BrokerPort 잔고조회, 정합/warning 로직
  • Tests:
    • 불일치 주입, 자동 해제

Delivery Trace Delta

  • Batches:
    • none
  • Releases:
    • none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: confirm-req

Validation Plan

  • 불일치 주입 → warning 마스킹 → 일치 복귀 → 자동 해제 시퀀스 테스트로 AC 검증.

CHG-20260606-02

  • Date: 2026-06-06
  • Author: project maintainers

Change Summary

  • 승인 게이트 통과 → Proposed → Approved. D-2 0수량 잔고 처리 규칙은 설계 단계 확정(비블로커).

Acceptance Criteria Delta

  • Added: none
  • Updated: none
  • Removed: none

Impacted Area Delta

  • 변경 없음

Delivery Trace Delta

  • Batches: none
  • Releases: none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: keep-current
  • Follow-up Action: suggest-batch-reqs / draft-batch

Validation Plan

  • 승인 기록. 구현 전 재검증 불필요.

CHG-20260606-03

  • Date: 2026-06-06
  • Author: Justin Ko

Change Summary

  • Status 변경: Approved → Implemented. BAT-008 release-candidate verification evidence 기반.

Intent

  • 정합 검증(reconcile_positions) + warning 자동 set/clear + BrokerPort.get_balance() 확장 구현 완료 상태로 동기화.

Acceptance Criteria Delta

  • Added/Updated/Removed: 없음

Impacted Area Delta

  • Docs/Modules/Tests: 없음

Delivery Trace Delta

  • Batches:
    • BAT-008 (release-candidate)
  • Releases:
    • none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: Implemented
  • Follow-up Action: 실 KIS 환경에서 D-2 0수량 잔고 케이스 관찰 후 운영 노트화 권장 (별도 작업).

Validation Plan

  • AC-1: tests/application/test_reconciliation.py::test_mismatch_raises_warning_and_masks_asset.
  • AC-2: ::test_subsequent_match_auto_clears_warning.
  • AC-3: ::test_paper_broker_returns_deterministic_balance.

CHG-20260608-01

  • Date: 2026-06-08
  • Author: Justin Ko

Change Summary

  • (change-req, dcy-013/issue #9) 부분 체결 후 외부 취소 처리(REQ-013)가 슬롯 qty 를 체결분만큼 차감하고 잔여를 holding 으로 복귀시켜, 슬롯 잔여 수량이 실 브로커 잔고와 정합하도록 보장한다(과매도 방지). 포지션 정합 검증 로직 자체(reconcile_positions)는 코드 변경 없음 — 본 change-req 는 정합 불변식이 유지됨을 명시하는 연계 기록. BAT-017 검증 완료 → Implemented 유지.

Intent

  • 부분 체결+취소에서 slot.qty ↔ 실제 held 수량 정합을 보장해 REQ-031 의 포지션 정합 불변식이 깨지지 않게 한다.

Acceptance Criteria Delta

  • (변경 없음 — reconcile 로직 불변. 부분 취소 회계가 정합 입력을 정확히 유지)

Impacted Area Delta

  • Modules: (없음 — REQ-013 _on_partial_cancel 이 잔여 qty 를 정확히 갱신)
  • Tests: tests/application/test_execution_cancel.py(잔여 qty=6 정합)

Delivery Trace Delta

  • Batches: BAT-017
  • Releases: none

Revalidation Impact

  • Reverification Needed: no (reconcile 코드 불변, 회계 정확성은 REQ-013 테스트로 커버)
  • Existing Implementation Invalidated: no
  • Status Recommendation: Implemented (연계 change-req)
  • Follow-up Action: confirm-req-implemented(BAT-017).

Validation Plan

  • BAT-017: 부분 취소 후 slot.qty 가 잔여 held 와 일치(과매도 0).
Reference in New Issue View Git Blame Copy Permalink