# 0. 문서 상태

- 상태: confirmed
- 문서 ID: dcy-009_20260607_multi-instance-rabbitmq-topology
- 이슈명: 인스턴스별 독립 RabbitMQ 채널 토폴로지 — trex-core 다중 인스턴스 운영을 위한 Topic Exchange + Fanout Exchange per-instance 큐 분리
- 작성 시각(KST): 2026-06-07
- 마지막 갱신 시각(KST): 2026-06-07 (draft-req: REQ-048~051 생성)
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-048, REQ-049, REQ-050, REQ-051

# 1. 계획 상태 요약

- 연계 문서 현황:
	- 관련 참조 파일: trex_core/adapters/messaging/topology.py, trex_core/adapters/messaging/rabbitmq.py, trex_core/runtime/daemon.py, trex_core/runtime/config.py, trex_core/application/watchdog.py
	- 관련 TODO/메모: dcy-006(RabbitMQ 도입, confirmed)에서 단일 인스턴스 기준 토폴로지 설계 완료. 다중 인스턴스 시 split-brain 문제와 per-instance 설정 파일 관리는 dcy-006 범위 밖이었음.
- 해석:
	- trex-core는 현재 고정 큐명과 단일 `.env` 기반 설정으로 운영되며, 다중 인스턴스를 동일 RabbitMQ에 연결하면 경쟁 소비로 인해 WatchdogStore split-brain·SafetySellService 중복 발동·이벤트 중복 발행 문제가 발생한다.
	- 이번 Discovery는 인스턴스별 TOML 설정 파일(`instance_key`, `portfolio_hub_token` 포함)을 도입하고, `instance_key` 기반 큐명 suffix화 + `trex.direct`(topic) + `trex.broadcast`(fanout) exchange 도입으로 인스턴스별 독립 채널을 확보하는 것을 목표로 한다.

# 2. 요구사항 판정 결과

- 판정: 신규
- 근거
	- dcy-006(RabbitMQ 도입)은 단일 인스턴스 기준 초기 큐/exchange 설계를 다뤘으며 이미 confirmed + delivered 상태다. 다중 인스턴스 토폴로지와 per-instance TOML 설정 파일은 dcy-006의 연장이 아닌 별도 인프라 변경 주제다.
	- 현재 어떤 Discovery/REQ도 `instance_key`, per-instance TOML 설정 파일, Topic exchange 기반 directed routing, Fanout exchange 기반 broadcast를 다루지 않는다.

# 3. 문제점의 요약

- 현재 상태
	- `trex_core/adapters/messaging/topology.py`: 모든 큐명이 리터럴 상수(`SNAPSHOT_REQ_QUEUE = "trex.snapshot.req"` 등)로 하드코딩. 인스턴스 suffix 없음.
	- `trex_core/adapters/messaging/rabbitmq.py`: `declare_topology()`가 고정 큐명으로 직접 큐를 선언한다. 제어 명령용 directed exchange나 broadcast exchange는 없다.
	- `trex_core/runtime/daemon.py`: "single-writer" 설계 명시. 3개 consumer 스레드(intent/snapshot/pause)가 고정 큐명을 구독. 인스턴스 식별자 개념 없음.
	- `trex_core/runtime/config.py`: `DaemonConfig.from_env()`가 모든 설정을 환경 변수에서 읽는다. `TREX_PORTFOLIO_HUB_TOKEN`을 포함한 민감값이 `.env`에 위치한다. per-instance 설정 파일 로더 없음.
	- `trex_core/application/watchdog.py`: `WatchdogStore._store: dict[str, datetime]` — 프로세스 내 in-memory 저장. 다중 인스턴스 간 공유 불가.
	- 문제: 다중 인스턴스를 동일 큐에 연결하면 RabbitMQ가 round-robin으로 메시지를 분배 → snapshot RPC를 받지 못한 인스턴스의 WatchdogStore가 갱신되지 않아 split-brain 발생 → 해당 인스턴스가 모든 슬롯을 watchdog 만료로 판정해 false safety-sell 발동 위험.
