# 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 단독)을 유지한다(회귀 없음).

## Acceptance Criteria
1. Given CWD 에 `.env`(`TREX_POSTGRESQL_DSN=...`)가 있고 해당 OS env 가 미설정, When `DaemonConfig.from_env()`, Then `.env` 값이 로드되어 `dsn` 에 반영된다.
2. Given OS env 와 `.env` 에 같은 키가 다른 값으로 존재, When `from_env()`, Then OS env 값이 우선한다(.env 가 덮어쓰지 않음).
3. Given `.env` 가 없음, When `from_env()`, Then 기존처럼 `os.environ` 만으로 동작한다(회귀 없음).
4. Given 저장소, When `.gitignore` 확인, Then `.env` 가 무시 대상이며 `.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()` 기본(즉시 전량 체결·거부 없음)과 byte-for-byte 동일하다(회귀 없음).

## Impacted Area
- Docs: 없음(baseline 구조/인터페이스/런타임 흐름 변경 없음 — minor-change)
- Modules: pyproject.toml(python-dotenv), trex_core/runtime/config.py(load_dotenv, PaperBrokerConfig), trex_core/runtime/daemon.py(_build_broker paper 주입), .gitignore, .env.example(신규 + paper 튜닝 키)
- Tests: tests/runtime/test_config_dotenv.py (로드/우선순위/부재 회귀, paper 튜닝 기본/파싱)

## 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 재참조로 충분.