# req-062: 수량 hub 정본+로컬 미러 + holding↔broker/hub 불일치 해소

- Status: Implemented
- Type: Integration
- Priority: High
- Owner: project maintainers

## Intent
- 보유 수량의 정본을 portfolio-hub 로 두고 슬롯은 미러만 유지하며, 코어 로컬 holding 과 브로커/hub 가 비정상적으로 어긋날 때의 해소 정책을 정의한다. (dcy-020 FR-4/OQ-5/NFR-5)

## Requirement
- 보유 **수량(asset_quantity)의 정본은 portfolio-hub** 이며, 슬롯은 수량을 정본 소유하지 않고 로컬 best-effort 미러(option D write-back/추정)로 둔다. 실제 청산 시 매도 수량은 **브로커 잔고(`get_balance().hldg_qty`)를 정본**으로 조회한다. 불일치 감지는 `reconcile_positions`(REQ-031)를 확장해 **브로커 잔고 + hub 수량 + 코어 슬롯 holding** 3자를 비교하며, 브로커를 ground truth 로 한다. 해소: A(코어 holding/브로커 0) → 슬롯 `error` + 운영자 resolve; B(코어 flat/브로커 보유, 최위험) → WARN/alert + 격리 + 운영자 결정(자동 청산·자동 편입 금지); C(수량만 불일치) → 미러 갱신 + warning, 상태 변경 없음; D(hub 만 지연) → 기존 write-back. **조용한 자동 교정 금지·표면화**, 실주문은 운영자 게이트(issue #15). 감지 reconcile 은 일일 refresh 와 분리해 더 자주 수행 가능(브로커 잔고+슬롯 상태만 필요).

## Acceptance Criteria
1. Given 매도 청산, When 매도 수량 결정, Then 로컬 미러가 stale 해도 브로커 잔고 기준으로 정확히 청산된다. **부분 매도(dcy-021)**: 집행 수량 = `min(intent qty, 브로커 hldg_qty)`; intent 가 잔고 이상이면 전량 매도(→inactive).
2. Given 코어 holding 인데 브로커 0, When reconcile, Then 슬롯이 `error` 로 격리되고 safety-sell 대상에서 빠지며 운영자 resolve 가 요구된다.
3. Given 코어 flat 인데 브로커 보유, When reconcile, Then WARN/alert + 격리되고 자동 청산·자동 편입 없이 운영자 결정으로 넘어간다.
4. Given 둘 다 보유, 수량만 불일치, When reconcile, Then 미러만 갱신되고 상태 전이는 없으며 hub 지속 불일치는 warning 으로 노출된다.
5. Given 사이징 주문(증액/부분 매도)이 일부만 체결(dcy-021), When 집행, Then 실제 체결분만 ledger 기록·슬롯 반영하고 미체결 잔량은 core 가 추적/재시도하지 않는다(재수렴은 전략).

## Impacted Area
- Docs: docs/runtime-flows.md(불일치 해소·write-back)
- Modules: trex_core/application/reconciliation.py, trex_core/application/ledger_outbox.py, trex_core/domain/slot/models.py(qty 미러 의미)
- Tests: tests/application/test_reconciliation.py, tests/application/test_ledger_option_d.py

## Notes
- 기존 REQ-017/019/029/030/031 와 연계(option D write-back 재사용). 슬롯 qty 정본 소유 제거는 REQ-002/006 change-req 와 정합.
- 출처: dcy-020 FR-4, OQ-5, NFR-5.

## Change Log

### CHG-20260610-01
- Date: 2026-06-10
- Author: Justin Ko

#### Change Summary
- dcy-020 FR-4/OQ-5/NFR-5 로부터 최초 생성(Proposed). 수량 hub 정본+미러·청산=브로커·불일치 해소(A/B/C/D, 표면화·운영자 게이트).

#### Intent
- 수량 정본 분리와 holding↔broker/hub 불일치 해소 정책을 backlog 정규화.

#### Acceptance Criteria Delta
- Added: 청산=브로커/A error/B 격리·운영자/C 미러갱신 4개 기준
- Updated: 없음
- Removed: 없음

#### Impacted Area Delta
- Docs: docs/runtime-flows.md
- Modules: application/reconciliation.py, ledger_outbox.py, domain/slot/models.py
- Tests: test_reconciliation.py, test_ledger_option_d.py

#### Delivery Trace Delta
- Batches: none
- Releases: none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no (REQ-031/017/019 연계·확장)
- Status Recommendation: keep-current
- Follow-up Action: confirm-req. REQ-002/006(qty 미러) change-req 정합.

#### Validation Plan
- 청산 브로커 기준 + A/B/C 불일치 해소 단위·통합 테스트 green.

### CHG-20260610-02
- Date: 2026-06-10
- Author: Justin Ko

#### Change Summary
- Status Proposed → Approved (confirm-req). 필수 필드·구체 AC 충족, source dcy-020(confirmed, handoff 승인)과 모순 없음.

#### Intent
- delivery input 으로 승격.

#### Acceptance Criteria Delta
- Added: 없음 / Updated: 없음 / Removed: 없음

#### Impacted Area Delta
- Docs: docs/srs/index.md (Register Approved) / Modules: 없음 / Tests: 없음

#### 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
- 승인 후 batch planning 에서 본 REQ AC 를 검증 기준으로 사용.

### CHG-20260610-IMPL
- Date: 2026-06-10
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-029(M2a 불일치 reconcile)+BAT-030(M2b 매도 수량 브로커 정본) — 모든 AC 가 release-candidate 배치 verification 의 evidence 와 연결됨(단위 367/PG 29/MQ 21 passed + run-the-app 자산 중심 e2e). Blocking Issues 없음.

### CHG-20260610-03
- Date: 2026-06-10
- Author: Justin Ko

#### Change Summary
- dcy-021(포지션 사이징) 반영: 부분 매도 집행 수량 = **`min(intent qty, 브로커 hldg_qty)`**(과매도 방지, 잔고 이상이면 전량→inactive). 사이징 주문 부분 체결 시 **실제 체결분만** ledger/슬롯 반영, 미체결 잔량 미추적(전략 재수렴). 기존 "매도 수량=브로커 정본"의 부분 매도 확장.

#### Intent
- 보유 수량 부분 감액을 브로커 정본 하에 과매도 없이 집행하고, 부분 체결은 실제 거래만 원장에 남긴다(dcy-021 OQ-3, dcy-013 부분 체결 처리 정합).

#### Acceptance Criteria Delta
- Added: AC-5(사이징 부분 체결 → 실제 체결만 반영·미추적)
- Updated: AC-1 에 부분 매도 집행 수량 = min(intent, 브로커 잔고)·이상이면 전량
- Removed: 없음

#### Impacted Area Delta
- Docs: docs/runtime-flows.md, docs/interface-contract.md (REQ-067 정합)
- Modules: trex_core/application/execution.py(부분 매도 dispatch qty), reconciliation.py(불변)
- Tests: tests/application/test_execution*.py(부분 매도 min·부분 체결)

#### Delivery Trace Delta
- Batches: dcy-021 신규 배치(예정)
- Releases: none

#### Revalidation Impact
- Reverification Needed: yes (부분 매도 집행 수량 정책 신규)
- Existing Implementation Invalidated: no (전량 매도=브로커 정본 기존 동작 보존, 부분은 확장)
- Status Recommendation: revert-to-approved (부분 매도 집행 미구현 — dcy-021 배치에서 구현·검증)
- Follow-up Action: dcy-021 배치 구현 후 Implemented 복귀.

#### Validation Plan
- 부분 매도 min(intent,잔고)·잔고 이상 전량·부분 체결 실제만 ledger 단위 + 회귀.

### CHG-20260610-IMPL
- Date: 2026-06-10
- Author: Justin Ko
- Type: status
- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-031(release-candidate) verification — 단위 378 / 통합 422 passed + run-the-app 사이징 e2e(증액 가중평균·부분 매도 잔량·전량 매도) green. Blocking Issues 없음.