Files

T

genichin ca757009f5 feat: add portfolio snapshot read layer

2026-06-06 09:33:00 +09:00

5.0 KiB

Raw Blame History

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

Given 정상 상태, When 스냅샷을 요청, Then assets(배열) + meta(view·available_slots·degraded·reason) envelope 를 반환하고, 자산이 없어도 assets 는 [](null 아님)다.
Given portfolio-hub 불가(권위 cash/position 유지 불가), When 요청, Then degraded=true + reason code 가 포함되고 raw 예외/자격증명 등 민감정보는 노출되지 않는다.
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.