Implement BAT-006: portfolio-hub ledger integration (REQ-017~019)

- REQ-017: LedgerPort contract (application/ledger_port.py) + portfolio-hub adapter + in-memory stub (adapters/ledger/), TREX_PORTFOLIO_HUB_* config - REQ-018: fill→ledger recording in execution loop; FillStatus carries execution_id (deterministic synth) + fee; paper/kis adapters updated - REQ-019: ledger outbox + retry worker (application/ledger_outbox.py), correlation_id idempotency, outcome vocabulary; 002_create_ledger_outbox.sql - Tests: in-memory/portfolio-hub ledger, execution ledger hook, outbox, domain import sweep Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-04 22:57:31 +09:00
parent 6277d610ea
commit 13837acc60
20 changed files with 1224 additions and 15 deletions
@@ -17,6 +17,12 @@ from datetime import date, datetime, timezone
 from typing import Any, Iterator, Optional
 from uuid import UUID, uuid4

+from trex_core.application.ledger_outbox import (
+    LedgerWorkItem,
+    OutboxOutcome,
+    WorkItemStatus,
+)
+from trex_core.application.ledger_port import LedgerTrade
 from trex_core.application.ports import IntentRecord
 from trex_core.domain.slot import Slot, SlotNotFoundError, SlotState, SlotTransitionRecord

@@ -300,3 +306,115 @@ class _PgIntentRecord:
        self.status = status
        self.slot_id = slot_id
        self.reason = reason
