trex-core/docs/srs/Exception/req-107_blocking-reconcile-logging-and-alarm.md

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

• Status: Approved
• 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-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.