# req-028: 종목 스냅샷 read 메시지 계약 + envelope + degraded 신호

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

## Intent
- 전략 모듈이 dcy-006 snapshot RPC 로 종목 스냅샷을 받는 요청/응답 계약(transport-무관 logical)을 정의한다. 빈 응답과 가용성 degrade 의 시맨틱을 모호하지 않게 한다.

## Requirement
- 스냅샷 read 는 dcy-006 의 `trex.snapshot.req` request-reply RPC 위에서 동작한다. 요청 payload 는 선택적 `strategy_key`·`view` 를 가진다.
- 응답은 **envelope** 다: `assets` 는 항상 배열(비면 `[]`, null 금지)이고, meta 로 `view`(에코), `available_slots`, `degraded`, `reason` 을 포함한다.
- 각 자산 항목은 symbol, asset_id, cash_balance, asset_quantity, active_strategy_id, 전략파라미터(opaque)를 담고 가격은 제외한다.
- portfolio-hub 가 불가해 권위 cash/position 을 유지할 수 없으면(write `*_after` 갱신 불가 또는 일일 fetch 실패) 응답에 `degraded=true` + machine-readable reason code(예: `portfolio_hub_unavailable`/`snapshot_fetch_failed`/`cash_position_stale`) + sanitize 된 message 를 실어 전략의 신규 매매 보류를 신호한다(빈 리스트/silent stale 금지).

## Acceptance Criteria
1. Given 정상 상태, When 스냅샷을 요청, Then `assets`(배열) + meta(`view`·`available_slots`·`degraded`·`reason`) envelope 를 반환하고, 자산이 없어도 `assets` 는 `[]`(null 아님)다.
2. Given portfolio-hub 불가(권위 cash/position 유지 불가), When 요청, Then `degraded=true` + reason code 가 포함되고 raw 예외/자격증명 등 민감정보는 노출되지 않는다.
3. Given 응답 항목, Then 필드는 symbol/asset_id/cash_balance/asset_quantity/active_strategy_id/strategy_params(opaque) 이고 가격 필드는 없다.

## Impacted Area
- Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md, docs/interface-contract.md
- Modules: trex_core/adapters/messaging (snapshot RPC 핸들러), 응답 스키마(transport-무관)
- Tests: envelope 스키마 검증(빈 응답 포함), degraded 주입 테스트

## Notes
- transport 는 dcy-006(REQ-021/022) 의 snapshot RPC 를 사용하며 본 REQ 는 logical 계약만 정의한다.
- NFR-3(가용성 degrade, OQ-5) + OQ-6(빈 표현)을 본 REQ 로 흡수/반영한다.
- 정확한 reason code enum/필드 스키마는 구현 단계에서 확정한다(dcy-005 OQ-5/OQ-6 결정 범위 내).

## Change Log

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

#### Change Summary
- dcy-005 FR-1/FR-3 + OQ-5/OQ-6 분해로 최초 생성(Proposed). NFR-3 흡수.

#### Intent
- 스냅샷 read 의 요청/응답 envelope 계약 + degrade 신호 정의.

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

#### Impacted Area Delta
- Docs:
  - dcy-005, interface-contract
- Modules:
  - adapters/messaging snapshot RPC 핸들러, 응답 스키마
- Tests:
  - envelope 스키마, degraded 주입

#### 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
- envelope 스키마 검증 + portfolio-hub 불가 주입으로 degraded 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
- snapshot RPC envelope 응답 + degraded 신호 + sanitization 구현 완료 상태로 동기화.

#### 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_handler.py::test_envelope_shape_returned + test_snapshot_selection.py::test_empty_envelope_assets_is_list_not_null.
- AC-2: tests/application/test_snapshot_handler.py::test_degraded_signal_does_not_leak_credentials + 실 daemon 운영 검증.
- AC-3: tests/application/test_snapshot_selection.py::test_envelope_shape_no_price_field.