feat: add portfolio snapshot read layer

2026-06-06 09:33:00 +09:00
parent 56e977a7ad
commit ca757009f5
51 changed files with 3565 additions and 51 deletions
@@ -0,0 +1,135 @@
+# 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.