trex-core/docs/batches/bat-025_20260609_slot-entry-count-and-closed-reallocation/design.md

BAT-025 Design

• Status: confirmed
• Batch: BAT-025

설계 목표

• 슬롯 자원을 진입 횟수 기준으로 고르게 재사용하고 idle 소진 시 closed 슬롯을 재할당하도록, slot-scoped entry_count 를 도메인 정본에 영속하고 buy admission 후보를 idle∪closed 로 확장한다. 동시성·계약·기존 동작(회귀) 안전을 보장한다.

1. 슬롯 도메인 필드 (REQ-002)

• Slot.entry_count: int = 0(take_profit_price 뒤, created_at 앞). EXPECTED_SLOT_FIELDS 에 "entry_count" 추가(같은 위치).
• slot-scoped 누적 진입 횟수. daily_symbol_entries(symbol-scoped, AC-3)와 무관 — 본 batch 에서 후자 미변경.

2. 상태 머신 전이 (REQ-002)

• _BASE_TRANSITIONS 에 (CLOSED, PENDING_BUY) 추가(#9). base 7→8 tuple, ALLOWED_TRANSITIONS 14→15.
• docstring "6 states + 9 base allowed transitions" 갱신(* → error family 는 별도 집합이므로 base 카운트는 tuple 8 + 주석 #9).

3. 전이 필드 계산 (REQ-002 / _apply_transition_fields)

• closed→pending_buy clean-slate(limit_price lifecycle 분기 앞): to_state is PENDING_BUY and slot.status is CLOSED 면 점유 필드(symbol/qty/avg_price/limit_price/allocated_capital/order_id/strategy_id/broker_order_id/portfolio_id/sell_strategy_id/forced_close_at/stop_loss_price/take_profit_price)를 None 으로 리셋한 slot 으로 교체 → 이전 사이클 점유가 새 진입에 누수되지 않음. entry_count 는 리셋 대상 제외(누적 보존).
• 이후 generic replace 에서 caller-supplied 값으로 새 진입 필드 적용(None 이면 keep — clean-slate 후이므로 None 유지).
• entry_count +1: new_entry_count = slot.entry_count + (1 if to_state is PENDING_BUY else 0) → idle→ 와 closed→ 모두 +1. 그 외 전이·closed→idle 복구는 보존. replace(..., entry_count=new_entry_count).

4. 후보 selector (REQ-006)

• SlotRepository.find_allocatable_slot(trading_date) Protocol 추가: idle∪closed 후보를 entry_count asc → updated_at asc → slot_id 정렬로 1건(없으면 None). caller 가 advisory lock+재시도로 마지막 후보 경합 처리.
• PG: SELECT {_SLOT_COLUMNS} FROM daily_slot WHERE trading_date=%s AND status IN ('idle','closed') ORDER BY entry_count ASC, updated_at ASC, slot_id ASC LIMIT 1. 기존 find_idle_slot 와 동일하게 FOR UPDATE 미사용(동시성은 transit advisory lock).
• in-memory: idle/closed 후보 중 min(key=(entry_count, updated_at or min, str(slot_id))).

5. persistence flat 매핑 (REQ-006)

• _SLOT_COLUMNS 끝에 entry_count(인덱스 18, 총 19컬럼). update_slot SET 에 entry_count=%s + params. _row_to_slot 에 entry_count=int(row[18]) if row[18] is not None else 0.
• 마이그레이션 008_add_slot_entry_count.sql: ALTER TABLE daily_slot ADD COLUMN IF NOT EXISTS entry_count INTEGER NOT NULL DEFAULT 0(additive·멱등, 004 패턴).

6. admission (REQ-007)

• _admit_buy 재시도 루프: find_idle_slot → find_allocatable_slot. transit from_state 하드코딩 IDLE → slot.status(후보가 idle 이면 idle→, closed 면 closed→ 직접 재할당). 후보 없으면 no_idle_slot 거부. SlotStateMismatchError 시 다음 후보 재시도(경합 보존). 멱등(intent_log dedup) 불변.

7. baseline 문서 (REQ-009)

• data-model.md: daily_slot entry_count 필드, Lifecycle closed→pending_buy, State Rules(전이 패밀리 8 base + clean-slate). 두 카운터 구분.
• runtime-flows.md: buy admission find_allocatable_slot(idle∪closed, entry_count 정렬)·closed 재할당, transit_slot 흐름에 →pending_buy 시 entry_count +1 단계.

테스트 설계

• domain: 전이 카운트(14→15, closed→pending_buy allowed/disallowed 재배치); 계약 가드(EXPECTED_SLOT_FIELDS); entry_count 증분(idle→/non-buy 미증가)·closed→idle 복구 보존; closed→pending_buy clean-slate(미공급 필드 클리어)·+1; selector(none/idle-only/closed 포함/entry_count 오름차순).
• application: closed 재할당 admit(idle 소진 시), idle 우선(closed 보다), 양쪽 소진 reject; 동시성 경합 회귀(test_intent_concurrency).
• PG 게이트: 마이그레이션/드리프트(EXPECTED_SLOT_FIELDS↔information_schema) — entry_count 자동 반영.
• 회귀: 전체 단위(flat 매핑 추가로 인한 slot read/write 무누락) green.