trex-core/docs/srs/Interface/req-002_slot-pure-domain-port.md

req-002: slot 순수 도메인 이식 및 공개 API 확정

• Status: Implemented
• Type: Interface
• Priority: High
• Owner: project maintainers

Intent

• 검증된 slot 상태머신/서비스 계약을 인프라에 오염되지 않은 storage-agnostic 코어로 trex-core 에 이식해, trex-core 의 표준 도메인 작성 패턴(순수 도메인 + Protocol 저장소 경계)을 확립한다.

Requirement

• trex-orbit 의 순수 6개 모듈(state/models/errors/repository/service/in_memory_repository)과 __init__.py 를 trex_core.domain.slot 네임스페이스로 이식하고, 모듈 간 import 경로를 trex_core.domain.slot.* 로 통일하며, 공개 API 를 인프라 심볼 없이 노출한다.

Acceptance Criteria

1. Given 이식 완료, When from trex_core.domain.slot import SlotState, Slot, SlotCapacity, SlotTransitionRecord, SlotRepository, SlotService, SlotDomainError, SlotNotFoundError, SlotStateMismatchError, SlotTransitionError, is_allowed_transition, SLOT_ADVISORY_LOCK_ID, ALLOWED_TRANSITIONS 를 실행, Then 모두 import 에 성공한다.
2. Given 이식된 도메인 코드, When 정적 import 스윕, Then stdlib 와 trex_core.domain.slot 내부 참조 외 외부 의존(psycopg/네트워크/CLI/config) import 가 0이다. (NFR-1)
3. Given 공개 API, When __init__.py 의 __all__ 을 확인, Then PostgreSQLSlotRepository·check_slot_domain_schema_drift 등 인프라 심볼이 노출되지 않는다.
4. Given SlotService, When 6 상태/9 base 전이(closed→pending_buy 포함, dcy-019)/advisory-lock 직렬화/closed→idle 재진입 +1/→pending_buy 시 slot entry_count +1(dcy-019)/closed→pending_buy clean-slate 점유 초기화/lock 보유 중 외부 I/O 금지 동작을 확인, Then 보존된다. (NFR-2 — 검증은 REQ-003)

Impacted Area

• Docs: docs/interface-contract.md, docs/data-model.md (계약 기준 — 큰 변경 없을 수 있음)
• Modules: trex_core/domain/slot/{init,state,models,errors,repository,service,in_memory_repository}.py
• Tests: REQ-003 에서 이식 단위테스트 + 계약 테스트로 검증

Notes

• NFR-1(순수 경계)·NFR-2(불변식 보존)를 본 REQ 의 acceptance 로 흡수. NFR-3(컬럼 계약)은 REQ-003 계약 테스트가 강제한다.
• 이식 시 유일한 코드 수정은 __init__.py docstring 정리 수준이며 로직 변경은 없다(dcy-001 A-2).
• 네임스페이스 trex_core.domain.slot 은 dcy-001 OQ-1 결정. REQ-001(부트스트랩) 선행.
• 출처: dcy-001 FR-2.

Change Log

CHG-20260603-01

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

Change Summary

• dcy-001 FR-2 로부터 최초 생성(Proposed). NFR-1·NFR-2 를 acceptance 로 흡수.

Intent

• slot 순수 도메인 이식 + 공개 API 확정 요구사항을 backlog 로 정규화.

Acceptance Criteria Delta

