trex-core/docs/srs/Integration/req-103_blocking-reconcile-b-c-cases.md

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.