trex-core/docs/srs/Exception/req-019_ledger-outbox-durability-idempotency.md

req-019: ledger outbox durability + correlation_id 멱등

• Status: Approved
• Type: Exception
• Priority: High
• Owner: project maintainers

Intent

• portfolio-hub 일시 장애에도 원장 기록이 유실되거나 중복되지 않도록, 체결 시 원장 기록을 ledger outbox(work item)에 적재하고 재시도 루프가 portfolio-hub write 를 수행하며 correlation_id 로 멱등을 보장한다.

Requirement

• 체결 시 원장 기록을 ledger outbox(work item)에 적재하고, 재시도 루프가 portfolio-hub write 를 시도한다(trex-orbit LedgerWriter/recovery work item 패턴). 원장 기록은 슬롯 전이와 분리되어(전이 우선, 기록 eventually-consistent) 일시 장애에도 유실 없이 결국 기록된다.
• 멱등 키 correlation_id = {asset_id}:{order_id}:{execution_id} 로 로컬 dedup 하고, portfolio-hub 중복/409 를 안전 처리해 동일 체결의 중복 원장이 0 이 되게 한다.
• write 결과는 outcome 어휘 completed / duplicate_completed / retryable_failure / conflict_blocked 로 분류한다. retryable_failure 는 재시도하고, conflict_blocked(409)는 운영자 해소 대상으로 보류한다.

Acceptance Criteria

1. Given 동일 execution_id 의 원장 기록을 2회 수행, When outbox 처리, Then 원장에 중복 거래가 생기지 않는다(correlation_id dedup, 중복 0). (NFR-2)
2. Given portfolio-hub write 가 일시 실패(retryable), When 재시도 루프, Then 결국 1건이 기록되고(completed) 슬롯 전이 일관성이 유지된다(무유실). (NFR-2)
3. Given portfolio-hub 가 409 충돌을 반환, When outbox 처리, Then outcome 이 conflict_blocked 로 표시되고 운영자 해소 전까지 자동 재시도로 무한 반복하지 않는다.
4. Given 이미 기록된 work item 재처리, When outbox 처리, Then outcome 이 duplicate_completed 로 분류되고 원장은 변하지 않는다.
5. Given 체결 직후 portfolio-hub 불가, When 슬롯 전이, Then 슬롯 전이는 기록 성공 여부와 무관하게 진행된다(분리).

Impacted Area

• Docs: docs/runtime-flows.md(ledger outbox/재시도 흐름), docs/data-model.md(outbox work item/멱등 키) — REQ-020 에서 정합
• Modules: 신규 ledger outbox(work item store) + 재시도 워커, REQ-018 의 fill 기록 경로가 직접 write 대신 outbox 적재로 연결
• Tests: 동일 execution_id 중복 0, 실패 주입 후 재시도로 결국 기록, 409→conflict_blocked, duplicate_completed, 전이/기록 분리

Notes

• 출처: dcy-004 FR-3, FR-4, NFR-2, R-1(High, 원장 유실/중복).
• BAT-004 의 broker handoff durability(REQ-014, 옵션 A)와 유사 구조이나 ledger 전용 outbox 다. 부분체결/정밀 세금 모델은 본 REQ 범위 밖(후속).
• 멱등/무유실(NFR-2)을 별도 REQ 로 승격하지 않고 본 REQ 의 AC-1/AC-2 로 흡수한다.
• conflict_blocked 운영자 해소 절차의 상세(알림/대시보드)는 운영 단계 후속.

Change Log

CHG-20260604-01

• Date: 2026-06-04
• Author: Justin Ko

Change Summary

• dcy-004 FR-3/FR-4 로부터 최초 생성(Proposed). NFR-2(멱등/무유실) 흡수.

Intent

• 원장 기록 무유실+멱등(outbox 재시도, correlation_id dedup, outcome 어휘)을 backlog 로 정규화.

Acceptance Criteria Delta

• Added:
  • 중복 0, 실패 재시도 결국 기록, conflict_blocked, duplicate_completed, 전이/기록 분리 5개 기준
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/runtime-flows.md, docs/data-model.md
• Modules:
  • ledger outbox store + 재시도 워커
• Tests:
  • 멱등/무유실/conflict 주입 테스트

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 편성

Validation Plan

• 동일 execution_id 중복 0 + 원장 실패 주입 후 재시도 결국 기록 + 409 conflict_blocked 테스트로 검증.

CHG-20260604-02

• Date: 2026-06-04
• Author: Justin Ko

Change Summary

• Status 변경: Proposed -> Approved. confirm-req 승인 게이트 통과.

Intent

• ledger outbox durability 와 correlation_id 멱등 요구사항을 delivery input 으로 승인.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • 없음
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: Approved
• Follow-up Action: batch 편성

Validation Plan

• 기존 Acceptance Criteria 로 batch delivery 에서 검증.