trex-core/docs/srs/Integration/req-030_daily-snapshot-scheduler-and-option-d-cash-position.md

req-030: 일일 스냅샷 스케줄러 + 옵션 D 현금/포지션 갱신

• Status: Implemented
• Type: Integration
• Priority: High
• Owner: project maintainers

Intent

• universe 멤버십·전략파라미터는 일일 스냅샷으로 고정하고, 현금/포지션은 portfolio-hub 가 ledger write 응답으로 돌려주는 권위 값으로 유지해 로컬 누적 보정 drift 를 제거한다(옵션 D).

Requirement

• 설정 가능한 시각(기본 07:30 KST, .env)에 스케줄러(신규 daemon 컴포넌트)가 daemon_id universe 를 페치해 스냅샷을 갱신한다. universe 멤버십·전략파라미터는 그 일일 스냅샷으로 고정한다.
• 현금/포지션은 스냅샷 baseline 에 더해, 체결 시 portfolio-hub ledger write 응답의 cash_balance_after / asset_quantity_after 권위 값으로 해당 자산을 갱신한다.

Acceptance Criteria

1. Given 설정 시각 도래, When 스케줄러 tick, Then universe 를 페치해 스냅샷(멤버십·전략파라미터·baseline 현금/포지션)을 갱신한다.
2. Given 체결 후 ledger write 응답이 *_after 를 반환, When 처리, Then 해당 자산의 현금/포지션을 그 권위 값으로 갱신한다.
3. Given duplicate write 응답(idempotent), When 처리, Then 현재 권위 *_after 값으로 동일하게 갱신한다.

Impacted Area

• Docs: docs/discovery/dcy-005_20260604_portfolio-hub-asset-snapshot-api.md, docs/runtime-flows.md
• Modules: 일일 스냅샷 스케줄러(런타임 신규), ledger write 응답 소비/스냅샷 갱신 로직, config(스냅샷 페치 시각)
• Tests: 스케줄 tick 페치, *_after 갱신, duplicate idempotent 갱신

Notes

• 의존: portfolio-hub#8 — ledger write 응답에 cash_balance_after/asset_quantity_after 반환(회계 단일 트랜잭션). portfolio-hub 배포(REL-003 등) 전까지 본 REQ 의 옵션 D 갱신 구현은 대기(dcy-005 A-7). 그 전까지는 baseline + 스케줄러 페치까지만 선구현 가능.
• A-6(유일 매매 주체·장중 외부 변동 없음) 전제.
• NFR-2(일관성)를 본 REQ 로 흡수한다.

Change Log

CHG-20260606-01

• Date: 2026-06-06
• Author: project maintainers

Change Summary

• dcy-005 FR-6 + OQ-2 분해로 최초 생성(Proposed). NFR-2 흡수.

Intent

• 일일 스냅샷 스케줄러 + 옵션 D 현금/포지션 갱신 정의.

Acceptance Criteria Delta

• Added:
  • AC-1~3 신규
• Updated:
  • none
• Removed:
  • none

Impacted Area Delta

• Docs:
  • dcy-005, runtime-flows
• Modules:
  • 스냅샷 스케줄러, write 응답 소비 로직, config
• Tests:
  • 스케줄 tick, *_after 갱신

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: portfolio-hub#8 배포 추적 후 옵션 D 구현 착수

Validation Plan

• 스케줄 tick 페치 + *_after 갱신/idempotent 갱신 테스트로 AC 검증.

CHG-20260606-02

• Date: 2026-06-06
• Author: project maintainers

Change Summary

• 승인 게이트 통과 → Proposed → Approved. 옵션 D 구현은 portfolio-hub#8 배포 후 착수(Notes 의존 유지, 비블로커).

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; 옵션 D 구현은 portfolio-hub#8 배포 트래킹 후

Validation Plan

• 승인 기록. 스케줄러 baseline 구현 → portfolio-hub#8 배포 후 옵션 D 갱신 통합 검증.

CHG-20260606-03

• Date: 2026-06-06
• Author: Justin Ko

Change Summary

