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>
This commit is contained in:
2026-06-10 10:28:38 +09:00
co-authored by Claude Opus 4.8
parent 1db7ab13bb
commit e2a71e50e2
13 changed files with 676 additions and 24 deletions
@@ -0,0 +1,64 @@
# req-057: 자산 영구 슬롯 상태머신 재정의 + 인스턴스 스코프 advisory lock
- Status: Proposed
- Type: Interface
- Priority: High
- Owner: project maintainers
## Intent
- 영구 자산 슬롯에 맞춰 슬롯 상태머신을 재정의하고, holding 을 코어 로컬 정본으로 두며, 공유 DB 다중 인스턴스에서 단일 writer 불변식을 인스턴스 단위로 보존한다. (dcy-020 FR-6/FR-3/NFR-1)
## Requirement
- 상태 집합을 `inactive → pending_buy → holding → pending_sell → inactive` (+ 모든 비-error → `error`, `error → {inactive, holding}` 운영자 resolve)로 재정의한다. 기존 `idle`·`closed` 는 영구 슬롯에서 단일 `inactive` 로 합치고 `closed→idle` 복구 전이를 제거한다. `holding`(포지션 열림)은 코어 슬롯의 로컬 정본으로 체결 시 동기 set, 매도 체결 시 동기 clear 한다(portfolio-hub `asset_quantity` 로 판단하지 않음). advisory lock 을 **인스턴스 스코프**(`pg_advisory_xact_lock(SLOT_LOCK_ID, hash(instance_key))`)로 두어 인스턴스 간 교차 직렬화를 제거한다.
## Acceptance Criteria
1. Given 상태머신, When 허용 전이 집합을 확인, Then `{inactive→pending_buy, pending_buy→holding, pending_buy→inactive, holding→pending_sell, pending_sell→inactive, pending_sell→holding, *→error, error→inactive, error→holding}` 와 정확히 일치한다.
2. Given 영구 슬롯, When 매도 체결로 종료, Then 슬롯은 `inactive` 로 돌아가고(별도 `closed`·`closed→idle` 없음) holding 로컬 플래그가 clear 된다.
3. Given 서로 다른 instance_key 의 두 슬롯, When 동시에 전이, Then 인스턴스별 락으로 서로를 차단하지 않는다(교차 경합 없음).
4. Given 같은 슬롯에 대한 동시 전이, When 병렬 처리, Then 인스턴스 스코프 락으로 직렬화되어 단일 writer 불변식이 유지된다.
## Impacted Area
- Docs: docs/runtime-flows.md(전이 흐름), docs/data-model.md(상태)
- Modules: trex_core/domain/slot/state.py, trex_core/domain/slot/service.py, trex_core/domain/slot/models.py
- Tests: tests/domain/slot/test_state.py, tests/domain/slot/test_service.py
## Notes
- 기존 REQ-002(상태머신·서비스) 재정의 change-req 동반. dcy-001 의 6상태/closed→idle 모델 폐기.
- holding 로컬 정본 근거(offline 안전·universe 누락 생존·hub 지연·capacity 원자성)는 dcy-020 FR-3.
- 출처: dcy-020 FR-6, FR-3, NFR-1, OQ-7.
## Change Log
### CHG-20260610-01
- Date: 2026-06-10
- Author: Justin Ko
#### Change Summary
- dcy-020 FR-6/FR-3/NFR-1 로부터 최초 생성(Proposed). 상태머신 재정의(idle/closed→inactive, closed→idle 제거) + holding 로컬 정본 + 인스턴스 스코프 advisory lock.
#### Intent
- 영구 자산 슬롯 상태머신·holding 로컬·인스턴스 단위 단일 writer 를 backlog 로 정규화.
#### Acceptance Criteria Delta
- Added:
- 전이 집합/inactive 종료/인스턴스별 락 비교차/동일 슬롯 직렬화 4개 기준
- Updated: 없음
- Removed: 없음
#### Impacted Area Delta
- Docs: docs/runtime-flows.md, docs/data-model.md
- Modules: domain/slot/state.py, service.py, models.py
- Tests: test_state.py, test_service.py
#### Delivery Trace Delta
- Batches: none
- Releases: none
#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no (신규 정의; REQ-002 재정의 change-req 로 기존 폐기)
- Status Recommendation: keep-current
- Follow-up Action: confirm-req. REQ-002 change-req 동반.
#### Validation Plan
- 전이 허용/거부 집합 + 인스턴스 락 단위테스트 green.