feat: add portfolio snapshot read layer

2026-06-06 09:33:00 +09:00
parent 56e977a7ad
commit ca757009f5
51 changed files with 3565 additions and 51 deletions
@@ -0,0 +1,136 @@
+# req-032: 런타임 pause/resume 제어
+
+- Status: Implemented
+- Type: Interface
+- Priority: Medium
+- Owner: project maintainers
+
+## Intent
+- 운영자가 특정 자산을 런타임에 매매에서 제외(pause)하거나 다시 포함(resume)할 수 있게 한다. 프로그램 이상·이벤트 시 안전 통제를 위한 수동 overlay 다.
+
+## Requirement
+- pause/resume 단위는 `portfolio_id`(= asset_id)다.
+- 제어는 **CLI** 와 **dcy-006 RPC 제어 메시지** 둘 다로 가능하며, 둘은 동일한 pause 상태를 변경한다. config 리로드 방식은 채택하지 않는다.
+- pause 상태는 **Postgres 에 영속**(portfolio_id 키)하며 daemon 재시작 후에도, 일일 스냅샷 refresh 후에도 유지된다(refresh 는 universe/포지션만 갱신, pause overlay 불변).
+- 적용 범위는 **전역** — pause 된 자산은 모든 view/전략 요청에서 마스킹된다.
+- pause 는 request-time mask 이므로 resume 시 다음 요청부터 즉시 응답에 복귀한다.
+
+## Acceptance Criteria
+1. Given 운영자가 `portfolio_id` 를 pause, When 임의 `view`/`strategy_key` 로 스냅샷을 요청, Then 그 자산은 응답에서 마스킹된다.
+2. Given pause 상태에서 daemon 재시작 또는 일일 refresh 발생, When 이후 요청, Then pause 가 유지된다.
+3. Given 운영자가 resume, When 다음 요청, Then 그 자산이 응답에 다시 포함된다.
+4. Given CLI 로 pause 후 RPC 제어로 조회(또는 그 반대), Then 동일한 pause 상태가 보인다.
+
+## Impacted Area
+- Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md
+- Modules: pause 상태 store(Postgres), CLI 제어, dcy-006 RPC 제어 메시지 핸들러, 응답 산출 시 pause 마스킹
+- Tests: pause→호출→resume→호출 시퀀스, 재시작/refresh 후 영속
+
+## Notes
+- pause(수동·영속) vs warning(자동·일시, REQ-031)은 독립 overlay 이며 OR 합성(둘 중 하나라도면 마스킹).
+- OQ-10 반영.
+
+## Change Log
+
+### CHG-20260606-01
+- Date: 2026-06-06
+- Author: project maintainers
+
+#### Change Summary
+- dcy-005 FR-9 + OQ-10 분해로 최초 생성(Proposed).
+
+#### Intent
+- 런타임 pause/resume 제어(단위·제어 표면·영속·범위) 정의.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~4 신규
+- Updated:
+  - none
+- Removed:
+  - none
+
+#### Impacted Area Delta
+- Docs:
+  - dcy-005
+- Modules:
+  - pause store, CLI, RPC 제어, 마스킹
+- Tests:
+  - pause/resume 시퀀스, 영속
+
+#### Delivery Trace Delta
+- Batches:
+  - none
+- Releases:
+  - none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req
+
+#### Validation Plan
+- pause→호출→resume→호출 + 재시작 영속 테스트로 AC 검증.
+
+### CHG-20260606-02
+- Date: 2026-06-06
+- Author: project maintainers
+
+#### Change Summary
+- 승인 게이트 통과 → Proposed → Approved.
+
+#### Acceptance Criteria Delta
+- Added: none
+- Updated: none
+- Removed: none
+
+#### Impacted Area Delta
+- 변경 없음
+
+#### Delivery Trace Delta
+- Batches: none
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: suggest-batch-reqs / draft-batch
+
+#### Validation Plan
+- 승인 기록. 구현 전 재검증 불필요.
+
+### CHG-20260606-03
+- Date: 2026-06-06
+- Author: Justin Ko
+
+#### Change Summary
+- Status 변경: Approved → Implemented. BAT-008 release-candidate verification evidence 기반.
+
+#### Intent
+- pause/resume CLI + RPC 제어 + Postgres 영속 구현 완료 상태로 동기화.
+
+#### Acceptance Criteria Delta
+- Added/Updated/Removed: 없음
+
+#### Impacted Area Delta
+- Docs/Modules/Tests: 없음
+
+#### Delivery Trace Delta
+- Batches:
+  - BAT-008 (release-candidate)
+- Releases:
+  - none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: Implemented
+- Follow-up Action: release 단계는 별도 진행
+
+#### Validation Plan
+- AC-1: tests/application/test_pause_handler.py::test_pause_then_list + test_snapshot_selection.py::test_pause_overlay_masks_asset.
+- AC-2: tests/adapters/portfolio/test_postgresql_pause_store.py::test_durability_simulated_via_fresh_store_instance.
+- AC-3: tests/application/test_pause_handler.py::test_resume_clears_pause.
+- AC-4: tests/application/test_pause_handler.py::test_cli_pause_visible_to_rpc_list_via_shared_store + 실 daemon RPC 운영 검증.