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