# req-103: 차단형 reconcile — B/C 불일치 슬롯 reconcile-warning 전이

- Status: Implemented
- 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-20260626-01
- Date: 2026-06-26
- Author: trex-core-dev
- Status: Approved → Implemented
- Summary: BAT-050(PR #31, ced7eda) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. reconcile_core_holdings B케이스·reconcile_positions C케이스 차단, 정상 케이스 오발동 없음, A케이스 기존 동작 유지, 전 AC 검증 완료.

#### Acceptance Criteria Delta
- 없음

#### Impacted Area Delta
- 없음

#### Delivery Trace Delta
- Batches: BAT-050 (core-A)
- Releases: M3 (배포 대기)

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

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

### 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.