Draft+approve REQ-005~009 from dcy-002 (slot-core daemon + API)

Decompose dcy-002 FR-1~FR-6 into five requirements and promote them to Approved (gate passed; source dcy-002 confirmed): - REQ-005 (Installation): slot-core daemon runtime + lifecycle/healthz - REQ-006 (Data): PostgreSQL SlotRepository + schema + drift test - REQ-007 (Interface): intent submission API + idempotency - REQ-008 (Interface): read-only slot/capacity query API - REQ-009 (Documentation): daemon/API/persistence baseline alignment NFR-1/2/3 absorbed into REQ-006/007 acceptance. Update SRS index (Next ID -> REQ-010, register, change log) and dcy-002 created-REQ refs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-04 11:12:34 +09:00
parent 346a580856
commit a44f9fddb7
7 changed files with 570 additions and 3 deletions
@@ -0,0 +1,114 @@
+# req-007: intent 제출 HTTP API + 멱등
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+- 매수·매도 전략 데몬이 HTTP 로 intent 를 제출하면 코어가 단독으로 admission/검증 후 슬롯을 전이하도록 한다(전략은 제안, 코어가 집행). intent_id 멱등으로 재전송 안전을 보장한다.
+
+## Requirement
+- `POST /v1/intents/buy` 와 `POST /v1/intents/sell` 를 제공한다. 코어는 admission/검증 후 슬롯 전이(idle→pending_buy / holding→pending_sell)를 advisory lock 하 단일 writer 로 수행하고, 동기로 admit/reject 를 응답한다. 수락된 intent 는 같은 트랜잭션에서 `intent_log`(intent_id, payload, decision, ts) 에 durable 기록하며 `intent_id` 로 dedup 한다. `GET /v1/intents/{intent_id}` 로 결정을 재조회한다.
+
+## Acceptance Criteria
+1. Given idle 슬롯, When `POST /v1/intents/buy`, Then admission 통과 시 idle→pending_buy 로 전이하고 `{admitted:true, slot_id}` 를 동기 응답한다.
+2. Given holding 슬롯, When `POST /v1/intents/sell`, Then 검증 통과 시 holding→pending_sell 로 전이하고 admit 결과를 동기 응답한다(거부 시 사유 포함).
+3. Given 이미 처리된 `intent_id`, When 동일 intent 재전송, Then 슬롯이 중복 전이되지 않고 최초 결정과 동일한 응답을 돌려준다(멱등). (NFR-3)
+4. Given 동일 슬롯에 대한 동시 intent, When 병렬 처리, Then advisory lock 으로 직렬화되어 단일 writer 불변식이 유지된다(매수·매도 전략은 슬롯을 직접 쓰지 않음). (NFR-2)
+5. Given 수락된 intent, When `GET /v1/intents/{intent_id}`, Then 기록된 decision 을 반환한다.
+
+## Impacted Area
+- Docs: docs/interface-contract.md(HTTP API 계약), docs/runtime-flows.md(요청 흐름) — REQ-009 에서 정합
+- Modules: trex_core/ 하위 API 어댑터(FastAPI 라우터/스키마) + 애플리케이션 서비스; 도메인 패키지는 무의존 유지(NFR-1)
+- Tests: API 통합테스트(정상/거부/멱등 재전송/동시성)
+
+## Notes
+- 동기 커밋 + intent_id 멱등 + intent_log(dcy-002 OQ-1). 완전 비동기 outbox 는 브로커 Discovery 로 Deferred.
+- `intent_log` 테이블은 REQ-006 에서 생성. REQ-005(런타임)·REQ-006(영속화) 선행.
+- NFR-2(단일 writer)·NFR-3(멱등) 흡수.
+- 출처: dcy-002 FR-2, FR-4.
+
+## Change Log
+
+### CHG-20260603-01
+- Date: 2026-06-03
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-002 FR-2·FR-4 로부터 최초 생성(Proposed). NFR-2·NFR-3 흡수.
+
+#### Intent
+- intent 제출 API + 멱등 요구사항을 backlog 로 정규화.
+
+#### Acceptance Criteria Delta
+- Added:
+  - buy/sell 전이, 멱등 재전송, 동시성 단일 writer, intent 재조회 5개 기준
+- Updated:
+  - 없음
+- Removed:
+  - 없음
+
+#### Impacted Area Delta
+- Docs:
+  - docs/interface-contract.md, docs/runtime-flows.md
+- Modules:
+  - API 어댑터(FastAPI) + 애플리케이션 서비스
+- 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 통합테스트(멱등 재전송 + 동시성 직렬화 포함)로 검증.
+
+### 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 를 검증 기준으로 사용.