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_buy, holding→pending_sell, pending_sell→inactive, pending_sell→holding, *→error, error→inactive, error→holding} 와 정확히 일치한다(dcy-021 CHG-20260610-03: holding→pending_buy 증액 전이 추가).
2. Given 영구 슬롯, When 매도 체결로 종료, Then 슬롯은 inactive 로 돌아가고(별도 closed·closed→idle 없음) holding 로컬 플래그가 clear 된다.
3. Given 서로 다른 instance_key 의 두 슬롯, When 동시에 전이, Then 인스턴스별 락으로 서로를 차단하지 않는다(교차 경합 없음).
4. Given 같은 슬롯에 대한 동시 전이, When 병렬 처리, Then 인스턴스 스코프 락으로 직렬화되어 단일 writer 불변식이 유지된다.
5. Given 보유(holding) 슬롯 증액, When holding→pending_buy 전이, Then 허용되고 체결 시 pending_buy→holding 으로 복귀한다(dcy-021 REQ-066). 부분 매도 잔량은 기존 pending_sell→holding 전이로 holding 을 유지한다.

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

CHG-20260610-03

• Date: 2026-06-10
• Author: Justin Ko

Change Summary

• dcy-021(포지션 사이징, issue #1) 반영: 상태 전이 집합에 holding→pending_buy(보유 슬롯 증액) 를 추가하고, pending_sell→holding(기존)을 부분 매도 잔량 holding 유지 경로로 명시. 전량 매도만 pending_sell→inactive.

Intent

• 보유 자산 슬롯이 holding 을 유지한 채 수량 증액(추가 매수)·부분 감액을 표현하도록 상태머신을 additive 확장(dcy-020 이 고정한 "종료=전량 청산" 경계 해제).

Acceptance Criteria Delta

• Added: AC-5(holding→pending_buy 증액 전이 허용·체결 시 holding 복귀, 부분 매도 잔량 pending_sell→holding)
• Updated: AC-1 허용 전이 집합에 holding→pending_buy 포함
• Removed: 없음

Impacted Area Delta

• Docs: docs/runtime-flows.md, docs/data-model.md (REQ-067 정합)
• Modules: trex_core/domain/slot/state.py(전이 추가), service.py(증액 qty/avg_price = REQ-066)
• Tests: tests/domain/slot/test_state.py(전이 집합·size), test_service.py

Delivery Trace Delta

• Batches: dcy-021 신규 배치(예정)
• Releases: none

Revalidation Impact

• Reverification Needed: yes (전이 집합 변경 — test_state 갱신·증액 경로 검증)
• Existing Implementation Invalidated: no (기존 전이 보존, additive) — 단 AC-1 "정확히 일치"가 신규 전이를 포함하도록 확장되어 재검증 필요
• Status Recommendation: revert-to-approved (신규 전이 미구현 — dcy-021 배치에서 구현·검증 후 confirm-req-implemented)
• Follow-up Action: dcy-021 배치 구현 + test_state 전이 집합 갱신 후 Implemented 복귀.

Validation Plan

• ALLOWED_TRANSITIONS 에 holding→pending_buy 포함·size 갱신 단위 테스트 + 증액 end-to-end(REQ-066).

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