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
parent 1db7ab13bb
commit e2a71e50e2
13 changed files with 676 additions and 24 deletions
@@ -0,0 +1,63 @@
+# req-058: universe 기반 슬롯 lifecycle reconcile (생성/soft-retire/tombstone)
+
+- Status: Proposed
+- Type: Integration
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+- 슬롯 집합을 portfolio-hub universe 의 projection 으로 유지하기 위해, universe fetch 결과로 슬롯을 생성/은퇴하는 reconcile 경로를 정의한다. 일일 preallocation(dcy-014)을 폐기하고 universe 동기화로 대체한다. (dcy-020 FR-1/OQ-2/NFR-3)
+
+## Requirement
+- 스냅샷 refresh(`get_portfolios` 성공 직후)에 슬롯 reconcile 을 수행한다: (1) universe 신규 자산 → 영구 슬롯 즉시 생성(비활성·멱등, `UNIQUE(instance_key, portfolio_id)`); (2) universe 제거 + 슬롯 비활성(holding/pending 아님) → **soft-retire**(`retired_at` 마킹, 행 보존, hard delete 금지); (3) universe 제거 + 보유 중/pending → **tombstone**(은퇴 보류, safety-sell/watchdog 유지, 신규 매수 후보 제외, 닫힌 뒤 은퇴). reconcile 쓰기는 인스턴스 스코프 advisory lock 안에서 단일 writer 로 수행한다. cadence 는 기존 부팅 + 일 1회 + 운영자 on-demand. portfolio-hub 불가/degraded 또는 universe N→0/급격 대량 감소면 생성·은퇴를 보류하고 경고한다.
+
+## Acceptance Criteria
+1. Given universe 에 신규 자산, When reconcile, Then 그 자산의 영구 슬롯이 비활성으로 생성되고 재실행해도 중복 생성되지 않는다(멱등).
+2. Given universe 에서 빠진 비활성 슬롯, When reconcile, Then soft-retire(`retired_at` set, 행 보존)되고, 같은 자산이 재등장하면 동일 슬롯이 재활성화된다.
+3. Given universe 에서 빠졌으나 holding/pending 인 슬롯, When reconcile, Then 은퇴되지 않고 tombstone(신규 매수 제외·safety-sell 유지)되며, 매도 체결 후에야 은퇴된다.
+4. Given portfolio-hub degraded 또는 universe 가 N→0, When reconcile, Then 슬롯 생성·은퇴가 보류되고 마지막 집합이 유지되며 경고가 남는다.
+
+## Impacted Area
+- Docs: docs/runtime-flows.md(reconcile lifecycle)
+- Modules: trex_core/application/snapshot_scheduler.py, trex_core/domain/slot/repository.py, trex_core/adapters/persistence/postgresql.py, trex_core/application/preallocation_scheduler.py(폐기)
+- Tests: tests/application/test_snapshot_scheduler.py(reconcile), tests/application/test_preallocation_scheduler.py(폐기/대체)
+
+## Notes
+- 기존 REQ-005/REQ-048(일일 preallocation·instance config) change-req 동반(preallocation 폐기·재해석). trading_date KST 계산(REQ-005)은 일일 회계 경계용으로 부분 존속.
+- 출처: dcy-020 FR-1, OQ-2, NFR-3.
+
+## Change Log
+
+### CHG-20260610-01
+- Date: 2026-06-10
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-020 FR-1/OQ-2/NFR-3 로부터 최초 생성(Proposed). universe reconcile(생성/soft-retire/tombstone) + degrade·대량소멸 보류 + 일일 preallocation 폐기.
+
+#### Intent
+- 슬롯 집합을 universe projection 으로 유지하는 lifecycle 을 backlog 로 정규화.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 생성 멱등/비활성 soft-retire 재활성/tombstone/degrade·대량소멸 보류 4개 기준
+- Updated: 없음
+- Removed: 없음
+
+#### Impacted Area Delta
+- Docs: docs/runtime-flows.md
+- Modules: snapshot_scheduler.py, repository.py, postgresql.py, preallocation_scheduler.py(폐기)
+- Tests: test_snapshot_scheduler.py, test_preallocation_scheduler.py
+
+#### 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. REQ-005/048 change-req(preallocation 폐기) 동반.
+
+#### Validation Plan
+- reconcile 생성/은퇴/tombstone/degrade 단위·통합 테스트 green.
@@ -0,0 +1,62 @@
+# 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.