• Added:
  • 공개 API import, 외부 의존 0, 인프라 심볼 비노출, 도메인 불변식 보존 4개 기준
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/interface-contract.md, docs/data-model.md
• Modules:
  • trex_core/domain/slot/* (6 모듈 + init)
• Tests:
  • REQ-003 에 위임

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 후 batch 편성(REQ-001 과 동일 batch 가능)

Validation Plan

• 공개 API import 성공 + import 스윕(외부 의존 0) + REQ-003 테스트 통과로 검증.

CHG-20260603-02

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

Change Summary

• Status Proposed → Approved (confirm-req).

Intent

• 승인 게이트(필수 필드·구체 AC·blocker 없음) 충족, source dcy-001(confirmed, handoff 승인)과 모순 없음 확인.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register 상태 Approved)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • none (batch 편성 전)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs / draft-batch 로 delivery batch 편성

Validation Plan

• 승인 후 batch planning 에서 본 REQ 의 Acceptance Criteria 를 검증 기준으로 사용.

CHG-20260603-03

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

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-001 release-candidate).

Intent

• BAT-001 verification.md 의 evidence(공개 API import / import 스윕 외부 의존 0 / __all__ 인프라 심볼 0 / 도메인 불변식 테스트)로 AC1~AC4 충족 → 구현 완료 동기화.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register Implemented)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • BAT-001 (release-candidate)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: draft-release 로 release 편성

Validation Plan

• BAT-001 verification evidence 재참조로 충분.

CHG-20260608-01

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

Change Summary

• (change-req, dcy-012/issue #10) 슬롯 도메인 필드 entry_price → limit_price(side 무관 "현재 pending 주문 지정가") 내부 rename + 생애주기 정의: pending 진입 시 set, pending 이탈(→HOLDING/→CLOSED) 시 None clear. transit_slot/_apply_transition_fields 파라미터·EXPECTED_SLOT_FIELDS 반영. BAT-016 재구현·재검증 완료 → Implemented 유지.

Intent

• 매수 지정가가 매도 주문에 누수되는 구조적 원인을 도메인 모델에서 제거(clear-on-exit). 가격 필드 의미를 side 무관으로 통일.

Acceptance Criteria Delta

• Updated:
  • Slot.entry_price → limit_price; →HOLDING/→CLOSED 전이 시 limit_price clear, →PENDING_* 전이 시 set.

Impacted Area Delta

• Modules: trex_core/domain/slot/models.py(Slot/EXPECTED_SLOT_FIELDS), trex_core/domain/slot/service.py(transit_slot/_apply_transition_fields clear-on-exit)
• Tests: tests/domain/slot/test_service.py(holding clear), tests/domain/slot/test_contract.py(필드셋)

Delivery Trace Delta

• Batches: BAT-016
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-016 에서 완료)
• Existing Implementation Invalidated: yes (entry_price 필드명/유지 의미)
• Status Recommendation: Implemented (change-req → BAT-016 재검증)
• Follow-up Action: confirm-req-implemented(BAT-016).

Validation Plan

• BAT-016: 전이별 set/clear 단위 + 컬럼 계약 가드(REQ-003) 정합.

CHG-20260609-01

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

Change Summary

• (change-req, dcy-019/issue #18) 슬롯 도메인에 (1) slot-scoped Slot.entry_count(기본 0) 필드 + EXPECTED_SLOT_FIELDS 추가, (2) 상태 머신 허용 전이에 closed→pending_buy(closed 슬롯 직접 재할당) 추가(8→9 base 전이), (3) _apply_transition_fields 에 closed→pending_buy clean-slate 점유 초기화 + 모든 →pending_buy(idle→/closed→) 시 entry_count +1 로직 반영. 기존 daily_symbol_entries(symbol-scoped, AC-3)는 무관·미변경. BAT-025 재구현·재검증 완료 → Implemented 유지.

Intent

• 슬롯 자원을 고르게 재사용(최저 진입 우선)하고 idle 소진 시 closed 재할당을 허용하기 위해, 슬롯 단위 누적 진입 횟수를 도메인 정본에 영속하고 closed→pending_buy 직접 전이를 도메인 계약에 추가.

Acceptance Criteria Delta

• Updated:
  • AC-4: "6 상태/8 전이" → "6 상태/9 base 전이(closed→pending_buy 포함)". 불변식 보존 대상에 →pending_buy 시 entry_count +1, closed→pending_buy clean-slate 점유 초기화 추가.
• Added:
  • Slot.entry_count(int, 기본 0) 필드가 EXPECTED_SLOT_FIELDS 계약에 포함된다.

Impacted Area Delta

• Modules: trex_core/domain/slot/models.py(Slot.entry_count/EXPECTED_SLOT_FIELDS), trex_core/domain/slot/state.py(closed→pending_buy 전이), trex_core/domain/slot/service.py(clean-slate + entry_count +1)
• Tests: tests/domain/slot/test_state.py(전이 카운트 14→15), test_contract.py(필드셋), test_slot_entry_count.py(신규)

Delivery Trace Delta

• Batches: BAT-025
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-025 에서 완료)
• Existing Implementation Invalidated: no (additive — 기존 idle-only 동작은 closed 후보 부재 시 보존, 회귀 green)
• Status Recommendation: Implemented (change-req → BAT-025 재검증)
• Follow-up Action: confirm-req-implemented(BAT-025).

Validation Plan

• BAT-025: 전이 카운트/계약 가드 + entry_count 증분·보존 + closed→pending_buy clean-slate 단위 테스트 green; daily_symbol_entries(AC-3) 회귀 green.