trex-core/docs/srs/Integration/req-062_quantity-hub-authority-and-divergence.md

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 없음.