genichin
996127f215
* feat: preserve ledger venue provenance * fix: satisfy ledger test lint ratchet * fix: advance image migration inventory
54 lines
3.8 KiB
Markdown
54 lines
3.8 KiB
Markdown
---
|
|
id: "req-0009"
|
|
status: approved
|
|
discovery: "dcy-0009"
|
|
criteria:
|
|
create:
|
|
- "ac-0039"
|
|
- "ac-0040"
|
|
- "ac-0041"
|
|
update: []
|
|
retire: []
|
|
satisfy:
|
|
- "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 주문.
|