trex-core/docs/srs/Interface/req-057_asset-slot-state-machine.md

req-057: 자산 영구 슬롯 상태머신 재정의 + 인스턴스 스코프 advisory lock

• Status: Implemented
• 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.

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-027(토대)+BAT-030(literal inactive·별칭 제거) — 모든 AC 가 release-candidate 배치 verification 의 evidence 와 연결됨(단위 367/PG 29/MQ 21 passed + run-the-app 자산 중심 e2e). Blocking Issues 없음.