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,108 @@
+# req-103: 차단형 reconcile — B/C 불일치 슬롯 reconcile-warning 전이
+
+- Status: Approved
+- Type: Integration
+- Priority: High
+- Owner: trex-core-dev
+
+## Intent
+- boot/일일 reconcile(`reconcile_core_holdings`, `reconcile_positions`) 수행 중 B(슬롯↔브로커 수량 불일치) 또는 C(원장↔슬롯 수량 불일치)가 탐지되면, 해당 슬롯을 **WARN 로그만 남기던 기존 동작에서 reconcile-warning durable 차단으로 승격**한다.
+- dcy-034 FR-1 대응: 불일치 슬롯이 탐지 즉시 차단되어 정합 전 잘못된 매매가 나가지 않도록 한다.
+- 단기 인스턴스 정상(일치) 시나리오에서 차단이 오발동하지 않아야 한다(NFR-2/S-4).
+
+## Requirement
+- 시스템은 `reconcile_core_holdings` 실행 중 케이스 B(슬롯 보유, 브로커 수량 불일치 — qty 차이)를 탐지하면 해당 slot_id를 `ReconcileWarningStore.set_warned(slot_id, portfolio_id, case_code='B', actor='reconcile', reason=...)` 로 durable 차단해야 한다.
+- 시스템은 `reconcile_positions` 실행 중 케이스 C(원장 portfolio-hub 수량 ≠ 브로커 수량)를 탐지하면 관련 슬롯(portfolio_id로 조회)을 `ReconcileWarningStore.set_warned(slot_id, portfolio_id, case_code='C', actor='reconcile', reason=...)` 로 durable 차단해야 한다.
+- 케이스 A(슬롯 보유, 브로커 0)는 기존 `SlotState.ERROR` 전이를 유지하고 reconcile-warning 스토어를 사용하지 않는다(기존 동작 보존).
+- `snapshot_scheduler.run_once()` 내 reconcile 순서(reconcile_positions → _reconcile_slots → reconcile_core_holdings)에서 두 함수 모두 ReconcileWarningStore를 주입받아 차단을 기록해야 한다.
+- 불일치가 실제로 있을 때만 차단이 발생하며, 수량이 일치하는 슬롯에는 차단이 적용되지 않아야 한다.
+
+## Acceptance Criteria
+1. Given 슬롯 보유 수량과 브로커 잔고 수량이 다른 케이스 B 입력에서, When `reconcile_core_holdings`가 실행되면, Then 해당 slot_id가 ReconcileWarningStore에 `case_code='B'`로 기록된다.
+2. Given portfolio-hub 원장 수량과 브로커 수량이 다른 케이스 C 입력에서, When `reconcile_positions`가 실행되면, Then 관련 슬롯의 slot_id가 ReconcileWarningStore에 `case_code='C'`로 기록된다.
+3. Given 슬롯 수량과 브로커 수량이 일치하는 정상 케이스에서, When reconcile가 실행되면, Then ReconcileWarningStore에 해당 slot_id 행이 생기지 않는다(오발동 없음, S-4).
+4. Given 케이스 A(슬롯 보유, 브로커 0)에서, When `reconcile_core_holdings`가 실행되면, Then 기존처럼 SlotState.ERROR 전이가 발생하고 ReconcileWarningStore는 사용하지 않는다.
+5. Given `ReconcileWarningStore`가 주입되지 않은 구성에서, When reconcile가 실행되면, Then 기존 WARN 로그 동작이 유지되고 예외가 발생하지 않는다(하위 호환 / 테스트 더블 지원).
+6. Given 단기 인스턴스(M1/M2 라이브) 정상 시나리오에서, When boot/일일 reconcile가 실행되면, Then 신규 reconcile-warning이 발생하지 않는다(회귀 0, NFR-2, S-4).
+
+## Impacted Area
+- Docs: `docs/interface-contract.md`, `docs/runtime-flows.md` (reconcile 흐름 갱신 필요 여부 batch design에서 확인)
+- Modules:
+  - `trex_core/application/reconciliation.py` (`reconcile_core_holdings`, `reconcile_positions` — ReconcileWarningStore 주입 파라미터 추가)
+  - `trex_core/application/snapshot_scheduler.py` (`SnapshotScheduler.__init__`, `run_once` — ReconcileWarningStore 주입 및 전달)
+- Tests:
+  - `tests/application/test_reconciliation.py` (신규 B/C 차단 케이스, 정상 케이스 오발동 없음, A 케이스 기존 동작 유지, store 미주입 하위 호환)
+  - `tests/application/test_snapshot_scheduler.py` (run_once 내 차단 흐름 통합 검증)
+  - 기존 reconcile 회귀 테스트
+
+## Notes
+- `reconcile_positions`는 현재 portfolio_id 단위 경고(`store.set_warning`)를 in-memory로 관리한다. C 차단은 portfolio_id에 대응하는 slot을 조회해야 하므로, `reconcile_positions`에 `slot_repo` 주입이 필요할 수 있다. 구체 구현은 batch design에서 결정한다.
+- ReconcileWarningStore 파라미터는 Optional로 추가해 기존 호출부(테스트 포함)의 하위 호환을 유지한다.
+- 불일치 수량 before/after 정보는 REQ-107(로깅) 범위에서 다룬다.
+- dcy-034 FR-1, NFR-2, NFR-3, S-4 대응.
+
+## Change Log
+
+### CHG-20260625-02
+- Date: 2026-06-25
+- Author: trex-core-dev
+
+#### Change Summary
+- REQ-103 **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
+- 신규 B/C 차단 테스트 pass / 정상 케이스 오발동 없음 테스트 pass / 기존 reconcile 회귀 pass.
+
+### CHG-20260625-01
+- Date: 2026-06-25
+- Author: trex-core-dev
+
+#### Change Summary
+- REQ-103 신규 생성 (Proposed) — dcy-034 FR-1 대응, draft-req 단계.
+
+#### Intent
+- 기존 WARN 로그 전용이던 B/C 불일치를 durable 차단으로 승격해 cold-start 시 정합 전 매매를 구조적으로 차단.
+
+#### Acceptance Criteria Delta
+- Added: AC-1~6 전부 신규.
+- Updated: 없음.
+- Removed: 없음.
+
+#### Impacted Area Delta
+- Docs: runtime-flows.md 갱신 예정.
+- Modules: reconciliation.py, snapshot_scheduler.py.
+- Tests: 신규 B/C 케이스 테스트.
+
+#### 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 편성.
+
+#### Validation Plan
+- 신규 B/C 차단 테스트 pass / 정상 케이스 오발동 없음 테스트 pass / 기존 reconcile 회귀 pass.