# 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` 는 인프라 게이트로 검증.