+
+
+# --- ledger outbox (BAT-006 / REQ-019) ---------------------------------------
+
+_OUTBOX_COLUMNS = (
+    "correlation_id, asset_id, order_id, execution_id, side, qty, price, "
+    "fee, tax, executed_at, status, attempts, last_outcome, last_error, "
+    "created_at, updated_at"
+)
+
+
+class PostgreSQLLedgerOutbox:
+    """ledger_outbox-backed LedgerOutbox. correlation_id PK is the dedup gate."""
+
+    def __init__(self, dsn: str, *, psycopg_module: Any = None) -> None:
+        self._psycopg = _require_psycopg(psycopg_module)
+        self._dsn = dsn
+
+    def enqueue(self, trade: LedgerTrade) -> LedgerWorkItem:
+        with self._psycopg.connect(self._dsn, autocommit=False) as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "INSERT INTO ledger_outbox "
+                    "(correlation_id, asset_id, order_id, execution_id, side, "
+                    " qty, price, fee, tax, executed_at) "
+                    "VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s) "
+                    "ON CONFLICT (correlation_id) DO NOTHING",
+                    (
+                        trade.correlation_id, trade.asset_id, trade.order_id,
+                        trade.execution_id, trade.side,
+                        trade.qty, trade.price, trade.fee, trade.tax,
+                        trade.executed_at,
+                    ),
+                )
+                conn.commit()
+        existing = self.get(trade.correlation_id)
+        assert existing is not None
+        return existing
+
+    def list_pending(self, limit: int = 32) -> list[LedgerWorkItem]:
+        with self._psycopg.connect(self._dsn) as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    f"SELECT {_OUTBOX_COLUMNS} FROM ledger_outbox "
+                    "WHERE status = 'pending' ORDER BY created_at LIMIT %s",
+                    (limit,),
+                )
+                return [self._row_to_item(r) for r in cur.fetchall()]
+
+    def get(self, correlation_id: str) -> Optional[LedgerWorkItem]:
+        with self._psycopg.connect(self._dsn) as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    f"SELECT {_OUTBOX_COLUMNS} FROM ledger_outbox WHERE correlation_id = %s",
+                    (correlation_id,),
+                )
+                row = cur.fetchone()
+                return self._row_to_item(row) if row else None
+
+    def mark_outcome(
+        self,
+        correlation_id: str,
+        outcome: OutboxOutcome,
+        *,
+        error: Optional[str] = None,
+    ) -> LedgerWorkItem:
+        with self._psycopg.connect(self._dsn, autocommit=False) as conn:
+            with conn.cursor() as cur:
+                if outcome is OutboxOutcome.COMPLETED:
+                    status_value = WorkItemStatus.COMPLETED.value
+                    attempts_delta = 1
+                elif outcome is OutboxOutcome.CONFLICT_BLOCKED:
+                    status_value = WorkItemStatus.CONFLICT_BLOCKED.value
+                    attempts_delta = 1
+                elif outcome is OutboxOutcome.DUPLICATE_COMPLETED:
+                    status_value = WorkItemStatus.COMPLETED.value
+                    attempts_delta = 0
+                else:  # retryable
+                    status_value = WorkItemStatus.PENDING.value
+                    attempts_delta = 1
+                cur.execute(
+                    "UPDATE ledger_outbox SET status=%s, attempts=attempts+%s, "
+                    "last_outcome=%s, last_error=%s, updated_at=%s "
+                    "WHERE correlation_id=%s",
+                    (
+                        status_value, attempts_delta, outcome.value, error,
+                        datetime.now(tz=timezone.utc), correlation_id,
+                    ),
+                )
+                conn.commit()
+        row = self.get(correlation_id)
+        assert row is not None
+        return row
+
+    @staticmethod
+    def _row_to_item(row: tuple) -> LedgerWorkItem:
+        f = lambda v: float(v) if v is not None else 0.0  # noqa: E731
+        trade = LedgerTrade(
+            asset_id=row[1], order_id=row[2], execution_id=row[3], side=row[4],
+            qty=f(row[5]), price=f(row[6]), fee=f(row[7]), tax=f(row[8]),
+            executed_at=row[9],
+        )
+        return LedgerWorkItem(
+            correlation_id=row[0],
+            trade=trade,
+            status=WorkItemStatus(row[10]),
+            attempts=int(row[11]) if row[11] is not None else 0,
+            last_outcome=OutboxOutcome(row[12]) if row[12] else None,
+            last_error=row[13],
+            created_at=row[14],
+            updated_at=row[15],
+        )
@@ -0,0 +1,33 @@
+-- BAT-006 / REQ-019: ledger outbox work-item store (dcy-004 OQ-2).
+--
+-- Each row is one fill that needs to be recorded in the portfolio-hub
+-- ledger. `correlation_id` ({asset_id}:{order_id}:{execution_id}) is the
+-- local dedup key — the same fill enqueued twice must NOT produce two
+-- ledger entries. Outcomes are classified per dcy-004 FR-4:
+--   completed | duplicate_completed | retryable_failure | conflict_blocked.
+
+CREATE TABLE IF NOT EXISTS ledger_outbox (
+    correlation_id   TEXT PRIMARY KEY,
+    asset_id         TEXT NOT NULL,
+    order_id         TEXT NOT NULL,
+    execution_id     TEXT NOT NULL,
+    side             TEXT NOT NULL CHECK (side IN ('buy','sell')),
+    qty              NUMERIC(18, 4) NOT NULL,
+    price            NUMERIC(18, 4) NOT NULL,
+    fee              NUMERIC(18, 4) NOT NULL DEFAULT 0,
+    tax              NUMERIC(18, 4) NOT NULL DEFAULT 0,
+    executed_at      TIMESTAMPTZ,
+    status           TEXT NOT NULL DEFAULT 'pending'
+        CHECK (status IN ('pending','completed','conflict_blocked')),
+    attempts         INTEGER NOT NULL DEFAULT 0,
+    last_outcome     TEXT
+        CHECK (last_outcome IS NULL OR last_outcome IN (
+            'completed','duplicate_completed','retryable_failure','conflict_blocked'
+        )),
+    last_error       TEXT,
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT (now() AT TIME ZONE 'UTC'),
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT (now() AT TIME ZONE 'UTC')
+);
+
+CREATE INDEX IF NOT EXISTS idx_ledger_outbox_status_created
+    ON ledger_outbox (status, created_at);