trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e2a71e50e21e64b6f5c982084f0aba9b8bdf140e
trex-core/docs/srs/Integration/req-062_quantity-hub-authority-and-divergence.md
T
genichinandClaude Opus 4.8 e2a71e50e2 docs(req): dcy-020 confirm + 추가 사양(FR-6~8/NFR-4~5/OQ-8) + draft-req REQ-056~065 
dcy-020(자산 중심 영구 슬롯 모델) Requirements phase.

- 추가 사양: FR-6(상태머신 재정의), FR-7(intent 자산 키), FR-8(운영자 단일뷰),
  NFR-4(전략 계약 호환), NFR-5(불일치 감지 주기), OQ-8(over-cap=신규 차단·기존 유지),
  dcy-019 산출물 제거 명시. review-discovery 정리 반영.
- confirm-discovery: 상태 draft→confirmed, Handoff 승인, Ready=true,
  Confirmed By=Justin Ko, 2026-06-10. index 행 confirmed.
- draft-req: 신규 REQ-056~065(전부 Proposed) 생성
  - 056 영구 슬롯 스키마 / 057 상태머신+인스턴스 lock / 058 universe reconcile
  - 059 capacity·admission / 060 max_active_slots TOML / 061 intent 자산 키
  - 062 수량 hub 정본+불일치 해소 / 063 slots 단일뷰 / 064 cutover / 065 baseline
  - srs/index Next ID→066, Register 10행, Recent Change Log 갱신
  - dcy-020 생성된 REQ 참조 갱신

기존 REQ-002/003/005/006/007/048 폐기·재정의 change-req 는 후속(문서 단계).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 10:28:38 +09:00

3.6 KiB
Raw Blame History

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

  • Status: Proposed
  • 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 해도 브로커 잔고 기준으로 정확히 청산된다.
  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 으로 노출된다.

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.
Reference in New Issue View Git Blame Copy Permalink