trex-core/docs/srs/Exception/req-031_position-reconciliation-and-warning.md

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.