feat(ledger): dcy-018 option D cash/position write-back + 추정 현금 (BAT-023)

ledger write 응답의 portfolio-hub 권위 cash/quantity 를 스냅샷에 write-back 해 매수/매도 직후 "수량 live·현금 stale" 비대칭 제거(option D 활성화). portfolio-hub#8 (*_after 응답) 동작 중 확인으로 그간 deferred 됐던 REQ-030 을 닫음. 거버넌스: 전부 change-req (신규 REQ 없음, dcy-018 OQ-3 a). - REQ-017: record_trade → LedgerWriteOutcome{result, cash_balance_after, asset_quantity_after}. 어댑터가 응답 root flat *_after 파싱(new+duplicate, 누락 None) - REQ-019: LedgerWriter 에 SnapshotStore 주입 → new+duplicate write-back (best-effort, *_after 절대값이라 멱등). LedgerOutbox.pending_cash_delta() - REQ-029: 추정 현금 오버레이(_apply_cash_estimate, cash_estimated 라벨, OQ-4 i) + 슬롯 오버레이 유지(OQ-1 B). 미정산 outbox delta 기반, write-back 수렴 - REQ-030: option D 활성화 → Approved→Implemented best-effort 격리(NFR-1): write-back/추정 실패가 ledger 멱등·청산 무차단. 배치 번호: 동시 커밋된 BAT-022(slot-state, dcy-016)와 충돌해 BAT-023 으로 배정. 검증: 단위 350 passed/35 skipped, 인프라 게이트(PG+RabbitMQ) 385 passed, ruff clean. 신규 test_ledger_option_d + adapter/PG 테스트. BAT-023 release-candidate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 21:50:56 +09:00
parent 63da87c9b3
commit 2bfecd59a8
26 changed files with 969 additions and 34 deletions
@@ -0,0 +1,42 @@
+# BAT-023 Design
+
+- Status: confirmed
+- Batch: BAT-023
+
+## 설계 목표
+- ledger write 응답의 portfolio-hub 권위 cash/quantity 를 스냅샷에 write-back 해 "수량 live·현금 stale" 비대칭을 제거(option D 활성화). 공백 구간은 추정 현금으로 메우되 안전·멱등·best-effort 를 보장.
+
+## 1. 응답 계약 확장 (REQ-017)
+- `LedgerWriteOutcome{result: LedgerWriteResult, cash_balance_after: Optional[float], asset_quantity_after: Optional[float]}` 신설. `record_trade` 반환 타입 변경.
+- `portfolio_hub.py`: 2xx 응답 root flat `cash_balance_after`/`asset_quantity_after` 파싱(`_opt_num`, 누락/형변환 실패 시 None). new(201)/duplicate(200) 모두. 409→Conflict, 404/400/422→Permanent(dcy-015) 예외 유지.
+- `in_memory.py`: `cash_after`/`quantity_after` 주입 파라미터 → outcome 에 실어 반환(테스트용).
+
+## 2. write-back (REQ-019/030, option D)
+- `LedgerWriter(snapshot_store=None)` 주입. `_process` 가 `new`·`duplicate` outcome 후 `_writeback(trade, outcome)` 호출.
+- `_writeback`: snapshot_store None 또는 `*_after` None 이면 skip. 아니면 `update_cash_position(trade.asset_id, cash_after, qty_after)`. **try/except 로 격리**(실패는 WARN, ledger outcome·청산 무차단, NFR-1).
+- duplicate 도 write-back(OQ-2 b): `*_after` 가 절대 권위값이라 멱등(중복 적용 위험 없음, NFR-3). 409/422 는 예외라 자연 skip.
+
+## 3. 추정 현금 오버레이 (REQ-029 / OQ-4)
+- source = **미정산 outbox delta**(슬롯 아님): 슬롯 기반이면 write-back 후에도 슬롯이 holding 이라 double-count. 미정산(pending) outbox 행은 정확히 "fill∼write-back 공백" 집합.
+- `trade_cash_delta(trade)`: buy → -(qty*price + fee + tax), sell → +(qty*price - fee - tax)(코어 근사).
+- `LedgerOutbox.pending_cash_delta() -> {asset_id: Σdelta}`(InMemory: pending 행 합 / PG: SQL SUM CASE). 백오프 무관 전체 pending.
+- `_apply_cash_estimate(payload, ledger_outbox)`(snapshot 핸들러): pending delta 있는 자산에 `cash_balance += delta` + `cash_estimated:true`. best-effort(예외 시 응답 불변).
+- write-back 완료 → 행이 pending 이탈 → delta 0 → 추정 사라지고 store 는 권위값. 자연 수렴, double-count 없음.
+
+## 4. 수량 source (REQ-029, OQ-1 B)
+- 슬롯 오버레이(`build_snapshot_envelope`) **변경 없음** — lifecycle 중 슬롯이 코어 권위 즉시값(불변식 A). write-back 은 현금 + 슬롯 밖 base 수량을 신선화. 슬롯↔write-back 불일치는 REQ-031 포지션 정합 경고로 노출(숨기지 않음).
+
+## 5. daemon 배선
+- 생성 순서: `SnapshotStore` 를 `LedgerWriter` 보다 먼저 생성(write-back target).
+- `LedgerWriter(snapshot_store=self.snapshot_store)`, snapshot 핸들러 `ledger_outbox=self.outbox`.
+
+## 6. baseline 문서 (REQ-030 정합 포함)
+- interface-contract: `LedgerWriteOutcome`/`*_after`/write-back/envelope `cash_estimated`.
+- runtime-flows: ledger writer write-back 단계 + snapshot 응답 추정 오버레이.
+- REQ-030 Status Approved→Implemented(파일 + srs/index register).
+
+## 테스트 설계
+- adapter: `*_after` 파싱(new/duplicate/누락).
+- writer: write-back new/duplicate/skip(None)/best-effort(store 예외)/store 미주입; pending_cash_delta 합; estimate overlay + write-back 후 수렴.
+- PG 게이트: `pending_cash_delta` SQL.
+- 회귀: record_trade 반환 타입 변경에 따른 기존 ledger 테스트(outcome.result) 정합 — 기존 테스트 더블/소비처 전환.
@@ -0,0 +1,41 @@
+# BAT-023 Implementation
+
+- Status: completed
+- Batch: BAT-023
+
+## 구현 요약
+- dcy-018 option D 활성화(ledger write 응답 cash/quantity write-back) + 추정 현금 오버레이를 전부 change-req 로 구현(REQ-030 Approved→Implemented).
+
+## 변경 내역
+
+### REQ-017 — 응답 계약 확장
+- `trex_core/application/ledger_port.py`: `LedgerWriteOutcome{result, cash_balance_after?, asset_quantity_after?}` 신설; `record_trade` 반환 타입 → `LedgerWriteOutcome`.
+- `trex_core/adapters/ledger/portfolio_hub.py`: 2xx 응답 root flat `cash_balance_after`/`asset_quantity_after` 파싱(`_opt_num`, new+duplicate, 누락 None). 409/404/400/422 예외 유지.
+- `trex_core/adapters/ledger/in_memory.py`: `cash_after`/`quantity_after` 주입 + outcome 반환.
+
+### REQ-019/030 — write-back + 추정 source
+- `trex_core/application/ledger_outbox.py`: `LedgerWriter(snapshot_store=None)` + `_writeback`(new+duplicate, `*_after` None/no-store skip, try/except best-effort); `_process` 가 outcome.result 소비. `trade_cash_delta` + `LedgerOutbox.pending_cash_delta()`(InMemory pending 합).
+- `trex_core/adapters/persistence/postgresql.py`: `pending_cash_delta` SQL(SUM CASE by asset_id, status='pending').
+- `trex_core/runtime/daemon.py`: SnapshotStore 를 LedgerWriter 보다 먼저 생성 + `snapshot_store` 주입.
+
+### REQ-029 — 추정 오버레이 + 슬롯 오버레이 유지
+- `trex_core/application/messaging_handlers.py`: `_apply_cash_estimate(payload, ledger_outbox)` — 미정산 자산에 `cash_balance += pending delta` + `cash_estimated:true`(best-effort). snapshot 핸들러 `ledger_outbox` 파라미터. 슬롯 오버레이(`build_snapshot_envelope`)는 불변.
+- `trex_core/runtime/daemon.py`: snapshot 핸들러에 `ledger_outbox=self.outbox` 배선.
+
+### REQ-030 — Approved→Implemented
+- `docs/srs/Integration/req-030_*.md` Status Approved→Implemented + CHG-20260608-01; `docs/srs/index.md` register REQ-030 → Implemented.
+
+### 문서
+- `docs/interface-contract.md`: LedgerWriteOutcome/`*_after`/write-back/envelope `cash_estimated`. Last Updated → BAT-023.
+- `docs/runtime-flows.md`: ledger writer write-back 단계 + snapshot 추정 오버레이. Last Updated → BAT-023.
+
+## 테스트
+- `tests/adapters/ledger/test_portfolio_hub_ledger.py` 확장: `*_after` 파싱(new/duplicate/누락) 3건.
+- 신규 `tests/application/test_ledger_option_d.py`: write-back(new/duplicate/skip/best-effort/no-store) + pending_cash_delta + estimate overlay + write-back 후 수렴 (11건).
+- 신규 PG 게이트 `tests/adapters/persistence/test_postgresql_ledger_outbox.py::test_pending_cash_delta_on_pg`.
+- 회귀: `test_ledger_outbox_backoff.py` programmable ledger → LedgerWriteOutcome 반환 전환.
+
+## 검증 실행
+- 단위: `TREX_BROKER=paper .venv/bin/python -m pytest -q` → `350 passed / 35 skipped`(`::test_sandbox_token_and_submit` deselect — LIVE `.env` 환경 의존, 본 batch 무관).
+- 인프라 게이트: `TREX_POSTGRESQL_TEST_DSN=...(trex_core_test) TREX_RABBITMQ_TEST_URL=... pytest -q` → `385 passed`(pending_cash_delta SQL 포함).
+- `ruff check trex_core tests` → All checks passed.
@@ -0,0 +1,34 @@
+# BAT-023: ledger write 응답 cash/position write-back (option D 활성화) + 추정 현금 오버레이
+
+- Status: release-candidate
+- Profile: standard
+- Source Discovery: dcy-018
+- Included REQ: REQ-017 (CHG-20260608-02), REQ-019 (CHG-20260608-02), REQ-029 (CHG-20260608-01), REQ-030 (CHG-20260608-01, Approved→Implemented)
+
+## Summary
+- dcy-018(ledger write 응답의 cash/quantity 를 portfolio 스냅샷에 write-back — option D 활성화 + 수량 source 통일, 운영 환류)을 단일 standard batch 로 delivery 한다. 거버넌스는 dcy-018 OQ-3 대로 **전부 change-req, 신규 REQ 없음**(REQ-030 은 Approved→Implemented).
+- 핵심: portfolio-hub#8(배포·동작 중)의 ledger write 응답 root flat `cash_balance_after`/`asset_quantity_after`(절대 권위값)를 어댑터가 파싱(REQ-017) → `LedgerWriter` 가 `new`·`duplicate` 에 `SnapshotStore.update_cash_position` write-back(REQ-019/030, best-effort). "수량 live·현금 stale" 비대칭 제거. 체결~write-back 공백은 미정산 outbox delta 기반 **추정 현금 오버레이**(`cash_estimated` 라벨, REQ-029/OQ-4)로 메우고 권위값 도착 시 수렴.
+
+## Scope
+- In Scope:
+  - `record_trade` → `LedgerWriteOutcome{result, *_after}` + 어댑터 `*_after` 파싱(new+duplicate, 누락 None) (REQ-017)
+  - `LedgerWriter` SnapshotStore write-back(new+duplicate, best-effort) + `pending_cash_delta` (REQ-019)
+  - 추정 현금 오버레이(`_apply_cash_estimate`, `cash_estimated` 플래그) + 슬롯 오버레이 유지 (REQ-029, OQ-1 B/OQ-4 i)
+  - option D 활성화 → REQ-030 Approved→Implemented
+  - interface-contract/runtime-flows 정합
+- Out of Scope:
+  - portfolio-hub#8 자체(외부, 배포·동작 중)
+  - 일일 스냅샷 스케줄러 fetch 재설계(REQ-030 AC-1 유지)
+  - 슬롯 오버레이 제거(OQ-1 B 로 유지 확정)
+
+## Documents
+- Planning: [planning.md](./planning.md)
+- Design: [design.md](./design.md)
+- Implementation: [implementation.md](./implementation.md)
+- Verification: [verification.md](./verification.md)
+
+## Notes
+- Source discovery 단일(dcy-018). OQ-1 B / OQ-2 b(new+duplicate write-back) / OQ-3 a(change-req) / OQ-4 (i)(추정 오버레이) Answered. DATA(응답 스키마)=dcy-005 A-7 `*_after` + portfolio-hub#8 동작 중.
+- best-effort 격리(NFR-1): write-back·추정 모두 예외 격리, ledger 멱등(REQ-019)·청산 무차단.
+- 멱등(NFR-3): `*_after` 가 절대 권위값이라 duplicate write-back 도 중복 적용 위험 없음.
+- 추정(OQ-4)은 코어 근사 수수료라 "추정/미정산" 라벨 필수, 노출 구간은 outbox drain(~1s)으로 짧음.
@@ -0,0 +1,47 @@
+# BAT-023 Planning
+
+- Status: confirmed
+- Batch: BAT-023
+- Profile: standard
+
+## Included REQ
+- REQ-017 (Integration, change-req): `record_trade`→`LedgerWriteOutcome` + 어댑터 `*_after` 파싱.
+- REQ-019 (Exception, change-req): `LedgerWriter` write-back + `pending_cash_delta` + SnapshotStore 주입.
+- REQ-029 (Interface, change-req): 추정 현금 오버레이 + 슬롯 오버레이 유지.
+- REQ-030 (Integration, change-req): option D 활성화 → Approved→Implemented.
+
+## Delivery Plan
+1. REQ-017: `ledger_port.py` `LedgerWriteOutcome`; `portfolio_hub.py` `*_after` 파싱(new+duplicate); `in_memory.py` outcome 반환 + cash/qty 주입.
+2. REQ-019/030: `ledger_outbox.py` LedgerWriter `snapshot_store` 주입 + `_writeback`(new+duplicate, best-effort) + `trade_cash_delta`/`pending_cash_delta`; `postgresql.py` `pending_cash_delta` SQL; daemon SnapshotStore 배선(생성 순서 조정).
+3. REQ-029: `messaging_handlers.py` `_apply_cash_estimate`(snapshot 핸들러, ledger_outbox 주입); 슬롯 오버레이 불변; daemon ledger_outbox 배선.
+4. 문서: interface-contract(LedgerWriteOutcome·*_after·cash_estimated)/runtime-flows(write-back·추정 flow). REQ-030 Status Approved→Implemented(파일+register).
+5. 테스트 + 전체 회귀 + ruff + 인프라 게이트(PG pending_cash_delta).
+
+## Dependencies
+- Internal:
+  - dcy-004/BAT-006 LedgerPort/outbox/writer(REQ-017/019) — 변경 대상.
+  - dcy-005/BAT-008 SnapshotStore/update_cash_position/envelope(REQ-029/030) — write-back sink + 오버레이.
+- External:
+  - portfolio-hub#8 ledger write 응답 `*_after`(배포·동작 중, dcy-005 A-7).
+
+## Design Gate
+- Design Required Before Implementation: yes
+- Reason: (a) `record_trade` 반환 타입 변경(LedgerWriteResult→LedgerWriteOutcome)은 LedgerPort·두 어댑터·LedgerWriter·테스트 더블에 교차 — 계약 확장 경계를 설계에서 고정. (b) write-back best-effort 격리(실패가 ledger 멱등·청산 무차단)와 멱등(절대 *_after, duplicate 안전) 규칙을 못박아야 안전. (c) 추정 현금 source = 미정산 outbox delta(슬롯 아님 — 청산 후 double-count 방지) + 슬롯 오버레이 유지 경계 + daemon 생성 순서(SnapshotStore before LedgerWriter). → design.md 동일 턴 scaffold.
+
+## Milestones
+1. M1 — REQ-017 LedgerWriteOutcome + 어댑터 파싱, adapter 테스트 green
+2. M2 — REQ-019/030 write-back + pending_cash_delta, option D 테스트 green
+3. M3 — REQ-029 추정 오버레이 + daemon 배선
+4. M4 — 문서 정합 + REQ-030 Implemented 전환
+5. M5 — 전체 회귀 + ruff + 인프라 게이트
+
+## Risks
+- R-1 (High→완화): write-back/추정이 ledger·청산을 막음. 대응: best-effort 예외 격리(NFR-1), write 성공 이후 분리 수행. source of truth(outbox 멱등) 불변.
+- R-2 (해소): 응답 스키마 미확정. 대응: `*_after` dcy-005 A-7 확정 + portfolio-hub#8 동작 중. 누락 시 None→skip.
+- R-3 (Low): 추정 부정확(근사 수수료). 대응: "추정/미정산" 라벨 + outbox drain(~1s) 짧은 구간 + write-back 수렴.
+- R-4 (Medium): duplicate 중복 적용. 대응: `*_after` 절대값이라 멱등(덮어쓰기).
+
+## Notes
+- 1차 게이트: 전체 회귀 green(record_trade 반환 타입 변경 호출부 전환 무누락).
+- 추정/write-back 결정론: InMemoryLedger(cash_after/quantity_after 주입) + InMemoryLedgerOutbox + SnapshotStore.
+- PG `pending_cash_delta` 는 인프라 게이트로 검증.
@@ -0,0 +1,59 @@
+# BAT-023 Verification
+
+- Status: verified
+- Batch: BAT-023
+
+## Acceptance Mapping
+
+### REQ-017 (응답 계약 확장, change-req)
+| AC | Evidence |
+|----|----------|
+| record_trade → LedgerWriteOutcome + `*_after`(new) | tests/adapters/ledger/test_portfolio_hub_ledger.py::test_outcome_parses_cash_quantity_after_on_new |
+| duplicate `*_after` | ::test_outcome_parses_after_on_duplicate |
+| 응답 누락 → None | ::test_outcome_after_none_when_response_omits |
+| 409/404/422 예외 회귀 | ::test_409_surfaces_as_ledger_conflict_error / ::test_client_errors_are_permanent |
+
+### REQ-019 (write-back + pending_cash_delta, change-req)
+| AC | Evidence |
+|----|----------|
+| new write-back | tests/application/test_ledger_option_d.py::test_writeback_updates_snapshot_on_new |
+| duplicate write-back(멱등) | ::test_writeback_applies_on_duplicate_too |
+| `*_after` 누락 시 skip | ::test_writeback_skipped_when_after_missing |
+| best-effort(store 예외 무차단) | ::test_writeback_best_effort_does_not_block_completion |
+| store 미주입 무크래시 | ::test_no_writeback_without_store |
+| pending_cash_delta 합(InMemory/PG) | ::test_pending_cash_delta_sums_by_asset / test_postgresql_ledger_outbox.py::test_pending_cash_delta_on_pg |
+
+### REQ-029 (추정 오버레이 + 슬롯 오버레이 유지, change-req)
+| AC | Evidence |
+|----|----------|
+| 미정산 자산 추정 cash + cash_estimated | tests/application/test_ledger_option_d.py::test_apply_cash_estimate_overlays_pending_delta |
+| write-back 후 수렴(추정 제거) | ::test_estimate_clears_after_writeback |
+| 슬롯 오버레이 불변 회귀 | tests/application/test_messaging_snapshot_consumer.py 전체 |
+
+### REQ-030 (option D Approved→Implemented, change-req)
+| AC | Evidence |
+|----|----------|
+| AC-2/AC-3 deferred 해소(ledger write `*_after` → SnapshotStore) | test_ledger_option_d.py(write-back 전반) + REQ-017/019 evidence |
+| AC-1 baseline 스케줄러 회귀 | tests/application/test_preallocation_scheduler.py + snapshot scheduler 회귀 |
+
+## Evidence
+- Test:
+  - 단위 전체 회귀: `350 passed / 35 skipped`(신규 option D 11 + adapter 3 포함; `::test_sandbox_token_and_submit` deselect).
+  - 인프라 게이트(PG trex_core_test + RabbitMQ): `385 passed`(pending_cash_delta SQL 포함).
+  - `ruff check trex_core tests` → All checks passed.
+- Logs: `350 passed, 35 skipped, 1 deselected` / `385 passed, 1 deselected ~17.9s`.
+
+## 성공 기준(dcy-018) 대응
+- S-1(매수/매도 후 cash+quantity 모두 권위값 갱신): test_writeback_updates_snapshot_on_new(+duplicate). 수량은 슬롯 오버레이(유지) + write-back base 신선화.
+- S-2(portfolio-hub 응답 누락/불가 시 skip + ledger 정상): test_writeback_skipped_when_after_missing + test_writeback_best_effort_does_not_block_completion.
+- S-3(DUPLICATE 중복 적용 없음): test_writeback_applies_on_duplicate_too(절대 권위값 멱등).
+- (OQ-4) 추정 현금: test_apply_cash_estimate_overlays_pending_delta + test_estimate_clears_after_writeback.
+
+## Carried-Over / 비차단
+- 실 데몬 + portfolio-hub#8 full-stack option D e2e(실 `*_after` 응답 → 스냅샷 갱신)는 운영 배포 검증(REL-005 등)에서 확인 — 단위는 InMemoryLedger `*_after` 주입 + adapter 파싱으로 커버.
+- 추정 현금은 코어 근사 수수료 기반 — "추정/미정산" 라벨로 커버, write-back 수렴(짧은 구간).
+
+## Result
+- Ready for Release: true
+- Blocking Issues:
+  - 없음. option D write-back·추정 오버레이·REQ-030 전환 모두 단위 green(385 passed 회귀, record_trade 반환 타입 변경 호출부 전환 무누락). LIVE/실 portfolio-hub#8 full-stack 은 운영 배포 검증 비차단.
@@ -30,3 +30,4 @@
 | BAT-020 | standard | release-candidate | REQ-032 (CHG-20260608-01), REQ-022 (CHG-20260608-01), REQ-021 (CHG-20260608-02), REQ-034 (CHG-20260608-01), REQ-026 (CHG-20260608-01) | dcy-016 | [bat-020](./bat-020_20260608_operator-cli-rpc-commands/) |
 | BAT-021 | standard | release-candidate | REQ-034 (CHG-20260608-02), REQ-021 (CHG-20260608-03), REQ-037 (CHG-20260608-01), REQ-038 (CHG-20260608-01), REQ-039 (CHG-20260608-01), REQ-032 (CHG-20260608-02), REQ-042 (CHG-20260608-01) | dcy-017 | [bat-021](./bat-021_20260608_watchdog-ownership-visibility/) |
 | BAT-022 | standard | release-candidate | REQ-028 (CHG-20260608-01), REQ-032 (CHG-20260608-03) | dcy-016 | [bat-022](./bat-022_20260608_slot-state-snapshot-visibility/) |
+| BAT-023 | standard | release-candidate | REQ-017 (CHG-20260608-02), REQ-019 (CHG-20260608-02), REQ-029 (CHG-20260608-01), REQ-030 (CHG-20260608-01, Approved→Implemented) | dcy-018 | [bat-023](./bat-023_20260608_ledger-cash-position-writeback-option-d/) |