chore: commit current workspace changes

docs/data-model.md

@@ -4,7 +4,7 @@
 - Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
 - Status: draft
 - Owner: project maintainers
-- Last Updated (KST): 2026-06-03
+- Last Updated (KST): 2026-06-04 (BAT-006)
 - Source Discovery / Batch: bootstrap-baseline (pre-Discovery)
 
 ## Project Summary
@@ -14,7 +14,7 @@
 - 자동매매 일일 거래 슬롯 생명주기 도메인 (equity trading slot lifecycle)
 
 ## Primary Persistence Backend
-- PostgreSQL (BAT-002, REQ-006) — 코어 데몬의 durable 단일 writer. 도메인은 여전히 storage-agnostic(SlotRepository Protocol); in-memory 어댑터는 테스트용으로 잔존. 슬라이스 1 테이블: daily_slot / daily_symbol_entries / slot_transition_log / intent_log (daily_slot_archive·prune 은 범위 밖).
+- PostgreSQL (BAT-002, REQ-006; BAT-006 확장) — 코어 데몬의 durable 단일 writer. 도메인은 여전히 storage-agnostic(SlotRepository Protocol); in-memory 어댑터는 테스트용으로 잔존. 슬라이스 1 테이블: daily_slot / daily_symbol_entries / slot_transition_log / intent_log / ledger_outbox (daily_slot_archive·prune 은 범위 밖).
 
 ## Purpose
 - This document captures the approved cross-cutting data model baseline for the project.
@@ -105,6 +105,57 @@
 - `try_insert` 는 INSERT ... ON CONFLICT DO NOTHING(dedup 게이트). 중복 intent_id 는 재전이 없이 기존 decision 반환.
 - 완전 비동기 outbox(상태머신 + 소비 루프)로의 승격은 브로커 집행 Discovery 로 Deferred(이 테이블이 전구체).
 
+## Entity: `LedgerTrade` (BAT-006)
+
+- Purpose: portfolio-hub 원장에 기록되는 단일 체결 거래 데이터. application 경계 DTO(영속 엔티티 아님 — 영속 표현은 `ledger_outbox` 에서 운반).
+- Source of Truth: 어댑터 호출 시 in-memory; 영속 표현은 `ledger_outbox` 의 컬럼들.
+
+### Key Fields
+
+- asset_id :: str :: 외부 원장 path param (= 슬롯 `portfolio_id`, dcy-004 OQ-1)
+- order_id :: str :: 로컬 주문 식별자 (`broker_order_id`)
+- execution_id :: str :: 결정적 합성 (paper / KIS 규칙). 멱등 키.
+- side :: 'buy' | 'sell'
+- qty :: float
+- price :: float
+- fee :: float :: BrokerPort `calculate_fee(side, qty*price)`
+- tax :: float :: 기본 0(정밀 모델 후속)
+- executed_at :: datetime?
+- correlation_id (derived) :: `{asset_id}:{order_id}:{execution_id}`
+
+### State Rules
+
+- 동일 `execution_id` 재기록 시 ledger 어댑터/서버가 dedup 한다(`LedgerWriteResult.DUPLICATE_OK` 또는 server-side 멱등). 로컬에서는 outbox PK 가 dedup gate.
+
+## Entity: `ledger_outbox` (BAT-006)
+
+- Purpose: 체결 → portfolio-hub 원장 기록을 슬롯 전이와 분리해 무유실 + 멱등으로 처리하기 위한 durable work-item store(dcy-004 OQ-2, orbit `LedgerWriter` 패턴).
+- Source of Truth: `ledger_outbox` (PostgreSQL) / 테스트는 in-memory `InMemoryLedgerOutbox`
+- Lifecycle: pending → completed | conflict_blocked ; retryable_failure 는 status `pending` 유지(attempts++)
+
+### Key Fields
+
+- correlation_id :: TEXT PK :: `{asset_id}:{order_id}:{execution_id}` — 로컬 dedup 게이트
+- asset_id / order_id / execution_id :: TEXT
+- side :: TEXT CHECK ('buy','sell')
+- qty / price / fee / tax :: NUMERIC(18,4)
+- executed_at :: TIMESTAMPTZ?
+- status :: TEXT CHECK ('pending','completed','conflict_blocked')
+- attempts :: INTEGER :: 재시도 누적
+- last_outcome :: TEXT? CHECK ('completed','duplicate_completed','retryable_failure','conflict_blocked')
+- last_error :: TEXT?
+- created_at / updated_at :: TIMESTAMPTZ
+
+### State Rules
+
+- `enqueue` 는 `INSERT ... ON CONFLICT (correlation_id) DO NOTHING`(dedup 게이트). 동일 fill 이 다시 enqueue 되어도 새 행을 만들지 않는다.
+- writer 결과 매핑:
+  - NEW → outcome `completed`, status `completed`.
+  - DUPLICATE_OK 또는 로컬 dedup hit → outcome `duplicate_completed`, status `completed`.
+  - 409 → outcome `conflict_blocked`, status `conflict_blocked` (자동 재시도 중단, 운영자 해소).
+  - 5xx/network/timeout → outcome `retryable_failure`, status `pending` (다음 tick 재시도).
+- slot 전이는 outbox 적재와 분리되어 critical path 유지.
+
 ## Shared Consistency Rules
 
 - (trading_date, symbol) 재진입 카운트는 closed->idle 복구와 원자적으로 증가한다.
@@ -134,3 +185,4 @@
 - 2026-06-03 :: bootstrap-baseline 으로 초기 데이터 모델 baseline 생성(Slot + SlotTransitionRecord + 재진입 카운터).
 - 2026-06-03 :: BAT-002 — PostgreSQL 영속화 확정 + `intent_log` 엔티티 추가(REQ-006/007/009).
 - 2026-06-04 :: BAT-004 — 브로커 집행 레이어 반영(BrokerPort/paper·KIS 어댑터, execution 루프, broker_order_id 실행큐·멱등, reconciliation) (REQ-011~015).
+- 2026-06-04 :: BAT-006 — ledger 통합 데이터 모델 반영(LedgerTrade DTO + `ledger_outbox` 테이블/`correlation_id` 멱등/outcome 어휘, FillStatus.execution_id/fee/tax 운반) (REQ-017~020).