# req-007: intent 제출 HTTP API + 멱등

- Status: Implemented
- 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 를 검증 기준으로 사용.

### 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 재참조로 충분.

### CHG-20260608-01

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

#### Change Summary

- (change-req, dcy-011) buy intent admission 계약 변경: `portfolio_id` 필수화 + admission 시 universe(`SnapshotStore`) 에서 `symbol` resolve + universe 부재 시 `unknown_portfolio` 거부. 기존 symbol-필수/portfolio_id-optional 폐기(hard cutover, 하위호환 없음). BAT-015 에서 재구현·재검증 완료 → Implemented 유지.

#### Intent

- 정식 식별자(asset_id=portfolio_id) 기반 원장 귀속·safety 보호 범위 정합(issue #6). `_admit_buy` 에 portfolio_id_required/unknown_portfolio reject + symbol resolve(`resolve_symbol` 주입) 추가.

#### Acceptance Criteria Delta

- Added:
  - buy 는 portfolio_id 필수(누락 시 `portfolio_id_required`), symbol 은 서버 resolve(`SnapshotStore`), universe 부재 시 `unknown_portfolio` 거부.
- Updated:
  - 기존 admission AC 의 symbol 입력 전제 → portfolio_id 기반으로 정정.

#### Impacted Area Delta

- Modules: `trex_core/application/intents.py`(BuyIntent portfolio_id 필수+symbol resolve, IntentService.resolve_symbol), `messaging_handlers.py`(buy payload), `runtime/daemon.py`(resolver 배선)
- Docs: `docs/interface-contract.md`, `docs/runtime-flows.md`
- Tests: intent/messaging buy 테스트 portfolio_id 기반 전환

#### Delivery Trace Delta

- Batches: BAT-015
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes (BAT-015 에서 완료)
- Existing Implementation Invalidated: yes (symbol-필수 admission 경로)
- Status Recommendation: Implemented (change-req → BAT-015 재구현·재검증)
- Follow-up Action: confirm-req-implemented(BAT-015) 로 Implemented 동기화.

#### Validation Plan

- BAT-015 verification: portfolio_id_required/unknown_portfolio/symbol resolve 단위 + 전체 회귀(314 passed).

### CHG-20260608-02

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

#### Change Summary

- (change-req, dcy-012) sell intent 계약에 optional 매도 가격 필드 추가: `SellIntent.limit_price`(+ sell payload `limit_price`) → `_admit_sell` 이 슬롯 `limit_price` 로 운반. 지정 시 지정가 매도, 미지정 시 시장가(자율 매도 기본 경로). buy 의 `entry_price` 는 동일 슬롯 `limit_price` 로 매핑(동작 동일). BAT-016 재구현·재검증 완료 → Implemented 유지.

#### Intent

- 매도 가격 하이브리드 정책(가격 유무 분기, dcy-012 OQ-1/OQ-2)을 intent 제출 계약에 반영. 기존 재량 매도 호출(가격 미지정)은 시장가로 안전 동작(NFR-3).

#### Acceptance Criteria Delta

- Added:
  - sell intent/payload optional `limit_price`(미지정 → 시장가, 지정 → 지정가). admission 이 슬롯 limit_price 로 운반.

#### Impacted Area Delta

- Modules: `trex_core/application/intents.py`(SellIntent/_admit_sell, _admit_buy limit_price 매핑), `trex_core/application/messaging_handlers.py`(sell payload limit_price)
- Docs: docs/interface-contract.md
- Tests: tests/application/test_sell_pricing.py

#### Delivery Trace Delta

- Batches: BAT-016
- Releases: none

#### Revalidation Impact

- Reverification Needed: yes (BAT-016 에서 완료)
- Existing Implementation Invalidated: no (optional 추가, 기존 sell 호출 시장가로 호환)
- Status Recommendation: Implemented (change-req → BAT-016 재검증)
- Follow-up Action: confirm-req-implemented(BAT-016).

#### Validation Plan

- BAT-016: 가격 전달 매도 → 지정가 / 미전달 → 시장가 단위 + 핸들러 payload.