- 기대 상태
	- 각 인스턴스는 자신의 TOML 설정 파일을 가진다. `instance_key`와 `portfolio_hub_token`은 TOML에 기입하며 `.env`에 넣지 않는 것을 원칙으로 한다.
	- `instance_key` 기반 큐명 suffix(`trex.intent.req.{instance_key}`)로 인스턴스별 독립 큐를 선언한다.
	- `trex.direct`(topic exchange) 도입: strategy 모듈이 특정 인스턴스에만 메시지를 전달할 때 routing key `{instance_key}.{channel_type}`으로 publish.
	- `trex.broadcast`(fanout exchange) 도입: 전역 제어 명령(global kill-switch 등)을 모든 인스턴스의 control 큐에 동시 전달.
- 이해관계자
	- 운영자(Justin Ko): 인스턴스별 TOML 설정 파일 관리 및 다중 포트폴리오 분산 운영 담당
	- 전략 모듈 개발자(orb-v1): routing key를 `instance_key` 기준으로 publish하도록 인터페이스 계약 변경 인지 필요
	- trex-core 데몬 운영자: `--config {path}.toml` CLI 인자로 인스턴스별 설정 파일 지정 + 큐 모니터링
- 제약사항
	- pika `BlockingConnection`은 thread-safe하지 않다 — 현재 consumer 스레드별 독립 Connection 패턴은 변경 없이 유지해야 한다.
	- 기존 durable 큐(`trex.intent.req` 등)가 이미 RabbitMQ 서버에 선언되어 있을 수 있다 → 새 큐명으로 전환 후 자연 소멸을 허용하며, RabbitMQ admin console에서 적절한 시점에 수동 삭제한다(OQ-1 Answered).
	- strategy 모듈(orb-v1)이 routing key 변경에 맞게 publish 코드를 업데이트해야 한다 — 인터페이스 계약 정의가 선행되어야 한다.
	- `portfolio_hub_token`과 `instance_key`는 `.env`에 넣지 않는다 — 기존 `config.py`의 `from_env()` 패턴 단독으로는 이 원칙을 지킬 수 없으므로 TOML 로더가 필수다.

## 주요 사용자 시나리오

- orb-v1 전략이 2개의 portfolio를 독립적으로 운영하려는 경우 — 인스턴스A(`instance_key: inst-1`)와 인스턴스B(`instance_key: inst-2`)를 각자의 TOML 파일로 구동해 WatchdogStore/SafetySellService 독립 동작을 보장한다.
- 전체 인스턴스에 global kill-switch를 발동하는 경우 — `trex.broadcast` exchange에 publish하면 모든 인스턴스의 control 큐에 동시 전달되어 인스턴스별 명시 없이 전역 제어가 가능하다.
- 단일 인스턴스 운영을 유지하면서 향후 다중 인스턴스로 전환하는 경우 — TOML 파일에 `instance_key = "default"`로 두고, 추후 인스턴스별 키를 달리해 큐를 분리한다.

# 4. 이번에 정의할 변경

- **per-instance TOML 설정 파일 도입**: 데몬 기동 시 `--config <path>.toml` CLI 인자로 인스턴스별 TOML 파일을 지정한다. 최소 필수 필드: `instance_key`(인스턴스 식별자), `portfolio_hub_token`(portfolio-hub 인증 토큰). 이 두 값은 `.env`에 넣지 않는 것을 원칙으로 한다. `config.py`에 `DaemonInstanceConfig.from_toml(path)` 로더를 추가하고, 기존 `DaemonConfig.from_env()`와 병합해 최종 설정을 구성한다.
- **큐명 동적화 및 `instance_key` 기반 suffix**: `topology.py`의 고정 큐명 상수를 `{base_name}.{instance_key}` 형식의 동적 함수로 교체한다. `daemon.py`가 TOML에서 읽은 `instance_key`를 `declare_topology(instance_key)`에 전달한다.
- **`trex.direct`(topic exchange) 도입 + per-instance 큐 바인딩**: `trex.direct` exchange(type: topic, durable)를 신설하고, 각 인스턴스의 intent/control/snapshot 큐를 routing key `{instance_key}.intent`, `{instance_key}.control`, `{instance_key}.snapshot`으로 바인딩한다.
- **`trex.broadcast`(fanout exchange) 도입 + control 큐 dual binding**: `trex.broadcast` exchange(type: fanout, durable)를 신설하고, 각 인스턴스의 control 큐를 이 exchange에 추가 바인딩한다. global kill-switch 등 전체 인스턴스 대상 제어 명령은 이 exchange에 publish한다.
- **baseline 문서 갱신**: `docs/runtime-flows.md`와 `docs/project-structure.md`에 multi-instance topology 구조와 TOML 기반 기동 흐름을 반영한다.

