trex-core/docs/srs/Integration/req-021_messaging-topology-and-contract-mapping.md

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.

CHG-20260608-01

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

Change Summary

• (change-req, dcy-011) buy intent 메시지 계약에서 symbol 필드 제거, portfolio_id 필수화. buy 핸들러는 payload 에서 symbol 을 읽지 않고 portfolio_id 만 매핑(서버 resolve 는 REQ-007). BAT-015 재구현·재검증 완료 → Implemented 유지.

Intent

• 요청 매핑 원칙(payload 식별자)을 정식 식별자(portfolio_id) 기준으로 정정(issue #6). buy 핸들러 payload 파싱 변경.

Acceptance Criteria Delta

• Updated:
  • buy payload 계약: symbol 제거, portfolio_id 필수.

Impacted Area Delta

• Modules: trex_core/application/messaging_handlers.py(buy 핸들러)
• Docs: docs/interface-contract.md
• Tests: tests/application/test_messaging_intent_consumer.py + tests/adapters/messaging/test_rabbitmq_intent_e2e.py

Delivery Trace Delta

• Batches: BAT-015
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-015 에서 완료)
• Existing Implementation Invalidated: yes (symbol 기반 buy payload)
• Status Recommendation: Implemented (change-req → BAT-015 재검증)
• Follow-up Action: confirm-req-implemented(BAT-015).

Validation Plan

• BAT-015: buy payload portfolio_id 기반 핸들러 단위 + RabbitMQ e2e.

CHG-20260608-02

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

Change Summary

• (change-req, dcy-016/REQ-034 연계) snapshot 요청 payload 에 워치독 억제 플래그 추가: touch_watchdog(기본 true) / actor="operator". make_snapshot_rpc_handler 가 플래그 시 holding 슬롯 last_seen_at 갱신을 건너뛴다. 기본값=현행(전략 폴링=워치독 갱신) 유지(하위호환). BAT-020 재구현·재검증 완료 → Implemented 유지.

Intent

• 운영자 CLI 조회가 전략 생존 신호로 오인되어 safety-sell 을 무력화하는 것 방지(R-4). 메시지 계약에 억제 플래그를 정식화.

Acceptance Criteria Delta

• Added:
  • snapshot 요청 payload touch_watchdog/actor 플래그(기본 미지정=touch). 운영자 조회는 억제.

Impacted Area Delta

• Modules: trex_core/application/messaging_handlers.py(make_snapshot_rpc_handler 억제 분기)
• Docs: docs/interface-contract.md
• Tests: tests/application/test_messaging_snapshot_consumer.py(touch vs suppress)

Delivery Trace Delta

• Batches: BAT-020
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-020 에서 완료)
• Existing Implementation Invalidated: no (기본값 현행 유지, 플래그 추가)
• Status Recommendation: Implemented (change-req → BAT-020 재검증)
• Follow-up Action: confirm-req-implemented(BAT-020).

Validation Plan

• BAT-020: 기본 요청 touch / operator 요청 suppress 단위(caplog/recorder).

CHG-20260608-03

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

Change Summary

• (change-req, dcy-017/REQ-034 연계) snapshot RPC 응답에 watchdog 필드(holding 슬롯 {slot_id, portfolio_id, symbol, expired, last_seen} 배열) 추가(best-effort, 실패 시 생략). 메시지 계약 확장. BAT-021 재구현·재검증 완료 → Implemented 유지.

Intent

• 워치독 소유 상태를 운영자 CLI 가 관측할 수 있도록 스냅샷 응답 계약에 read-only 필드 정식화.

Acceptance Criteria Delta

• Added:
  • snapshot 응답 optional watchdog[] 필드(read-only).

Impacted Area Delta

• Modules: trex_core/application/messaging_handlers.py(_attach_watchdog)
• Docs: docs/interface-contract.md
• Tests: tests/application/test_messaging_snapshot_consumer.py

Delivery Trace Delta

• Batches: BAT-021
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-021 에서 완료)
• Existing Implementation Invalidated: no (additive 필드)
• Status Recommendation: Implemented (change-req → BAT-021 재검증)
• Follow-up Action: confirm-req-implemented(BAT-021).

Validation Plan

• BAT-021: snapshot 응답 watchdog 필드 shape 단위.