• Status 유지: Approved. BAT-008 에서 AC-1(일일 스냅샷 스케줄러 baseline)은 구현 완료 + evidence 확보, AC-2/AC-3(옵션 D *_after 갱신)은 외부 의존(portfolio-hub#8) 배포 대기로 deferred. 본 REQ 는 AC 일부 충족이므로 Implemented 전환을 보류한다(SRS Status Transition Evidence 의 "미충족 Acceptance Criteria 가 있으면 Implemented 로 전환하지 않는다" 규정 준수).

Intent

• 스케줄러 baseline 부분 구현 완료를 추적 + 옵션 D 후속 작업의 wiring point 가 노출되어 있음을 기록.

Acceptance Criteria Delta

• Added/Updated/Removed: 없음

Impacted Area Delta

• Docs/Modules/Tests: 없음 (AC-1 baseline 은 BAT-008 에서 구현 + 검증 완료, AC-2/AC-3 wiring point 노출만 추가)

Delivery Trace Delta

• Batches:
  • BAT-008 (release-candidate; AC-1 evidence)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: yes (portfolio-hub#8 배포 후 AC-2/AC-3 통합 검증)
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current (Approved 유지)
• Follow-up Action: portfolio-hub#8 배포 완료 알림 수신 시 별도 minor-change batch 로 옵션 D 구현 (LedgerWriter 의 ledger write 응답 소비 경로에서 cash_balance_after/asset_quantity_after → SnapshotStore.update_cash_position(...) 호출 1줄 추가) + AC-2/AC-3 통합 evidence 확보 → REQ-030 Approved → Implemented 전환.

Validation Plan

• AC-1 (현재 완료): tests/application/test_snapshot_scheduler.py::test_run_once_fetches_universe_and_swaps_store + ::test_swap_preserves_warning_for_carried_over_portfolio + 실 daemon boot 후 첫 fetch 동작 확인.
• AC-2 (deferred): portfolio-hub#8 배포 후 ledger write 응답 소비 경로에 wiring 연결 + integration 테스트.
• AC-3 (deferred): duplicate write 응답 idempotent 갱신 테스트.

Notes

• BAT-008 verification.md Human Approval Memo 에 deferred residual risk 로 명시되어 있고, batch 전체는 release-candidate 로 promote 됨.

CHG-20260608-01

• Date: 2026-06-08
• Author: Justin Ko

Change Summary

• (change-req, dcy-018) Status Approved → Implemented. 연기됐던 option D(AC-2/AC-3: ledger write 응답 *_after 로 현금/포지션 갱신)를 portfolio-hub#8 배포·동작 확인 후 실제 구현. LedgerWriter 가 *_after 를 SnapshotStore.update_cash_position 으로 write-back(REQ-019), 어댑터가 *_after 파싱(REQ-017). REQ-030 Change Log Follow-up(CHG-20260606-03 "portfolio-hub#8 배포 후 minor-change 로 option D 구현") 예고대로 닫음.

Intent

• option D 현금/포지션 갱신을 실제 활성화해 AC-2/AC-3 충족 → Approved→Implemented 전환.

Acceptance Criteria Delta

• (변경 없음 — AC-2/AC-3 의 deferred 해소; ledger write 응답 *_after 소비 경로 구현)

Impacted Area Delta

• Modules: trex_core/application/ledger_outbox.py(write-back), trex_core/adapters/ledger/portfolio_hub.py(*_after 파싱), trex_core/runtime/daemon.py(SnapshotStore 배선)
• Tests: tests/application/test_ledger_option_d.py

Delivery Trace Delta

• Batches: BAT-023
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-023 에서 AC-2/AC-3 통합 검증)
• Existing Implementation Invalidated: no (AC-1 baseline 불변, deferred AC 구현)
• Status Recommendation: Implemented (option D 활성화 완료)
• Follow-up Action: confirm-req-implemented(BAT-023) 로 Approved→Implemented 동기화.

Validation Plan

• BAT-023: ledger write *_after → SnapshotStore 갱신 단위 + 실 데몬 e2e(option D).