## 영향 범위

- 코드 영향:
	- `trex_core/runtime/config.py`: `DaemonInstanceConfig` dataclass 추가(`instance_key`, `portfolio_hub_token`). `from_toml(path)` 로더 추가. 기존 `DaemonConfig.from_env()`는 유지하되, TOML 로더와 병합하는 `from_config(toml_path)` 팩토리 추가.
	- `trex_core/adapters/messaging/topology.py`: 고정 큐명 상수 → 동적 함수(`intent_queue(instance_key)` 등). `DIRECT_EXCHANGE`, `BROADCAST_EXCHANGE` 상수 추가.
	- `trex_core/adapters/messaging/rabbitmq.py`: `declare_topology(instance_key)` signature 변경. topic/fanout exchange 선언 + per-instance 큐 바인딩 로직 추가.
	- `trex_core/runtime/daemon.py`: `--config` CLI 인자 파싱. TOML에서 `instance_key` 읽기. 큐 선언/구독 시 `instance_key` 전달.
	- 진입점(`trex_core/__main__.py` 또는 동등): `--config <path>` CLI 인자 추가.
- 문서 영향:
	- `docs/runtime-flows.md`: multi-instance topology 흐름 추가(directed vs broadcast 분기), TOML 기반 기동 절차 반영
	- `docs/project-structure.md`: topology.py 역할 변경(동적 큐명 빌더), 설정 파일 계층 반영
	- `docs/interface-contract.md`: routing key 계약 갱신 — `{instance_key}.{channel_type}` 규칙 추가
- 운영 영향:
	- 인스턴스별 TOML 파일 생성 및 관리 필요(`instance_key`, `portfolio_hub_token` 포함)
	- 기존 `trex.intent.req` 등 old 큐는 새 큐 전환 후 자연 소멸을 허용한다. RabbitMQ admin console에서 적절한 시점에 수동 삭제(OQ-1 Answered).
	- `TREX_PORTFOLIO_HUB_TOKEN` env var는 TOML로 이관 후 `.env`에서 제거 필요

# 5. 요구사항 목록

## 기능 요구사항

- FR-1: 데몬 기동 시 `--config <path>.toml` CLI 인자는 필수다. 인자 없이 기동하면 오류 메시지를 출력하고 즉시 종료한다. TOML 파일에서 최소 `instance_key`와 `portfolio_hub_token`을 읽는다. 이 두 값은 `.env`에서 읽지 않는다.
- FR-2: `instance_key` 값을 기반으로 모든 수신 큐명을 `{base}.{instance_key}` 형식으로 suffix화한다.
- FR-3: `trex.direct`(type: topic, durable) exchange를 선언하고, 각 인스턴스의 intent/control/snapshot 큐를 routing key `{instance_key}.intent`, `{instance_key}.control`, `{instance_key}.snapshot`으로 바인딩한다.
- FR-4: `trex.broadcast`(type: fanout, durable) exchange를 선언하고, 각 인스턴스의 control 큐를 이 exchange에 추가 바인딩(dual binding)한다. 전체 인스턴스 대상 제어 명령은 이 exchange에 publish한다.
- FR-5: `instance_key = "default"` 단일 인스턴스 운영 시 기존 intent/snapshot/control RPC 경로와 동작이 동일하게 유지된다(하위 호환 검증 기준: 기존 테스트 스위트 회귀 없음).
- FR-6: `docs/runtime-flows.md`와 `docs/project-structure.md`를 multi-instance topology 및 TOML 기반 기동 기준으로 갱신한다.

