docs(dcy-034): confirm-req REQ-102~108 Approved — 차단형 reconcile + sync/verify

dcy-034 confirm-req 완료(팀장 2026-06-25): REQ-102(warning store)/103(차단 reconcile)/104(pause∨warning 게이트)/105(sync)/106(verify)/107(로깅·알람)/108(NFR) Approved. OQ-A(INACTIVE→HOLDING actor제한 전이)/OQ-B(안전망 차단예외)/OQ-C(verify C전용) 반영. FR-7→portfolio-hub dcy-008/REQ-043 교차참조. .claude/worktrees gitignore. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHtM5Ws1HKCKQ4JGi6GRb5
2026-06-26 00:16:21 +09:00
parent e052e70619
commit 35f3147250
10 changed files with 797 additions and 4 deletions
@@ -0,0 +1,109 @@
+# 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.