# req-008: 슬롯 read-only 조회 HTTP API

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

## Intent
- 매도 전략이 보유 슬롯을 평가하고 운영자가 가용성을 모니터링할 수 있도록, 코어가 슬롯 스냅샷과 capacity 를 read-only 로 제공한다.

## Requirement
- `GET /v1/slots?status=holding`(status/trading_date 필터)로 슬롯 스냅샷을 read-only 로 반환하고, `GET /v1/capacity` 로 idle/holding/pending 카운트 + scarcity_ratio 를 반환한다. 이 엔드포인트는 슬롯을 쓰지 않는다(read-only).

## Acceptance Criteria
1. Given holding 슬롯이 있는 상태, When `GET /v1/slots?status=holding`, Then 해당 슬롯 스냅샷 목록을 반환한다(쓰기 부작용 없음).
2. Given status/trading_date 필터, When 조회, Then 필터에 맞는 슬롯만 반환한다.
3. Given 슬롯 분포, When `GET /v1/capacity`, Then idle/holding/pending 카운트와 scarcity_ratio 를 반환한다.

## Impacted Area
- Docs: docs/interface-contract.md(조회 API 계약) — REQ-009 에서 정합
- Modules: trex_core/ 하위 API 어댑터(읽기 라우터); 도메인 `compute_slot_capacity`/repo 조회 재사용
- Tests: 조회 API 통합테스트

## Notes
- 엔드포인트 집합은 dcy-002 OQ-3 결정. REQ-005(런타임)·REQ-006(영속화) 선행.
- read-only 라 단일 writer 불변식과 무관(쓰기 경로 아님).
- 출처: dcy-002 FR-3.

## Change Log

### CHG-20260603-01
- Date: 2026-06-03
- Author: Justin Ko

#### Change Summary
- dcy-002 FR-3 로부터 최초 생성(Proposed).

#### Intent
- 슬롯 read-only 조회 API 요구사항을 backlog 로 정규화.

#### Acceptance Criteria Delta
- Added:
  - holding 스냅샷, 필터, capacity 3개 기준
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta
- Docs:
  - docs/interface-contract.md
- Modules:
  - API 어댑터(읽기 라우터)
- Tests:
  - 조회 API 통합테스트

#### 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 편성

#### Validation Plan
- 조회 API 통합테스트(스냅샷/필터/capacity)로 검증.

### CHG-20260603-02
- Date: 2026-06-03
- Author: Justin Ko

#### Change Summary
- Status Proposed → Approved (confirm-req).

#### Intent
- 승인 게이트(필수 필드·구체 AC·blocker 없음) 충족, source dcy-002(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-002 release-candidate).

#### Intent
- BAT-002 verification.md 의 acceptance mapping + evidence(pytest 74 pass / PG 통합 / 데몬 E2E)로 모든 AC 충족 → 구현 완료 동기화.

#### Acceptance Criteria Delta
- Added:
  - 없음
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta
- Docs:
  - docs/srs/index.md (Register Implemented)
- Modules:
  - 없음
- Tests:
  - 없음

#### Delivery Trace Delta
- Batches:
  - BAT-002 (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-002 verification evidence 재참조로 충분.