## 비기능 요구사항

- NFR-1: `instance_key = "default"` TOML로 배포된 환경에서 토폴로지 변경 후 재시작 시 동작 회귀가 없어야 한다(pytest 전체 통과 기준).
- NFR-2: 기존 pika `BlockingConnection` per-thread 패턴을 유지한다. exchange 바인딩 추가로 인해 추가 스레드 또는 커넥션을 생성하지 않는다.
- NFR-3: 인스턴스별 독립 큐 사용 시 WatchdogStore, SafetySellService가 자신의 인스턴스 슬롯만 처리하므로 split-brain이 발생하지 않는다(다중 인스턴스 e2e 시나리오 통과).
- NFR-4: `portfolio_hub_token`과 `instance_key`가 코드/env/로그에 평문으로 노출되지 않는다. TOML 파일은 git에 커밋하지 않는다(`.gitignore` 추가).

## 범위 경계

- In Scope
	- per-instance TOML 설정 파일 로더(`instance_key`, `portfolio_hub_token`)
	- `instance_key` 기반 큐명 suffix화
	- `trex.direct`(topic exchange) 신설 + per-instance 큐 바인딩
	- `trex.broadcast`(fanout exchange) 신설 + control 큐 dual binding
	- daemon.py/topology.py/rabbitmq.py/config.py/진입점 변경
	- 인터페이스 계약(`docs/interface-contract.md`) routing key 규칙 추가
	- `docs/runtime-flows.md`, `docs/project-structure.md` 갱신
	- `.gitignore`에 `*.toml` 또는 `config/*.toml` 추가(인스턴스 설정 파일 git 제외)
- Out of Scope
	- 전체 설정을 TOML로 일원화(KIS 자격증명 등 나머지 env var의 TOML 이관 — 별도 논의)
	- strategy 모듈(orb-v1) 코드 변경 — 인터페이스 계약만 정의, 구현은 strategy 모듈 범위
	- WatchdogStore Redis 외부화 — competing consumer 방식(별도 Discovery)
	- active-passive failover / leader election
	- 기존 old 큐 자동 삭제 스크립트 — 운영 절차로 처리
	- 인스턴스↔portfolio 매핑 레지스트리 (trex-core 내부 DB 불필요)

# 6. 리스크/가정 목록

## 리스크

- R-1 (Medium): strategy 모듈이 routing key를 변경하지 않으면 다중 인스턴스 환경에서 메시지가 올바른 인스턴스에 도달하지 않는다.
	- 완화 방안: 인터페이스 계약에 routing key 규칙을 명시한다. `instance_key = "default"` 단일 인스턴스 시에는 routing key `default.intent` 등으로 publish하면 하위 호환 유지 가능.
- R-2 (Medium): 기존 durable 큐(`trex.intent.req` 등)가 RabbitMQ에 잔류하면 새 큐로 전환 후 old 큐에 consumer가 없어진다.
	- 완화 방안: 자연 소멸 허용. 배포 후 old 큐에 새로 publish되는 메시지가 없으므로 메시지 누적 없음. 적절한 시점에 RabbitMQ admin console에서 수동 삭제(OQ-1 Answered).
- R-3 (Low): `trex.broadcast` exchange 메시지가 모든 인스턴스에 동시 전달되므로 인스턴스별로 동일 제어 명령을 중복 처리한다.
	- 완화 방안: kill-switch/pause 핸들러에 idempotency 보장(REQ-036 패턴, DB advisory lock). 중복 처리는 무해하게 동작.
- R-4 (Low): TOML 설정 파일이 실수로 git에 커밋되면 `portfolio_hub_token` 등 민감값이 노출된다.
	- 완화 방안: `.gitignore`에 인스턴스 TOML 경로 추가(FR-1 범위). TOML 파일은 배포 전용 경로에 위치시킨다.

## 가정

