# req-102: reconcile-warning durable store — slot_id/pid 키 별도 테이블

- Status: Implemented
- Type: Data
- Priority: High
- Owner: trex-core-dev

## Intent
- boot/일일 reconcile에서 슬롯↔브로커(B) 또는 원장↔슬롯(C) 불일치가 탐지될 때 해당 슬롯을 차단하는 **durable한 reconcile-warning 상태**를 저장할 별도 PostgreSQL 테이블을 도입한다.
- OQ-1(dcy-034) 확정: pause_store와 동형 설계를 선례로 삼아 SlotState enum·전이표·slots RPC wire 계약을 변경하지 않는 비침습 접근을 취한다(NFR-4).
- 재시작 후에도 차단 상태가 유지되어야 한다(NFR-1).

## Requirement
- 시스템은 `slot_reconcile_warning` 테이블(PK: slot_id)을 PostgreSQL에 생성하고, `slot_id`, `portfolio_id`, `case_code`(B 또는 C), `actor`, `reason`, `created_at`, `updated_at` 컬럼을 가져야 한다.
- `ReconcileWarningStore`(application port) 및 `PostgreSQLReconcileWarningStore`(adapter)는 pause_store와 동형 인터페이스(`set_warned`, `clear_warned`, `list_warned`, `is_warned`)를 제공해야 한다.
- 스토어는 slot_id를 PK로 삼고 동일 slot_id의 중복 삽입 시 `ON CONFLICT DO UPDATE`로 갱신해야 한다.
- DB 마이그레이션 스크립트로 테이블 생성을 관리해야 한다.

## Acceptance Criteria
1. Given `slot_reconcile_warning` 테이블이 없는 DB에서 마이그레이션을 실행하면, When 마이그레이션이 완료되면, Then 테이블이 존재하고 PK(slot_id), case_code, portfolio_id, actor, reason, created_at, updated_at 컬럼이 모두 존재한다.
2. Given `ReconcileWarningStore.set_warned(slot_id, portfolio_id, case_code, actor, reason)` 호출 후, When 데몬이 재시작되어도, Then `is_warned(slot_id)` = True가 유지된다(durable).
3. Given 동일 slot_id에 대해 `set_warned`를 두 번 호출하면, When DB를 조회하면, Then 행이 1개이고 최신 값으로 갱신되어 있다(ON CONFLICT DO UPDATE).
4. Given `clear_warned(slot_id)` 호출 후, When `is_warned(slot_id)`를 조회하면, Then False를 반환한다.
5. Given `list_warned()` 호출 시, When 복수의 warned slot이 존재하면, Then 해당 slot_id 집합이 반환된다.
6. Given `SlotState` enum 및 `ALLOWED_TRANSITIONS`, When 스토어를 추가해도, Then `domain/slot/state.py`에 새 SlotState 또는 전이 추가가 없다(wire 계약 불변, NFR-4).

## Impacted Area
- Docs: `docs/srs/index.md` (Next Requirement ID, Register 갱신)
- Modules:
  - `trex_core/adapters/portfolio/reconcile_warning_store.py` (신규 — pause_store.py 동형)
  - `trex_core/application/ports.py` 또는 `application/portfolio.py` (ReconcileWarningStore 포트 정의)
  - `trex_core/adapters/persistence/migrations/` (신규 마이그레이션)
  - `trex_core/domain/slot/state.py` (변경 없음 — 불변 확인)
- Tests:
  - `tests/application/` 또는 `tests/adapters/` — ReconcileWarningStore 단위 테스트 (set/clear/list/is_warned, durable 검증, ON CONFLICT 검증)
  - 기존 slot state machine 테스트 회귀 확인

## Notes
- pause_store 선례(`adapters/portfolio/pause_store.py`, `application/portfolio.py:PauseStore`)를 동형으로 따른다.
- 포트 정의 위치(application/portfolio.py 내 Protocol 클래스 vs 별도 파일)는 batch design에서 결정한다.
- `case_code` 값: `B`(슬롯 보유·브로커 수량 불일치), `C`(원장↔슬롯 수량 불일치).
- dcy-034 FR-5, NFR-1, NFR-4 대응.

## Change Log

### CHG-20260626-01
- Date: 2026-06-26
- Author: trex-core-dev
- Status: Approved → Implemented
- Summary: BAT-050(PR #31, ced7eda) + BAT-051(PR #32, 07b393d) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. 683 passed / 47 skipped / 0 fail. slot_reconcile_warning 테이블 마이그레이션, ReconcileWarningStore(in-memory/PG) 신규 구현, 전 AC 검증 완료.

#### Acceptance Criteria Delta
- 없음 (기존 AC 그대로 충족)

#### 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: M3 배포 시 PG durable 검증.

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

### CHG-20260625-02
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-102 **Proposed → Approved** (confirm-req, 팀장 2026-06-25).

#### Intent
- 팀장 confirm-req로 상태 승인. 내용 변경 없음(OQ-1 반영 초안 그대로 승인).

#### 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
- ReconcileWarningStore 단위 테스트 pass / DB 마이그레이션 스크립트 적용 검증 / SlotState 불변 회귀 테스트 pass.

### CHG-20260625-01
- Date: 2026-06-25
- Author: trex-core-dev

#### Change Summary
- REQ-102 신규 생성 (Proposed) — dcy-034 FR-5 대응, draft-req 단계.

#### Intent
- dcy-034 OQ-1 확정(pause_store 동형 별도 durable store)을 반영해 reconcile-warning 저장 능력 도입.

#### Acceptance Criteria Delta
- Added: AC-1~6 전부 신규.
- Updated: 없음.
- Removed: 없음.

#### Impacted Area Delta
- Docs: index.md 갱신.
- Modules: reconcile_warning_store.py 신규, 마이그레이션 신규.
- Tests: ReconcileWarningStore 단위 테스트 신규.

#### Delivery Trace Delta
- Batches: 미정 (suggest-batch-reqs 이후)
- Releases: 미정

#### Revalidation Impact
- Reverification Needed: no (신규 REQ)
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 batch 편성.

#### Validation Plan
- ReconcileWarningStore 단위 테스트 pass / DB 마이그레이션 스크립트 적용 검증 / SlotState 불변 회귀 테스트 pass.