# req-029: 자산 선별(slot overlay) + view 모드 + strategy_key 필터

- Status: Implemented
- Type: Interface
- Priority: High
- Owner: project maintainers

## Intent
- 스냅샷 응답에 담을 자산 집합을 core 의 권위 슬롯 상태로 선별한다. 보유(holding)는 포함하되 일시·불안전 상태는 마스킹하고, 전략 타입별 view 와 전략별 필터를 제공한다.

## Requirement
- 응답 base 집합은 요청 `view`(`all` 기본 | `buyable` | `held`)로 선택한다: `all` = universe 전체(portfolio-hub 보유 + holding 슬롯), `buyable` = universe − 슬롯 점유, `held` = holding 슬롯 자산만.
- 마스킹(pending·warning·pause)은 전 모드에 균일 적용한다. pending 은 모든 모드에서 마스킹되므로 `held` 는 holding 만 포함한다. 포함/마스킹 판정은 core 권위 슬롯 상태 + 정합 결과 + pause 상태를 portfolio-hub 보유 여부보다 우선한다(slot overlay, 불변식 A).
- 선택적 `strategy_key`(요청 시) 는 자산의 단일 `active_strategy_id` 와 대소문자 구분 정확 일치로 직교 필터링한다. `strategy_key` 는 사람이 읽는 안정 유일 slug(예: `target-value-v1`)다.
- 최종 합성: `assets = base(view) − mask(pending·warning·pause) − (strategy_key 필터, 주어진 경우)`. `buyable` 은 `available_slots=0` 이면 `[]` 다.

## Acceptance Criteria
1. Given 같은 종목이 holding 슬롯·pending 슬롯에 각각 있을 때, When `view=all`, Then holding 자산은 포함되고 pending 자산은 마스킹된다.
2. Given `available_slots=0`, When `view=buyable`, Then `[]` 를 반환한다.
3. Given `view=held`, Then holding 슬롯 자산만 반환하고 pending 은 제외한다.
4. Given `strategy_key` 제공, Then `active_strategy_id` 가 일치하는 자산만 반환하고, 생략 시 (마스킹 후) 전체 자산을 반환한다.
5. Given warning 또는 pause 자산, When 임의 `view`, Then 해당 자산은 마스킹된다.

## Impacted Area
- Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md
- Modules: trex_core/application 스냅샷 선별/slot overlay 로직(slot repository 재사용), strategy_key 필터
- Tests: view 모드별·마스킹·strategy_key 필터 합성 테스트

## Notes
- core 권위 슬롯 상태(불변식 A)가 portfolio-hub 보유 여부보다 우선한다.
- OQ-4(in-flight 합성)·OQ-9(strategy_key)·OQ-11/OQ-12(view 모드) 반영.
- holding 자산의 보유 수량 표기를 core 슬롯 vs 스냅샷 중 무엇 기준으로 할지(holding→ledger flush 갭)는 설계 시 확정(dcy-005 OQ-4 잔여).
- (orb-v1 소비 참고, CHG-04) 첫 전략 orb-v1 은 `strategy_key` 없이 `view=buyable` 로 조회한다. 즉 전략 설정과 무관하게 universe 전체를 대상으로 하고, slot 점유(holding·pending)·warning(정합 불일치)·pause(사용자) 만 제외하면 된다 — 이는 `view=buyable` + `strategy_key` 생략의 기존 동작과 정확히 일치한다. pending(in-flight) 제외는 중복 주문 방지, warning 제외는 틀린 baseline 매매 차단(REQ-031) 목적으로 orb-v1 의도에 부합한다(사용자 확인). 따라서 단일 전략 단계에서는 `/v1/portfolios` PortfolioItem 의 전략 필드(active_strategy_id/strategy_params) 부재가 orb-v1 동작에 무해하다. (2번째 전략부터는 strategy_key 라우팅이 필요해져 전략 필드 부재 해소가 재대두된다.)

## Change Log

### CHG-20260606-01
- Date: 2026-06-06
- Author: project maintainers

#### Change Summary
- dcy-005 FR-2/FR-8 + OQ-4/9/11/12 분해로 최초 생성(Proposed).

#### Intent
- 응답 자산 선별(slot overlay·view·strategy_key) 규칙 정의.

#### Acceptance Criteria Delta
- Added:
  - AC-1~5 신규
- Updated:
  - none
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - dcy-005
- Modules:
  - 스냅샷 선별/slot overlay, strategy_key 필터
- Tests:
  - view/마스킹/필터 테스트

#### 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
- 슬롯 상태 주입 후 view/마스킹/strategy_key 합성 테스트로 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
- `build_snapshot_envelope` 의 base(view) 산출 + masking OR 합성 + strategy_key 직교 필터 구현 완료 상태로 동기화.

#### 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_snapshot_selection.py::test_view_all_includes_holding_excludes_pending_for_same_symbol.
- AC-2: ::test_view_buyable_with_zero_available_slots_returns_empty.
- AC-3: ::test_view_held_returns_only_holding_slot_assets.
- AC-4: ::test_strategy_key_orthogonal_filter + ::test_strategy_key_missing_includes_everything_unmasked.
- AC-5: ::test_warning_overlay_masks_asset_uniformly_across_views + ::test_pause_overlay_masks_asset.

### CHG-20260606-04
- Date: 2026-06-06
- Author: Justin Ko

#### Change Summary
- 첫 전략 orb-v1 의 스냅샷 소비 패턴을 Notes 참고 사항으로 추가(본문 비변경). AC/요구사항/계약 변경 없음.

#### Intent
- orb-v1 은 전략 설정(active_strategy_id/strategy_params)과 무관하게 모든 자산을 대상으로 하며 `strategy_key` 없이 `view=buyable` 로 조회한다는 소비 계약을 명시해, `/v1/portfolios` PortfolioItem 의 전략 필드 부재가 orb-v1 에 무해함을 기록한다.

#### Acceptance Criteria Delta
- Added: none
- Updated: none
- Removed: none

#### Impacted Area Delta
- Docs:
  - 본 REQ Notes 에 orb-v1 소비 참고 사항 1건 추가
- Modules: 없음
- Tests: 없음

#### Delivery Trace Delta
- Batches:
  - BAT-008 (release-candidate) — 영향 없음(기존 구현/검증 그대로 유효)
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current (Implemented 유지)
- Follow-up Action: orb-v1 Discovery 착수 시 본 참고 사항을 입력으로 사용. 2번째 전략 도입 시 strategy_key/strategy_params 필요 → PortfolioItem 전략 필드 부재 해소(detail strategy_set 보강 또는 별도 change-req) 재검토.

#### Validation Plan
- 문서 전용 변경. 기존 AC-1~5 테스트 그대로 유효하며 재실행 불필요.