- A-1: 현재 배포 환경은 단일 인스턴스 운영이다. 다중 인스턴스 전환은 향후 필요 시점에 진행한다.
- A-2: strategy 모듈(orb-v1)은 인터페이스 계약 변경에 맞춰 routing key를 업데이트할 수 있다.
- A-3: 인스턴스별 담당 portfolio 매핑은 TOML 설정 또는 strategy 모듈의 routing 설정으로 관리한다. trex-core 내부에 레지스트리 DB를 두지 않는다.
- A-4: `portfolio_hub_token`과 `instance_key`를 `.env`에서 TOML로 이관하면 기존 `.env` 기반 배포 스크립트를 수정해야 한다. KIS 자격증명 등 나머지 env var는 이번 범위에서 이관하지 않는다.
- A-5: TOML 파일 경로는 `--config` CLI 인자로 지정한다. `--config` 인자는 필수이며, 지정하지 않으면 데몬이 오류 메시지를 출력하고 즉시 종료한다(OQ-2 Answered). 기본값 fallback은 제공하지 않는다.

## 오픈 질문

- OQ-1: 기존 durable 큐(`trex.intent.req` 등) 처리 방식 — 자연 소멸(수동 삭제) vs 배포 절차에 명시적 삭제 포함?
	- 상태: Answered
	- 결정: 자연 소멸 허용. 배포 후 old 큐에 새로 publish되는 메시지는 없으므로 메시지 누적 없음. RabbitMQ admin console에서 적절한 시점에 수동 삭제. 배포 절차에 명시적 삭제 단계를 추가하지 않는다.
	- 반영 위치: R-2 완화 방안
- OQ-2: `--config` 인자 없이 데몬 기동 시 동작 — 오류 종료(필수) vs `instance_key = "default"` 기본값으로 기동?
	- 상태: Answered
	- 결정: `--config` 필수. 인자 없이 기동 시 오류 메시지 출력 후 즉시 종료. 기본값 fallback 없음. 인스턴스 식별이 보장되지 않은 상태로 기동하는 것은 다중 인스턴스 환경에서 split-brain 위험을 내포하므로 명시적 실패가 안전하다.
	- 반영 위치: A-5, FR-1

### 오픈 질문 처리 기준

- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.

# 7. 초기 성공 기준

- S-1: `--config inst-1.toml`(`instance_key = "inst-1"`)으로 인스턴스 기동 시 `trex.intent.req.inst-1`, `trex.snapshot.req.inst-1`, `trex.control.req.inst-1` 큐가 RabbitMQ에 선언되고, `trex.direct` exchange에 올바른 routing key로 바인딩된다.
- S-2: `instance_key = "inst-1"`과 `instance_key = "inst-2"` 인스턴스를 동시 기동했을 때, `inst-1` routing key로 publish된 메시지가 `trex.intent.req.inst-1` 큐에만 전달된다.
- S-3: `trex.broadcast` exchange에 publish된 제어 메시지가 `trex.control.req.inst-1`과 `trex.control.req.inst-2` 큐 모두에 전달된다.
- S-4: `instance_key = "default"` TOML로 기동 시 기존 pytest 스위트(단위 + 회귀) 전체 통과 — 동작 회귀 없음.
- S-5: `portfolio_hub_token`이 `.env`에 없고 TOML에서만 읽혀 `PortfolioHubConfig.token`에 올바르게 주입된다.

## 측정 방식 및 데이터 출처

- S-1 측정 방식: RabbitMQ Management API(`GET /api/queues`, `GET /api/bindings`) 또는 pika 큐 선언 성공 로그 / 데이터 출처: 통합 테스트 또는 manual e2e
- S-2 측정 방식: 두 인스턴스 기동 후 `inst-1` routing key로 intent publish → `trex.intent.req.inst-1` 메시지 카운트 +1, `trex.intent.req.inst-2` 카운트 0 확인 / 데이터 출처: RabbitMQ Management API 또는 통합 테스트
- S-3 측정 방식: broadcast exchange에 publish → 두 인스턴스 control 큐 모두 메시지 카운트 +1 / 데이터 출처: 통합 테스트 또는 manual e2e
- S-4 측정 방식: `pytest` 전체 실행 → 0 failures / 데이터 출처: pytest 출력
- S-5 측정 방식: `.env`에 `TREX_PORTFOLIO_HUB_TOKEN` 미설정 상태에서 TOML로 기동 → `PortfolioHubConfig.token` 값 확인 / 데이터 출처: 단위 테스트(config loader)

