# req-096: 체결가 백필·0가격 통과 WARN 로깅

- Status: Approved
- Type: Exception
- Priority: High
- Owner: trex-core-dev

## Intent
- REQ-095의 백필 가드가 발동되거나, 백필 없이 price≤0 체결이 하류(원장·슬롯)로 통과하는 경우, 운영자가 사후에도 해당 이벤트를 식별할 수 있도록 구조화된 WARN 로그를 남겨야 한다.
- 현재 원장 skip 가드(`portfolio_id` 부재, `execution_id` 부재)는 각각 WARN을 남기는 반면, "체결됐는데 price≤0" 케이스는 어떤 가드에도 걸리지 않고 조용히 통과한다. 이 가시성 공백을 동일한 수준으로 맞춘다.
- WARN 로그는 슬롯·심볼·주문ID·원가격·대체가격·사유를 포함해 백필 항목이 실제 평균가인지 백필 근사인지 추적 가능(NFR-3)하게 한다.

## Requirement
- 체결(완전·부분 취소 후) 처리에서 REQ-095의 백필이 발동된 경우, 슬롯 ID·심볼·주문 ID·원 브로커 평균가(None 또는 0)·대체가격(백필 지정가)·사유(`avg_price_backfill`)를 포함한 WARN 수준 구조화 로그를 반드시 남겨야 한다.
- 지정가마저 부재/≤0인 극단 케이스(design 확정 폴백 정책 적용 시점)에서 백필이 불가능해 price≤0 상태가 하류로 넘어가는 경우에도, 동일한 필드 집합을 포함한 WARN(또는 그 이상 수준) 로그를 남겨야 한다.
- 정상 평균가(happy path) 수신 경로에서는 이 WARN 로그가 발생하지 않아야 한다.

## Acceptance Criteria

1. Given `fs.avg_price`가 None 또는 ≤0이고 지정가 백필이 적용된 체결, When 집행 루프가 해당 체결을 처리할 때, Then `slot_id`, `symbol`, `broker_order_id`(또는 동등 주문 식별자), 원 `avg_price`(None 또는 0), `backfill_price`(대체가), `reason=avg_price_backfill` 필드를 포함하는 WARN 로그가 정확히 1건 생성된다.
2. Given 지정가마저 부재/≤0인 극단 케이스(폴백 정책 적용), When 집행 루프가 해당 체결을 처리할 때, Then 슬롯·심볼·주문 ID·원가격·사유를 포함한 WARN 이상 수준 로그가 1건 이상 생성된다(0 저장 또는 skip 어느 쪽이든 무경고 통과 없음).
3. Given `fs.avg_price`가 정상 양수인 체결(happy path), When 집행 루프가 처리할 때, Then 백필 관련 WARN 로그가 생성되지 않는다.
4. Given 백필 WARN 로그가 생성된 후 운영자가 로그를 조회할 때, Then 해당 로그로부터 어떤 슬롯의 어떤 체결에서 백필이 발생했는지, 원래 브로커가 제공한 가격이 무엇이었는지, 어떤 가격으로 대체됐는지를 식별할 수 있다(NFR-3: 실제 평균가 vs 백필 근사 구분 가능).

## Impacted Area
- Docs: `docs/operations.md` — 백필 WARN 발생 시 운영자 점검 절차 추가 권고 (implementation 후 갱신)
- Modules:
  - `trex_core/application/execution.py` — `_on_filled`, `_on_partial_cancel`, `_record_ledger` 내 백필 분기 후 WARN 로그 추가
- Tests:
  - `tests/application/test_execution.py` (또는 동등 경로) — 백필 경로에서 WARN 로그 발생 단언, happy path에서 WARN 미발생 단언

## Notes
- 이 REQ는 REQ-095(백필 가드)와 독립적으로 측정 가능하다: REQ-095가 값 정정을, REQ-096이 가시성을 담당하며, 둘 다 같은 batch에서 구현해야 함께 의미가 있다.
- 원장 skip 가드(portfolio_id 부재 WARN, execution_id 부재 WARN)와 동일한 운영 가시성 수준을 목표로 한다(Discovery FR-3 기준).
- AC-2의 극단 케이스(지정가마저 부재)의 폴백 정책 세부 사항은 REQ-095와 동일하게 design 확정 대상이다. 본 REQ는 어떤 폴백 정책이 채택되더라도 무경고 통과가 없어야 한다는 원칙을 요구한다.
- NFR-3(백필 추적 가능) — Discovery NFR-3을 본 REQ AC-4로 흡수.
- Discovery: dcy-032_20260621_fill-missing-price-cost-basis-backfill.md (FR-3)

## Change Log

### CHG-20260621-01
- Date: 2026-06-21
- Author: trex-core-dev

#### Change Summary
- 최초 생성 (draft-req dcy-032)

#### Intent
- 백필 발생 및 price≤0 체결 통과 시 운영 가시성 확보를 위한 WARN 로깅 요구사항 신규 정의

#### Acceptance Criteria Delta
- Added:
  - AC-1~4 신규 정의
- Updated: 없음
- Removed: 없음

#### Impacted Area Delta
- Docs: docs/operations.md (implementation 후 갱신)
- Modules: trex_core/application/execution.py
- Tests: tests/application/test_execution.py

#### Delivery Trace Delta
- Batches: 미정 (suggest-batch-reqs 이후 편성, REQ-095와 동일 batch 예상)
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no (최초 생성)
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: 없음