trex-core/docs/srs/Interface/req-007_intent-submission-api.md

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 ∪ closed, dcy-019), When POST /v1/intents/buy, Then find_allocatable_slot(entry_count→updated_at→slot_id 정렬)로 최저 진입 후보를 잡아 slot.status→pending_buy(idle→ 또는 closed→ 직접 재할당) 전이하고 {admitted:true, slot_id} 를 동기 응답한다. idle·closed 모두 소진 시 no_idle_slot 거부.
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 을 반환한다.
6. (CHG-20260610-02, dcy-023/issue #22) Given buy intent payload, Then allocated_capital 은 계약 필드가 아니다 — BuyIntent 에 필드가 없고 admission 경로에서 전달되지 않으며, 외부 발신자가 payload 에 키를 포함해도 unknown key 로 무시된다(즉시 제거, dcy-023 OQ-1).
7. (CHG-20260615-01, issue #27) Given rejected sell intent 응답(intent_type:"sell", status:"rejected"), Then additive retryable: bool 필드가 포함된다 — core 가 소유한 reason→retryable 매핑으로 채워지고 reason 은 유지된다. 매핑: slot_state_changed/slot_not_holding:pending_buy/duplicate_in_flight → true; slot_not_found/slot_not_holding:inactive/slot_not_holding:pending_sell/slot_not_holding:error/bad_request:* → false; 미인식 reason → true(안전 기본 — 멈춘 손절매가 hammering 보다 위험). admitted/processing/buy 응답·기존 필드는 불변(완전 additive·하위호환).

Impacted Area

• Docs: docs/interface-contract.md(HTTP API 계약), docs/runtime-flows.md(요청 흐름) — REQ-009 에서 정합
• Modules: trex_core/ 하위 API 어댑터(FastAPI 라우터/스키마) + 애플리케이션 서비스; 도메인 패키지는 무의존 유지(NFR-1); (CHG-20260610-02) intents.py BuyIntent·admission + messaging_handlers.py payload 파싱 allocated_capital 제거
• 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.

CHG-20260608-03

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

Change Summary

• (change-req, REL-004 사전 run 검증에서 발견된 결함 수정) 데몬 buy 심볼 resolver 버그 정정: Daemon._resolve_symbol 이 SnapshotStore.get() 반환값(SnapshotAsset)에서 asset.symbol 을 접근했으나 symbol 은 asset.item.symbol 에 있어 AttributeError → 데몬 buy admission 이 매번 크래시(intent RPC 타임아웃). asset.item.symbol 로 수정. 단위 테스트가 stub resolver 를 주입해 실 데몬 배선을 한 번도 실행하지 않아 369 passed 에도 누락됐다 — 실 데몬 기동 + CLI e2e(REL-004 smoke)에서 검출. Implemented 유지.

Intent

• dcy-011/REQ-007 의 buy 심볼 서버 resolve 가 실 런타임(daemon + SnapshotStore)에서 동작하도록 배선 결함 수정 + 회귀 가드 추가.

Acceptance Criteria Delta

• (변경 없음 — AC 동일; 배선 결함 수정. 실 데몬 resolver 가 SnapshotAsset.item.symbol 을 읽음)

Impacted Area Delta

• Modules: trex_core/runtime/daemon.py(_resolve_symbol → asset.item.symbol)
• Tests: tests/runtime/test_daemon_resolve_symbol.py(실 Daemon._resolve_symbol × 실 SnapshotStore 회귀)

Delivery Trace Delta

• Batches: BAT-015
• Releases: REL-004 (사전 run 검증에서 검출·수정)

Revalidation Impact

• Reverification Needed: yes (REL-004 live smoke + 회귀 테스트로 완료)
• Existing Implementation Invalidated: yes (데몬 buy admission 경로 — 실 런타임에서 전면 실패였음)
• Status Recommendation: Implemented (배선 수정 + 회귀 가드)
• Follow-up Action: REL-004 confirm-release 전 live smoke 증거에 반영.

Validation Plan

• 실 데몬 기동(paper + test PG/RabbitMQ) + trex-core enter pf-005930 --yes → admitted/체결/ledger completed e2e + test_daemon_resolve_symbol 회귀.

CHG-20260609-01

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

Change Summary

• (change-req, dcy-019/issue #18) buy admission(_admit_buy) 의 슬롯 선택을 find_idle_slot → find_allocatable_slot(idle ∪ closed, entry_count→updated_at→slot_id 정렬)로 일반화하고, 후보 status 를 따르도록 transit from_state 를 하드코딩 IDLE → slot.status 로 변경(closed 후보면 closed→pending_buy 직접 재할당). 마지막 슬롯 경합 재시도 루프·멱등(intent_log dedup)·단일 writer 불변식 보존. BAT-025 검증 완료 → Implemented 유지.

Intent

• idle 소진 시에도 closed 슬롯을 재할당해 슬롯 자원을 효율적으로 회전시키고, 슬롯 사용을 진입 횟수 기준으로 고르게 분산.

Acceptance Criteria Delta

• Updated:
  • AC-1: 후보 = idle ∪ closed, find_allocatable_slot 선택 + slot.status→pending_buy 전이(closed 직접 재할당 포함), 양쪽 소진 시 no_idle_slot 거부로 일반화.

Impacted Area Delta

• Modules: trex_core/application/intents.py(_admit_buy: find_allocatable_slot + from_state=slot.status)
• Tests: tests/application/test_buy_admission_reallocation.py(신규: closed 재할당 admit/idle 우선/양쪽 소진 reject), tests/application/test_intent_concurrency.py(경합 회귀 보존)

Delivery Trace Delta

• Batches: BAT-025
• Releases: none

Revalidation Impact

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

Validation Plan

• BAT-025: closed 재할당 admit / idle 우선 / 양쪽 소진 reject 단위 + 동시성 경합 회귀 green.

CHG-20260610-01

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

Change Summary

• (change-req, dcy-020) buy/sell admission 이 자산 중심으로 재정의 예정 — REQ-059(FCFS·M캡·무치환·over-cap)·REQ-061(intent 자산 키 통일, sell-by-slot_id 폐기, already_active/not_holding)가 대체. find_allocatable_slot/idle·closed 배정 폐기. 외부 전략 계약 변경(NFR-4) 동반. 현재 코드 불변이라 Implemented 유지(keep-current), dcy-020 admission/intent 배치에서 확정(외부 계약 cutover 게이트).

Intent

• 신호 기반 자산 admission 전환 추적성 forward-link.

Acceptance Criteria Delta

• Updated: 없음(dcy-020 delivery 배치에서 admission/intent AC 재정의)

Impacted Area Delta

• Docs: dcy-020, REQ-059/061
• Modules: (예정) application/intents.py·메시지 핸들러/스키마
• Tests: (예정) intent/admission 테스트 재작성

Delivery Trace Delta

• Batches: (예정) dcy-020 admission/intent 배치(외부 계약 cutover)
• Releases: none

Revalidation Impact

• Reverification Needed: no (현 시점)
• Existing Implementation Invalidated: no (코드 불변)
• Status Recommendation: keep-current
• Follow-up Action: dcy-020 admission/intent 배치에서 재정의 + status 전환. 외부 전략 모듈 동시 전환(NFR-4).

Validation Plan

• dcy-020 admission/intent 배치 verification 으로 대체.

CHG-20260610-02

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

Change Summary

• (change-req, dcy-023/issue #22) buy intent payload 계약에서 allocated_capital 즉시 제거 — BuyIntent 데이터클래스 필드·admission 전달(_admit_buy→SlotService)·messaging handler payload 파싱(body.get("allocated_capital")) 삭제. 외부 발신자(trex-orb-v1)가 키를 계속 송신해도 unknown key 로 무시되어 무해(dcy-023 OQ-1 운영자 결정: 즉시 제거, 유예 없음). AC-6 추가, Implemented→Approved(재구현 대기).

Intent

• 사이징·회계 소비자가 없는 운반 전용 필드를 intent 계약에서 제거. dcy-021 명령형 qty 사이징 계약과 정합.

Acceptance Criteria Delta

• Added:
  • AC-6: BuyIntent 에 allocated_capital 부재 + 수신 payload 의 해당 키 무시.
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Modules: trex_core/application/intents.py(BuyIntent/admission), trex_core/application/messaging_handlers.py(payload 파싱)
• Tests: intent admission·handler 파싱 테스트에서 allocated_capital 참조 정리 + 키 포함 payload 무시 테스트

Delivery Trace Delta

• Batches: (예정) dcy-023 batch
• Releases: none

Revalidation Impact

• Reverification Needed: yes (dcy-023 batch 에서 수행)
• Existing Implementation Invalidated: yes (BuyIntent 필드·파싱 제거)
• Status Recommendation: Approved (Implemented→Approved 되돌림)
• Follow-up Action: dcy-023 batch 구현·검증 후 confirm-req-implemented.

Validation Plan

• dcy-023 batch: allocated_capital 포함 payload 가 정상 admit 되며 슬롯·로그에 미반영(무시) + 전체 suite green.

CHG-20260610-IMPL

• Date: 2026-06-10
• Author: Justin Ko
• Type: status
• Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-034(release-candidate) verification — allocated_capital 전 경로 제거(도메인/intent/영속/snapshot/CLI), 마이그레이션 013 테스트 DSN 멱등 round-trip + 컬럼 부재 확인, 전체 428 passed + PG 게이트 21 passed + ruff clean, grep 전수 0건. Blocking Issues 없음.

CHG-20260615-01

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

Change Summary

• (change-req, issue #27) rejected SellIntent 응답에 additive retryable: bool 추가. core 소유 reason→retryable 매핑으로 채우고 reason 유지. #26 sell-idempotency 논의(거부 sticky)의 후속 — 데몬이 reason 문자열 하드코딩 없이 권위 플래그로 retry/stop 판단(손절매 안전 경로 decoupling).

Intent

• 거부 retryability를 core 도메인 지식으로 캡슐화해, 새 reason 추가 시 데몬 분류가 조용히 drift하는 안전 실패 모드 제거(issue #27).

Acceptance Criteria Delta

• Added: AC-7 (rejected sell 응답 additive retryable + core 소유 매핑 + 미인식 기본 true + 완전 additive)
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• Docs: docs/interface-contract.md(rejected sell 응답 retryable 필드)
• Modules: trex_core/application/messaging_handlers.py(intent 응답 빌더 — sell+rejected 시 retryable; core 소유 _SELL_REJECT_RETRYABLE 매핑)
• Tests: tests/application/(retryable 플래그 매핑 케이스 + additive 하위호환)

Delivery Trace Delta

• Batches: BAT-043(편성 예정)
• Releases: none

Revalidation Impact

• Reverification Needed: yes (신규 AC-7만)
• Existing Implementation Invalidated: no (완전 additive — 기존 응답 필드/admit/buy 불변)
• Status Recommendation: revert-to-approved (Implemented → Approved — 신규 additive AC 구현·검증 대기)
• Follow-up Action: BAT-043 batch-lite 구현·검증 후 confirm-req-implemented

Validation Plan

• messaging_handlers 테스트: 각 reject reason → 기대 retryable 매핑, 미인식 reason → true, admitted/processing/buy 응답에 retryable 부재, 기존 reason 필드 유지.

CHG-20260615-IMPL

• Date: 2026-06-15
• Author: Justin Ko
• Type: status
• Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-043(release-candidate) verification — rejected sell 응답 additive retryable(core 소유 _SELL_REJECT_RETRYABLE 매핑 + _sell_reject_retryable helper, 미인식 true/bad_request* false). AC-7 evidence: tests/application/test_sell_retryable_flag.py(매핑 7 reason+미인식+None+bad_request, 응답 inactive/unknown_slot/bad_request→false, admitted/buy 부재). 487 passed, ruff clean. 기존 AC-1~6 불변. Blocking Issues 없음.