# req-107: 차단/해제 전이 식별 로깅 + 고영향 불일치 알람

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

## Intent
- reconcile-warning 차단 및 해제 전이마다 슬롯·심볼·원인케이스·수량 before/after·actor를 포함한 **식별 가능한 구조화 로그**를 남겨 운영자가 차단 원인과 이력을 추적할 수 있게 한다.
- 고영향 불일치(케이스 A: 슬롯 보유인데 브로커 0 — phantom holding)는 기존 알람 채널(dcy-033/`trex.alerts`)로 통지한다.
- dcy-034 FR-6 대응.

## Requirement
- 시스템은 reconcile-warning 차단 전이(`set_warned`) 시 WARNING 레벨 로그를 남겨야 하며, 로그에는 `slot_id`, `portfolio_id`, `symbol`, `case_code`(B 또는 C), `broker_qty`, `slot_qty`(B의 경우 before), `hub_qty`(C의 경우 원장 수량), `actor`="reconcile" 필드가 포함되어야 한다.
- 시스템은 reconcile-warning 해제 전이(`clear_warned`) 시 INFO 레벨 로그를 남겨야 하며, 로그에는 `slot_id`, `portfolio_id`, `symbol`, `actor`(sync/verify/reconcile), `resolved_by`(sync 또는 verify) 필드가 포함되어야 한다.
- 케이스 A(슬롯 보유, 브로커 0 — phantom holding)는 기존 REQ-100(`AlarmEmitter.publish_alarm`) 경로를 통해 `trex.alerts` exchange로 CRITICAL 알람을 발행해야 한다(기존 `reconcile_core_holdings` 내 alarm_emitter 호출 활성 — 이미 구현됨, 여기서는 차단형 전이와의 일관성 확인).
- B/C 케이스 차단 시 WARNING 로그는 구조화 포맷(JSON 또는 key=value)으로 남겨져 Loki/로그 검색에서 `slot_id`, `case_code` 필드로 필터링 가능해야 한다(REQ-084 구조화 로깅 기반과 일관).
- sync 또는 verify로 warning이 해제될 때, actor 필드에 "sync" 또는 "verify"가 기록되어야 한다.

## Acceptance Criteria
1. Given 케이스 B 불일치 탐지 시, When `set_warned`가 호출되면, Then `level=WARNING`, `slot_id`, `portfolio_id`, `symbol`, `case_code='B'`, `broker_qty`, `slot_qty`(before) 필드를 포함한 로그가 기록된다.
2. Given 케이스 C 불일치 탐지 시, When `set_warned`가 호출되면, Then `level=WARNING`, `slot_id`, `portfolio_id`, `symbol`, `case_code='C'`, `hub_qty`, `broker_qty` 필드를 포함한 로그가 기록된다.
3. Given `trex-core sync`로 warning 해제 시, When `clear_warned`가 호출되면, Then `level=INFO`, `slot_id`, `portfolio_id`, `symbol`, `actor='sync'` 필드를 포함한 로그가 기록된다.
4. Given `trex-core verify`로 warning 해제 시, When `clear_warned`가 호출되면, Then `level=INFO`, `slot_id`, `portfolio_id`, `symbol`, `actor='verify'` 필드를 포함한 로그가 기록된다.
5. Given 케이스 A(슬롯 보유, 브로커 0)에서, When `reconcile_core_holdings`가 실행되면, Then 기존 REQ-100 경로로 `trex.alerts` CRITICAL 알람이 발행된다(기존 동작 회귀 없음).
6. Given 차단/해제 로그가 남겨진 경우, When 로그를 `slot_id` 또는 `case_code`로 필터링하면, Then 해당 이벤트를 특정할 수 있다(Loki 구조화 로그 필터링 가능).

