trex-core/docs/srs/Data/req-102_reconcile-warning-durable-store.md

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

• Status: Approved
• 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-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.