# req-021: messaging 토폴로지 + 메시지 계약 매핑

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

## Intent
- trex-core ↔ 전략 모듈 통신을 RabbitMQ(AMQP) 메시지 기반으로 정의해, 스냅샷·intent admission 은 request-reply 로, 체결/슬롯 상태는 이벤트(pub/sub)로 전달한다. 기존 logical 계약(스냅샷 필드/마스킹/view 모드/strategy_id 필터, intent 스키마)은 transport-무관하게 보존하고 메시지 payload/속성/routing key 로 의미 손실 없이 매핑한다.

## Requirement
- 통신 토폴로지를 아래 3 패턴으로 확정한다(dcy-006 OQ-2).
  1. 스냅샷 RPC(request-reply): 요청 queue `trex.snapshot.req`(direct/default exchange), 응답은 RabbitMQ direct reply-to(`amq.rabbitmq.reply-to`) + `correlation_id`. 요청 payload 에 `strategy_id` 와 `view` 모드(dcy-005 OQ-11/FR-8).
  2. intent admission RPC(request-reply): 요청 queue `trex.intent.req`, 응답 = admission 결과(`status`, `slot_id`, `reason`). `correlation_id` = intent 멱등키(dcy-003 패턴) 로 RPC 상관과 dedup 일원화. 체결/종료(fill/close) 결과는 응답이 아니라 이벤트(③)로 전달해 admission 동기 + fill 비동기 2단계 시맨틱을 보존한다.
  3. 이벤트 pub/sub: trex-core 가 체결·슬롯 상태 변화를 topic exchange `trex.events` 에 발행한다. routing key 는 `{event_type}.{strategy_id}.{symbol}` 형식이며, 전략 queue 는 `*.{strategy_id}.#` 패턴으로 바인딩해 자기 자산 이벤트만 수신한다(broker 단 필터).
- 매핑 원칙을 다음과 같이 고정한다: 요청 메시지(①·②) 의 `view` 모드와 `strategy_id` 는 message **payload** 에, 이벤트(③) 의 `strategy_id`·`symbol` 은 **routing key** 에 싣는다.
- 위 토폴로지/매핑은 transport-무관 logical 계약(스냅샷 필드/마스킹/view 모드/strategy_id, intent 스키마)을 변경하지 않는다.

## Acceptance Criteria
1. Given trex-core daemon, When 기동, Then 스냅샷 RPC 요청 큐(`trex.snapshot.req`), intent RPC 요청 큐(`trex.intent.req`), 이벤트 토픽 익스체인지(`trex.events`)가 선언되어 있다.
2. Given stub/실 어댑터로 발행한 스냅샷 RPC 요청, When trex-core 가 응답, Then 응답 메시지가 HTTP 응답과 동일한 logical 필드(필드/마스킹/view 모드 적용)를 운반하고 `correlation_id` 가 요청과 일치한다.
3. Given intent admission RPC 요청 메시지, When trex-core 가 처리, Then 슬롯 전이 후 admission 응답(`status, slot_id?, reason?`)이 reply-to 큐로 반환되고 체결/종료는 응답이 아니라 후속 이벤트로 발행된다.
4. Given 동일 종목·이벤트가 전략 A 와 전략 B 의 queue 에 각각 `*.A.#`/`*.B.#` 패턴으로 바인딩된 상태, When trex-core 가 strategy_id=A 의 이벤트를 발행, Then A 의 queue 만 수신하고 B 의 queue 는 수신하지 않는다.
5. Given 요청 메시지, When 페이로드를 검사, Then `view`/`strategy_id` 가 payload 에 있고 routing key 에 들어가 있지 않다(요청 매핑 원칙).

## Impacted Area
- Docs: docs/interface-contract.md(메시지 계약), docs/runtime-flows.md(RPC/이벤트 흐름) — REQ-026 에서 정합.
- Modules: 신규 `trex_core/adapters/messaging/` 토폴로지 선언(exchange/queue/binding) 및 routing key 생성 로직.
- Tests: stub 어댑터로 RPC 요청-응답 매핑, 이벤트 routing key 바인딩 필터링, 요청/이벤트 매핑 원칙 검사.