## Impacted Area
- Docs: `docs/operations.md` (로그 조회 방법 추가)
- Modules:
  - `trex_core/application/reconciliation.py` (차단 전이 로그 — set_warned 호출 지점)
  - `trex_core/runtime/cli.py` (`sync`/`verify` 해제 로그 — clear_warned 호출 지점)
  - `trex_core/adapters/portfolio/reconcile_warning_store.py` (선택: store 자체에 로그 위임 vs 호출부 로그 — batch design에서 결정)
- Tests:
  - `tests/application/test_reconciliation.py` (차단 로그 필드 검증)
  - `tests/runtime/test_cli.py` (해제 로그 actor 필드 검증)
  - 기존 REQ-100 알람 테스트 회귀 확인

## Notes
- 케이스 A 알람은 REQ-100 구현(`reconcile_core_holdings` 내 `alarm_emitter.publish_alarm("core_holding_broker_flat", ...)`)이 이미 존재하므로, 이 REQ에서는 B/C 차단 로그 추가와 A 알람 기존 동작 회귀 없음을 확인하면 된다.
- 구조화 로그 포맷은 REQ-084(`trex_core/runtime/logging_setup.py`)와 일관성 있게 작성한다.
- 고영향 B 불일치(large qty 차이 등)에 대해 B 케이스도 `trex.alerts` 알람으로 확대할지는 batch design에서 검토한다(dcy-034는 "고영향(A phantom)은 trex.alerts" 명시, B/C는 WARN 로그로 충분함을 시사).
- dcy-034 FR-6 대응.

## Change Log

### CHG-20260626-01
- Date: 2026-06-26
- Author: trex-core-dev
- Status: Approved → Implemented
- Summary: BAT-050/051(PR #31/#32) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. B/C 케이스 WARNING 로그 필드(slot_id/case_code/qty before-after), sync/verify 해제 INFO 로그(AC-3/4), A케이스 CRITICAL 알람 회귀 전 AC 검증 완료.

#### Acceptance Criteria Delta
- 없음

#### Impacted Area Delta
- 없음

#### Delivery Trace Delta
- Batches: BAT-050 (core-A, AC-1/2/5), BAT-051 (core-B, AC-3/4)
- Releases: M3 (배포 대기)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Implemented
- Follow-up Action: 없음.

#### Validation Plan
- BAT-050/051 verification.md AC 매핑 전항목 PASS 확인됨.

### CHG-20260625-02
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-107 **Proposed → Approved** (confirm-req, 팀장 2026-06-25).

#### Intent
- 팀장 confirm-req로 상태 승인. 내용 변경 없음(초안 그대로 승인).

#### Acceptance Criteria Delta
- Added: 없음.
- Updated: 없음.
- Removed: 없음.

#### Impacted Area Delta
- 없음.

#### Delivery Trace Delta
- Batches: 미정 (suggest-batch-reqs 이후)
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: Approved
- Follow-up Action: batch 편성 후 구현.

#### Validation Plan
- 차단 로그 필드 검증 테스트 pass / 해제 로그 actor 필드 검증 pass / A 알람 회귀 pass.

### CHG-20260625-01
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-107 신규 생성 (Proposed) — dcy-034 FR-6 대응, draft-req 단계.

#### Intent
- 차단/해제 전이 가시화. 운영자가 로그만으로 불일치 발생 및 해소 이력을 추적할 수 있는 구조화 로그 신설.

#### Acceptance Criteria Delta
- Added: AC-1~6 전부 신규.
- Updated: 없음.
- Removed: 없음.

#### Impacted Area Delta
- Docs: operations.md 갱신.
- Modules: reconciliation.py, cli.py.
- Tests: 로그 필드 검증 신규.

#### Delivery Trace Delta
- Batches: 미정
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no (신규 REQ)
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 batch design.

#### Validation Plan
- 차단 로그 필드(slot_id/case_code/qty before-after/actor) 검증 테스트 pass / 해제 로그 actor 필드 검증 pass / A 알람 회귀 pass.