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
@@ -4,7 +4,7 @@
 - Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
 - Status: draft
 - Owner: project maintainers
- Last Updated (KST): 2026-06-05 (BAT-007)
+- Last Updated (KST): 2026-06-06 (BAT-008)
 - Source Discovery / Batch: bootstrap-baseline (pre-Discovery, 3-phase lifecycle 밖의 bootstrap 산출물)

 ## Project Summary
@@ -23,10 +23,12 @@
 ## Primary Runtime
 - Type: daemon (sync + thread, no HTTP) + library (slot 도메인)
 - Entry Points:
-  - `trex-core-daemon` (console_script → `trex_core.runtime.daemon:main`) :: 슬롯 코어 데몬 — migrate+preallocate+reconcile 후 4 백그라운드 스레드(intent RPC consumer / snapshot RPC consumer / execution / ledger) 기동, RabbitMQ messaging 으로 전략 모듈과 통신 (BAT-002 + BAT-007)
-  - RabbitMQ `trex.snapshot.req` / `trex.intent.req` / `trex.events` :: 매수·매도 전략 데몬과의 transport (docs/interface-contract.md)
+  - `trex-core-daemon` (console_script → `trex_core.runtime.daemon:main`) :: 슬롯 코어 데몬 — migrate+preallocate+reconcile 후 6 백그라운드 스레드(intent RPC consumer / snapshot RPC consumer / pause RPC consumer / snapshot scheduler / execution / ledger) 기동, RabbitMQ messaging 으로 전략 모듈과 통신 (BAT-002 + BAT-007 + BAT-008)
+  - `trex-core` (console_script → `trex_core.runtime.cli:main`) :: 운영 CLI (`pause` / `resume` / `paused`) (BAT-008)
+  - RabbitMQ `trex.snapshot.req` / `trex.intent.req` / `trex.pause.req` / `trex.events` :: 매수·매도 전략 데몬과의 transport (docs/interface-contract.md)
  - SlotService / SlotRepository (Protocol) :: in-process 도메인 서비스 + 저장소 경계(라이브러리 사용)
  - MessagingTransport (Protocol) :: transport 추상화 (RabbitMQ / InMemory stub)
+  - PortfolioHubReadPort (Protocol) :: portfolio-hub universe read 경계 (BAT-008)

 ## Purpose
 - This document is the current approved repository and package structure baseline.
@@ -63,23 +65,28 @@
 │   ├── domain/slot/              # slot 순수 도메인 (BAT-001, 무의존)
 │   │   ├── __init__.py · state.py · models.py(+EXPECTED_SLOT_FIELDS) · errors.py
 │   │   ├── repository.py(Protocol) · service.py · in_memory_repository.py
-│   ├── application/              # 유스케이스 (BAT-002, BAT-004, BAT-006, BAT-007)
+│   ├── application/              # 유스케이스 (BAT-002, BAT-004, BAT-006, BAT-007, BAT-008)
 │   │   ├── ports.py              # IntentStore Protocol
 │   │   ├── intents.py            # IntentService / BuyIntent / SellIntent / IntentDecision
-│   │   ├── broker_port.py        # BrokerPort + OrderRequest/OrderAck/FillStatus + calculate_fee (BAT-004/BAT-006)
+│   │   ├── broker_port.py        # BrokerPort + OrderRequest/OrderAck/FillStatus + BalanceItem + calculate_fee (BAT-004/BAT-006/BAT-008)
 │   │   ├── execution.py          # ExecutionService (dispatch·poll·transition·reconcile + ledger enqueue + event emit hook)
 │   │   ├── ledger_port.py        # LedgerPort + LedgerTrade/LedgerWriteResult/예외 (BAT-006)
 │   │   ├── ledger_outbox.py      # LedgerOutbox Protocol + LedgerWriter + InMemoryLedgerOutbox (BAT-006)
 │   │   ├── messaging.py          # MessagingTransport Protocol + DTO + TransportHealth (BAT-007)
-│   │   └── messaging_handlers.py # intent/snapshot RPC handlers + slot event payload builder (BAT-007)
-│   ├── adapters/                 # 인프라 어댑터 (BAT-002, BAT-004, BAT-006, BAT-007)
-│   │   ├── broker/               # paper.py(결정적 async 더블) · kis.py(KIS Open API)  (BAT-004)
+│   │   ├── messaging_handlers.py # intent/snapshot/pause RPC handlers + slot event payload builder (BAT-007/BAT-008)
+│   │   ├── portfolio.py          # PortfolioHubReadPort + SnapshotStore + PauseStore + envelope builder (BAT-008)
+│   │   ├── reconciliation.py     # reconcile_positions (hub ↔ broker symbol-aggregate) (BAT-008)
+│   │   └── snapshot_scheduler.py # SnapshotScheduler — daily fetch + swap + reconcile (BAT-008)
+│   ├── adapters/                 # 인프라 어댑터 (BAT-002, BAT-004, BAT-006, BAT-007, BAT-008)
+│   │   ├── broker/               # paper.py(결정적 async 더블) · kis.py(KIS Open API + 잔고조회)  (BAT-004/BAT-008)
 │   │   ├── ledger/               # in_memory.py(stub) · portfolio_hub.py(HTTP 어댑터)  (BAT-006)
 │   │   ├── messaging/            # topology.py · in_memory.py(stub) · rabbitmq.py(pika 동기)  (BAT-007)