## Notes
- 출처: dcy-006 FR-1, FR-2, OQ-2.
- 토폴로지 선언과 어댑터 구현 분리: 본 REQ 는 "무엇을/어떻게 매핑하나" 계약을 다루고, RabbitMQ 어댑터 + 런타임 통합 자체는 REQ-022 에서 다룬다.
- logical 계약(스냅샷 필드/마스킹/view 모드/strategy_id, intent 스키마)은 dcy-005/002/003 소관이며 본 REQ 가 변경하지 않는다.
- dcy-005 의 스냅샷 read 계약이 아직 REQ 로 정규화되지 않았으면 본 REQ 의 AC-2 검증은 stub 응답 셰이프 수준에서 시작하고, 정식 계약 확정 후 evidence 를 보강한다.

## Change Log

### CHG-20260605-01
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- dcy-006 FR-1/FR-2 로부터 최초 생성(Proposed). 통신 토폴로지(스냅샷 RPC + intent RPC + 이벤트 topic) 와 요청/이벤트 매핑 원칙(view·strategy_id payload, event routing key)을 backlog 로 정규화.

#### Intent
- transport 추상화의 메시지 계약과 토폴로지 결정을 별도 REQ 로 분리해 어댑터 구현(REQ-022) 및 신뢰성(REQ-023)과 독립 진척.

#### Acceptance Criteria Delta
- Added:
  - 토폴로지 선언 4종, RPC 응답 매핑 1종, 이벤트 routing key 필터링 1종, 매핑 원칙 검사 1종 (총 5개 기준)
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta
- Docs:
  - docs/interface-contract.md, docs/runtime-flows.md
- Modules:
  - adapters/messaging 토폴로지 선언
- Tests:
  - RPC 요청-응답, 이벤트 routing key 필터링, 매핑 원칙 검사

#### 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
- stub 어댑터 통합테스트로 RPC 매핑·이벤트 routing key 필터링·매핑 원칙을 검증.

### CHG-20260605-02
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- Status 변경: Proposed -> Approved. confirm-req 승인 게이트 통과.

#### Intent
- messaging 토폴로지 + 메시지 계약 매핑을 delivery input 으로 승인.

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

#### Impacted Area Delta
- Docs/Modules/Tests: 없음

#### Delivery Trace Delta
- Batches:
  - none
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Approved
- Follow-up Action: REQ-022/023/025 와 함께 batch 편성(통신 단절 R-5 회피)

#### Validation Plan
- 기존 Acceptance Criteria 로 batch delivery 에서 검증.

### CHG-20260605-03
- Date: 2026-06-05
- Author: Justin Ko

#### Change Summary
- Status 변경: Approved -> Implemented. BAT-007 release-candidate verification evidence 기반.

#### Intent
- messaging 토폴로지 + 메시지 계약 매핑 구현과 검증 evidence 확보 후 구현 완료 상태로 동기화.

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

#### Impacted Area Delta
- Docs/Modules/Tests: 없음

#### Delivery Trace Delta
- Batches:
  - BAT-007 (release-candidate)
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Implemented
- Follow-up Action: release 단계는 별도 진행

#### Validation Plan
- AC-1: tests/adapters/messaging/test_rabbitmq_transport.py::test_declare_topology_creates_core_entities.
- AC-2: tests/application/test_messaging_snapshot_consumer.py + tests/adapters/messaging/test_rabbitmq_transport.py::test_rpc_roundtrip.
- AC-3: tests/application/test_messaging_intent_consumer.py + test_messaging_event_publisher.py 조합.
- AC-4: tests/application/test_messaging_event_publisher.py::test_event_for_strategy_a_does_not_reach_strategy_b_queue + tests/adapters/messaging/test_rabbitmq_transport.py::test_event_publish_and_per_strategy_consume.
- AC-5: tests/adapters/messaging/test_topology.py.