Files

T

genichin 996127f215 Preserve ledger venue provenance (#39 )

* feat: preserve ledger venue provenance

* fix: satisfy ledger test lint ratchet

* fix: advance image migration inventory

2026-09-19 19:30:32 +09:00

3.8 KiB

Raw Blame History

id, status, discovery, criteria

status

discovery

criteria

req-0009

approved

dcy-0009

create

update

retire

satisfy

ac-0039

ac-0040

ac-0041

ac-0032

ac-0034

ac-0035

ac-0037

Broker ledger venue provenance preservation

Objective

trex-core가 이미 durable하게 구분하는 actual execution venue와 original order-routing venue를 portfolio-hub의 broker ledger write·storage·read 경계까지 손실 없이 보존한다. Unknown actual venue와 SOR routing을 정상 조합으로 유지하고, 기존 client·historical/manual/corporate-action row·회계·조회 계약과 혼합 버전 배포의 하위호환성을 보장한다.

Scope

Broker ledger request에 optional nullable execution_venue와 order_venue를 추가한다.
execution_venue는 KRX, NXT, NULL만 허용하고 order_venue는 KRX, NXT, SOR, NULL만 허용한다.
portfolio_ledger에 두 nullable column과 같은 allowlist constraint를 additive migration으로 추가한다. 기존 row는 NULL로 유지한다.
Broker ledger insert·domain mapping·POST response와 unified GET broker item이 저장값을 추정·변환 없이 반환한다.
동일 (portfolio_id, order_id, execution_id) duplicate는 portfolio row lock에 더해 기존 ledger row를 FOR UPDATE로 선택한다. 같은 transaction에서 기존 economic payload를 먼저 비교해 불일치면 metadata 변경 없이 409로 중단한다. Economic payload가 같을 때 모든 venue의 non-null 충돌을 먼저 검사하고, 충돌이 없을 때만 NULL→non-null venue를 하나의 metadata-only update로 보강한다. Incoming NULL은 기존 non-null을 지우지 않는다.
Metadata-only duplicate 보강은 ledger row, portfolio cash·asset quantity·snapshot, WAC/PnL 또는 corporate-action state를 다시 적용하지 않는다.
기존 active AC-0032·AC-0034·AC-0035·AC-0037을 의미 변경 없이 satisfy하여 unified ordering/filter/cursor, canonical nullable representation, owner authorization, manual/corporate-action 및 joined ledger compatibility를 유지한다.
trex-core는 active AC-0019 아래 기존 LedgerTrade.venue를 execution_venue, LedgerTrade.order_venue를 order_venue로 HTTP payload에 전달한다. Core producer·domain·outbox schema는 변경하지 않는다.
실제 PostgreSQL migration·round-trip·concurrent duplicate와 core adapter payload/reload, 교차 저장소 201 new -> 200 duplicate -> GET /ledger contract를 검증한다.

Constraints

SOR는 order routing provenance이며 actual execution venue로 저장하거나 추론하지 않는다.
Unknown actual venue는 NULL로 보존하고 order_venue, 시간 또는 historical default에서 KRX/NXT를 추론하지 않는다.
기존 idempotency key와 기존 경제적 payload conflict 판정은 유지한다.
추가 request field는 optional이어야 하며 구버전 core/client payload가 계속 유효해야 한다.
Historical, manual, corporate-action row는 두 venue가 NULL이어도 유효해야 한다.
Hub-first, core-adapter-second 배포 순서를 문서화하되 production rollout은 수행하지 않는다.
Normative Design Documents: 없음. 이 REQ와 create AC-0039~AC-0041 및 satisfy 대상 active AC가 normative specification을 소유한다.

Non-Goals

broker_ordered_at, core_observed_filled_at 또는 다른 timestamp provenance.
trex-core LedgerTrade, producer, broker execution adapter, outbox table/schema 또는 routing policy 변경. PortfolioHubLedger HTTP ledger transport adapter의 기존 venue 직렬화는 Scope에 포함한다.
Historical venue 추정·backfill.
새로운 ledger detail endpoint 또는 idempotency key 변경.
Production migration·deployment·restart·실제 broker 주문.

3.8 KiB Raw Blame History