-│   │   └── persistence/          # postgresql.py(+PostgreSQLLedgerOutbox) · in_memory_intent_store.py · migrate.py · sql/(001_…, 002_create_ledger_outbox.sql)
-│   └── runtime/                  # 데몬 (BAT-002, BAT-004, BAT-006, BAT-007)
-│       ├── config.py             # DaemonConfig + KISConfig + PortfolioHubConfig + RabbitMQConfig (env)
-│       └── daemon.py             # Daemon class: setup(migrate/preallocate/reconcile/declare-topology) + 4 worker threads (execution·ledger·intent-rpc·snapshot-rpc) + graceful shutdown
+│   │   ├── portfolio/            # hub_read.py(HTTP) · stub_read.py(stub) · pause_store.py(Postgres) (BAT-008)
+│   │   └── persistence/          # postgresql.py(+PostgreSQLLedgerOutbox) · in_memory_intent_store.py · migrate.py · sql/(001_…, 002_create_ledger_outbox.sql, 003_create_snapshot_pause.sql)
+│   └── runtime/                  # 데몬 (BAT-002, BAT-004, BAT-006, BAT-007, BAT-008)
+│       ├── config.py             # DaemonConfig + KISConfig + PortfolioHubConfig + RabbitMQConfig + SnapshotScheduleConfig (env)
+│       ├── daemon.py             # Daemon class: setup(migrate/preallocate/reconcile/declare-topology) + 6 worker threads (execution·ledger·intent-rpc·snapshot-rpc·pause-rpc·snapshot-scheduler) + graceful shutdown
+│       └── cli.py                # trex-core CLI: pause/resume/paused subcommands (BAT-008 / REQ-032)
 └── tests/
    ├── domain/slot/              # test_state / test_service / test_contract
    ├── domain/                   # test_domain_import_sweep (NFR-1 가드, BAT-006/BAT-007)
@@ -135,3 +142,4 @@
 - 2026-06-04 :: BAT-004 — 브로커 집행 레이어 반영(BrokerPort/paper·KIS 어댑터, execution 루프, broker_order_id 실행큐·멱등, reconciliation) (REQ-011~015).
 - 2026-06-04 :: BAT-006 — ledger 레이어 추가(application LedgerPort/LedgerOutbox, adapters/ledger in_memory·portfolio_hub, persistence PostgreSQLLedgerOutbox + 002 마이그레이션, runtime ledger writer 루프, FillStatus 확장, NFR-1 import 스윕) (REQ-017~020).
 - 2026-06-05 :: BAT-007 — transport 전환(`adapters/api/` 제거, `application/messaging.py` + `application/messaging_handlers.py` 신설, `adapters/messaging/` 신설(topology/in_memory/rabbitmq), runtime/daemon 을 sync+thread 4 스레드 구조로 재구성, `RabbitMQConfig` + `TREX_RABBITMQ_URL` env, `TREX_API_HOST`/`TREX_API_PORT` 폐기, `fastapi`/`uvicorn` 의존 제거 + `pika` 도입, NFR-1 import 스윕에 pika/messaging 추가, HTTP 표면 0 회귀 가드) (REQ-021~026).
+- 2026-06-06 :: BAT-008 — portfolio-hub 스냅샷 read 레이어 추가(`application/portfolio.py` + `application/reconciliation.py` + `application/snapshot_scheduler.py` 신설, `adapters/portfolio/` 신설(hub_read/stub_read/pause_store), `BrokerPort.get_balance()` 확장 + paper/KIS 구현, `messaging_handlers` 에 snapshot envelope + pause RPC 추가, runtime/daemon 을 6 스레드로 확장(pause-rpc + snapshot-scheduler), `SnapshotScheduleConfig` + `TREX_SNAPSHOT_*` env, `runtime/cli.py` + `trex-core` 콘솔 스크립트, `003_create_snapshot_pause.sql` 마이그레이션, NFR-1 import 스윕 유지) (REQ-027~033; REQ-030 옵션 D 는 portfolio-hub#8 배포 후 별도 구현).