trex-core/docs/srs/Configuration/req-010_daemon-dotenv-loading.md

req-010: 데몬 설정 .env 파일 로딩

• Status: Implemented
• Type: Configuration
• Priority: Medium
• Owner: project maintainers

Intent

• 운영자가 데몬 환경변수(TREX_POSTGRESQL_DSN 등)를 .env 파일로 관리할 수 있도록, 데몬 기동 시 .env 를 로드한다. 실제 OS 환경변수는 .env 보다 우선한다(12-factor 호환).

Requirement

• DaemonConfig.from_env() 가 os.environ 을 읽기 전에 .env(있으면)를 로드한다. python-dotenv 를 의존성에 추가하고, .env 는 .gitignore 에 등록해 커밋되지 않게 하며, .env.example 를 참고용으로 제공한다. .env 가 없거나 dotenv 미설치여도 기존 동작(os.environ 단독)을 유지한다(회귀 없음).
• (CHG-20260609-01, trex-orb-v1 정합) .env 해석은 config 디렉터리 기준 결정적이다 — --env-file <path> 우선, 없으면 <config_dir>/.env(TOML 옆). CWD 의존 상향 탐색(find_dotenv(usecwd=True))을 사용하지 않는다. .env 는 config/.env 로 공용화하고 config/.env.example 를 제공하며, .gitignore 는 config/* 를 무시하되 *.example.toml/.env.example 만 추적한다. override=False(실제 OS env 우선)는 유지한다.

Acceptance Criteria

1. (CHG-20260609-01 갱신) Given <config_dir>/.env(또는 --env-file)에 TREX_POSTGRESQL_DSN=... 가 있고 해당 OS env 가 미설정, When 설정 로드, Then .env 값이 로드되어 dsn 에 반영된다.
2. Given OS env 와 .env 에 같은 키가 다른 값으로 존재, When 로드, Then OS env 값이 우선한다(.env 가 덮어쓰지 않음, override=False).
3. Given .env 가 없음, When 로드, Then 기존처럼 os.environ 만으로 동작한다(회귀 없음).
4. Given 저장소, When .gitignore 확인, Then config/* 가 무시 대상이며 config/*.example.toml·config/.env.example 은 추적된다.
5. Given broker=paper 이고 .env/OS env 에 TREX_PAPER_FILL_AFTER_POLLS/TREX_PAPER_QTY_PER_POLL/TREX_PAPER_REJECT_SYMBOLS 가 설정, When DaemonConfig.from_env() 후 _build_broker, Then paper 더블이 해당 시나리오(지연/부분/거부, REQ-011 AC-2)로 구성된다. 미설정이면 PaperBroker() 기본과 동일(회귀 없음).
6. (CHG-20260609-01) Given CWD 를 바꿔 실행, When 설정 로드, Then <config_dir>/.env 가 CWD 와 무관하게 결정적으로 로드된다(상향 탐색 없음).
7. (CHG-20260609-01) Given --env-file <path>, When 로드, Then <config_dir>/.env 대신 그 파일이 로드된다(우선).

Impacted Area

• Docs: (CHG-20260609-01) config/.env.example(신규, 공유 인프라 키), .env→config/.env 이동
• Modules: pyproject.toml(python-dotenv), trex_core/runtime/config.py(load_dotenv→_load_dotenv(config_path, env_file) config-dir 해석, PaperBrokerConfig), trex_core/runtime/daemon.py(_build_broker paper 주입, --env-file), cli.py(--env-file), .gitignore(config/* 허용목록), .env.example(paper 튜닝 키)
• Tests: tests/runtime/test_config_dotenv.py (로드/우선순위/부재 회귀, paper 튜닝 기본/파싱, config-dir·--env-file·CWD 무관)

Notes

• minor-change fast path: 단일 저위험 Configuration REQ, 구조/인터페이스/런타임 흐름 영향 없음(기동 시 env 소스 추가뿐). batch-lite 로 처리, design 불요.
• dotenv 로드는 best-effort(미설치 시 graceful no-op) — 도메인/테스트 경로에 영향 없음.
• 맥락: dcy-002 데몬(REQ-005)의 설정 편의 개선. trex-orbit 도 .env 사용.

Change Log

CHG-20260604-01

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

Change Summary

• 최초 생성(Proposed) — 데몬 .env 로딩 Configuration 요구사항.

Intent

• 환경변수의 파일 기반 관리(.env) 지원을 backlog 로 정규화.

Acceptance Criteria Delta

• Added:
  • .env 로드, OS env 우선, 부재 회귀, gitignore 4개 기준
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • 없음
• Modules:
  • pyproject.toml, runtime/config.py, .gitignore, .env.example
• Tests:
  • tests/runtime/test_config_dotenv.py

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: minor-change batch-lite 편성

Validation Plan

• 설정 로드/우선순위/부재 회귀 단위테스트로 검증.

CHG-20260604-02

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

Change Summary

• Status Proposed → Approved (minor-change 저위험 단일 REQ, 구조/인터페이스/런타임 흐름 영향 없음).

Intent

• 승인 게이트 충족(필수 필드·구체 AC·blocker 없음). batch-lite 로 즉시 delivery 가능.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register Approved)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • none (batch-lite 편성 예정)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: draft-batch 로 batch-lite 생성

Validation Plan

• batch-lite verification 에서 AC 검증.

CHG-20260604-03

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

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-003 release-candidate).

Intent

• BAT-003 verification.md 의 AC↔evidence(로드/우선순위/부재 회귀/gitignore, 78 pass)로 모든 AC 충족 → 구현 완료.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register Implemented)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • BAT-003 (release-candidate)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: draft-release 로 release 편성(BAT-001~003)

Validation Plan

• BAT-003 verification evidence 재참조로 충분.

CHG-20260606-01

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

Change Summary

• paper broker 튜닝 knob(REQ-011 AC-2 의 지연/부분/거부 시나리오)을 데몬 env 로 노출하는 신규 scope 추가. DaemonConfig.from_env() 가 TREX_PAPER_FILL_AFTER_POLLS/TREX_PAPER_QTY_PER_POLL/TREX_PAPER_REJECT_SYMBOLS 를 PaperBrokerConfig 로 파싱하고 _build_broker 가 paper 더블에 주입한다. 미설정이면 기존 PaperBroker()(즉시 전량 체결·거부 없음)와 byte-for-byte 동일(회귀 없음).

Intent

• e2e 시나리오(주문 거부 롤백/지연 체결/부분 체결)를 데몬 재기동만으로 재현할 수 있도록 REQ-011 의 결정적 더블 knob 을 운영 설정 표면(REQ-010 .env 로딩)에 연결. REQ-011 본문은 이미 시나리오를 요구(AC-2)하므로 broker 요구사항 변경이 아니라 Configuration 노출.

Acceptance Criteria Delta

• Added:
  • AC-5: paper 튜닝 env 파싱 + _build_broker 주입, 미설정 시 기본 동작 byte-for-byte 동일(회귀 없음)
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register 상태·Recent Change Log Summary)
• Modules:
  • trex_core/runtime/config.py (PaperBrokerConfig dataclass + from_env 파싱), trex_core/runtime/daemon.py (_build_broker 주입), .env.example (paper 튜닝 키 3개 문서화)
• Tests:
  • tests/runtime/test_config_dotenv.py (test_paper_broker_defaults, test_paper_broker_env_tuning)

Delivery Trace Delta

• Batches:
  • BAT-009 (batch-lite, tooling — 신설 예정; AC-5 delivery/verification 담당)
• Releases:
  • REL-001 영향 없음: REL-001 이 포함한 REQ-010 coverage 는 AC-1~4(.env 로딩 메커니즘, BAT-003)로 그대로 유효. AC-5 는 REL-001 이후 신규 scope 이며 별도 release 로 배포.

Revalidation Impact

• Reverification Needed: yes (신규 AC-5 한정; 기존 AC-1~4 evidence(BAT-003)는 무효화되지 않음)
• Existing Implementation Invalidated: no
• Status Recommendation: Implemented → Approved (신규 AC-5 는 BAT-009 verification 전까지 미확정)
• Follow-up Action: draft-batch 로 BAT-009(batch-lite, tooling) 생성 → verification → confirm-req-implemented 로 Approved → Implemented 재전환

Validation Plan

• 단위: test_paper_broker_defaults(미설정=기본), test_paper_broker_env_tuning(3 env 파싱) — 이미 작성·통과(166 pass).
• e2e: 데몬 env 재기동으로 거부 롤백(idle→pending_buy→idle), 지연 체결(+3.7s), 부분 체결(qty 누적 +2.5s) 재현 — BAT-009 verification 에 evidence 기록.

CHG-20260606-02

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

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-009 release-candidate).

Intent

• BAT-009 verification.md 의 AC↔evidence(AC-1~4 BAT-003 회귀 재확인 + AC-5 단위 2개·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-009 (release-candidate)
• Releases:
  • none (REL-001 과 분리된 후속 release 로 배포 예정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current (Implemented)
• Follow-up Action: draft-release 로 BAT-009 배포 편성(원하는 시점에).

Validation Plan

• BAT-009 verification evidence 재참조로 충분.

CHG-20260609-01

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

Change Summary

• (change-req, trex-orb-v1 설정 관리 정합) .env 해석을 config 디렉터리 기준 결정적으로 변경한다 — --env-file <path> 가 우선, 없으면 <config_dir>/.env(TOML 옆). 기존 find_dotenv(usecwd=True)(CWD 의존 상향 탐색)를 제거해 실행 위치와 무관하게 동일 .env 를 로드한다. .env 를 repo 루트 → config/.env 로 이동(공용화), config/.env.example 신설, .gitignore 를 config/* 무시 + *.example.toml/.env.example 만 추적하는 형태로 전환. override=False(실제 OS env 우선)는 유지. config_dir 는 REQ-048 CHG-20260609-01 의 --config-path 로 제공된다.

Intent

• 어디서 실행하든 동일한 공유 인프라 .env(DSN/RabbitMQ/KIS/portfolio-hub 등)를 결정적으로 로드한다. 다중 인스턴스가 같은 broker/DSN/hub 를 공유하도록 .env 를 인스턴스 TOML 과 분리해 config 디렉터리에 공용화(12-factor).

Acceptance Criteria Delta

• Added:
  • AC-6: .env 는 <config_dir>/.env(TOML 옆)에서 CWD 와 무관하게 결정적으로 로드된다. dotenv 미설치/.env 부재 시 no-op(회귀 없음).
  • AC-7: --env-file <path> 가 주어지면 <config_dir>/.env 대신 그 파일을 로드한다(우선).
  • AC-8: .gitignore 는 config/* 를 무시하되 config/*.example.toml 과 config/.env.example 은 추적한다(실제 .env/인스턴스 TOML 비커밋).
• Updated:
  • AC-1: "CWD 의 .env" → "<config_dir>/.env"(또는 --env-file) 로 로드 소스 변경.
• Removed: none

Impacted Area Delta

• Modules: trex_core/runtime/config.py(_load_dotenv(config_path, env_file) — config-dir 결정적 해석, find_dotenv(usecwd=True) 제거), trex_core/runtime/daemon.py·cli.py(--env-file 인자 전달)
• Docs: config/.env.example(신규, 공유 인프라 키), .gitignore(config/* 허용목록), .env(루트→config/.env 이동)
• Tests: tests/runtime/test_config_dotenv.py(config-dir 로드/--env-file 우선/CWD 무관/override=False 회귀/부재 no-op)

Delivery Trace Delta

• Batches: 신규 batch-lite(REQ-048 CHG-20260609-01 과 동일 배치)
• Releases: none

Revalidation Impact

• Reverification Needed: yes (신규 batch 에서 AC-6/7/8 + AC-1 변경 검증)
• Existing Implementation Invalidated: yes (.env 해석 위치가 CWD → config-dir 로 변경되어 기존 루트 .env 의존 동작이 바뀜 — 운영 배포 시 .env 이동 필요)
• Status Recommendation: Implemented → Approved (신규/변경 AC 미구현 — batch 재검증 후 Implemented 복귀)
• Follow-up Action: draft-batch(batch-lite) → run-batch-implementation → verification → confirm-req-implemented

Validation Plan

• 신규 BAT: <config_dir>/.env 결정적 로드(CWD 변경해도 동일), --env-file 우선, OS env 우선(override=False) 회귀, .env 부재 no-op 단위. .gitignore config/* 허용목록 가드.

CHG-20260609-02

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

Change Summary

• Status 변경: Approved → Implemented. BAT-026 release-candidate verification evidence 기반(CHG-20260609-01 AC-1/2/3/4/6/7).

Acceptance Criteria Delta

• Added/Updated/Removed: 없음

Impacted Area Delta

• Docs/Modules/Tests: 없음

Delivery Trace Delta

• Batches: BAT-026 (release-candidate)
• Releases: none

Revalidation Impact

• Reverification Needed: no (BAT-026 에서 완료)
• Existing Implementation Invalidated: no
• Status Recommendation: Implemented
• Follow-up Action: 운영 배포 시 .env→config/.env 이동(루트 .env 폴백으로 무중단). release 단계 별도 진행.

Validation Plan

• tests/runtime/test_config_resolution.py(config-dir .env/--env-file/CWD 무관/override) + test_config_dotenv.py 6건 무회귀 + .gitignore 가드. 전체 375 passed, ruff clean.