# 8. REQ로 넘기기 전 확인 체크

- [x] 범위(In Scope/Out of Scope) 확정
	- 기준: OQ-1(old 큐 처리) Answered, OQ-2(TOML 필수) Answered
- [x] 성공 지표의 측정 방식/데이터 출처 확정
	- 기준: S-1~S-5 각각 테스트 또는 e2e 근거 확정 — S-1~S-5 측정 방식 및 데이터 출처 섹션 7에 전부 기입됨
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
	- 기준: R-1~R-4 전부 Medium/Low — High 영향 리스크 없음. 모든 리스크에 완화 방안 기입됨. REQ 단계 인계 확정.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
	- 기준: OQ-1, OQ-2 모두 Answered
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
	- 기준: Justin Ko 확인 — Section 11 Confirmed By: Justin Ko

# 9. 파일 처리 결과

- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-009_20260607_multi-instance-rabbitmq-topology.md
- 참조 문서:
	- trex_core/adapters/messaging/topology.py (고정 큐명 상수 현황 — 변경 대상)
	- trex_core/adapters/messaging/rabbitmq.py (declare_topology 현황 — 변경 대상)
	- trex_core/runtime/daemon.py (consumer thread 현황 — instance_key 추가 대상)
	- trex_core/runtime/config.py (DaemonConfig.from_env() — TOML 로더 추가 대상)
	- docs/discovery/dcy-006_20260605_strategy-module-rabbitmq-transport.md (원래 RabbitMQ 도입 Discovery — 참조 기준)
	- docs/runtime-flows.md (baseline 문서 — 갱신 대상, FR-6)
	- docs/project-structure.md (baseline 문서 — 갱신 대상, FR-6)

# 10. 사용자 결정 필요 항목 요약

## CONFIRM

- CONFIRM_STRATEGY_MODULE_OUT_OF_SCOPE: 확인됨. strategy 모듈(orb-v1)의 routing key 구현 변경은 이번 Discovery 범위 밖. trex-core는 exchange·바인딩 계약만 정의하며, strategy 모듈의 publish 코드 변경은 별도 Discovery 또는 REQ에서 다룬다(Section 5 Out of Scope 반영).
- CONFIRM_ENV_RESIDUAL: 확인됨. KIS 자격증명(`TREX_KIS_*`), PostgreSQL DSN, TREX_RABBITMQ_URL 등 기존 env var는 이번 범위에서 `.env` 유지. TOML 이관 대상은 `portfolio_hub_token`과 `instance_key`만(Section 5 Out of Scope + A-4 반영).

## DATA

- DATA_TOML_SCHEMA_FULL: REQ 단계 확정. 최소 필드: `instance_key` (string), `portfolio_hub_token` (string). 추가 필드는 REQ 단계 스키마 정의에서 확정한다.
- DATA_MULTI_INSTANCE_TRIGGER_TIMING: REQ/배포 단계 계측 항목. Discovery 단계 범위 밖. 실제 다중 인스턴스 운영 계획은 배포 시점 REQ에서 반영한다.

# 11. Discovery Freeze

## 섹션 참조

- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)

## Freeze 플래그

- Handoff Decision: REQ Drafting 진행 가능
- Handoff Rationale: TOML 설정 파일 도입 + instance_key 기반 토폴로지 설계 완료. OQ-1(old 큐 자연 소멸), OQ-2(TOML 필수) 모두 Answered. CONFIRM/DATA 항목은 REQ 단계에서 확정 가능 — confirm-discovery 후 REQ 초안 작성 진행 가능.
- Ready for REQ Drafting: true
- Confirmed By: Justin Ko
- Confirmed At (KST): 2026-06-07