trex-core/docs/srs/Documentation/req-020_ledger-baseline-alignment.md

req-020: ledger 레이어 baseline 문서 정합

• Status: Approved
• Type: Documentation
• Priority: Medium
• Owner: project maintainers

Intent

• portfolio-hub ledger 통합(REQ-017~019)이 도입하는 LedgerPort, 체결→원장 기록 흐름, ledger outbox, 원장 데이터 필드를 baseline 문서에 반영해 코드와 문서의 정합을 유지한다.

Requirement

• 아래 baseline 문서를 ledger 레이어에 맞게 갱신한다.
  • docs/runtime-flows.md: 체결→원장 기록 흐름 + ledger outbox 재시도/conflict 흐름.
  • docs/interface-contract.md: LedgerPort.record_trade 계약 + FillStatus 확장(execution_id/fee) + portfolio-hub ledger 엔드포인트.
  • docs/project-structure.md: ledger 어댑터(adapters/ledger) 및 outbox 컴포넌트 위치.
  • docs/data-model.md: 원장 거래 기록 필드(asset_id/side/qty/price/fee/tax/executed_at/execution_id) + outbox work item/멱등 키(correlation_id).

Acceptance Criteria

1. Given REQ-017~019 구현, When baseline 문서를 점검, Then 4개 문서(runtime-flows/interface-contract/project-structure/data-model)에 ledger 레이어가 반영되어 있다.
2. Given baseline 문서, When 코드와 대조, Then LedgerPort 계약·FillStatus 확장·outbox 구조·원장 필드 설명이 실제 구현과 모순되지 않는다.
3. Given 변경 로그, When 점검, Then 각 baseline 문서의 변경 이력에 ledger 통합(REQ-017~020) 반영이 기록되어 있다.

Impacted Area

• Docs: docs/runtime-flows.md, docs/interface-contract.md, docs/project-structure.md, docs/data-model.md
• Modules: 없음(문서 전용)
• Tests: 문서-코드 정합 점검(리뷰), 필요 시 interface-contract 예시와 실제 시그니처 대조

Notes

• 출처: dcy-004 FR-5.
• baseline 갱신은 REQ-017~019 구현 내용에 의존하므로 동일 batch 후반 또는 구현 직후 수행하는 편이 적절하다(REQ-015 baseline 정합 선례와 동일 패턴).

Change Log

CHG-20260604-01

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

Change Summary

• dcy-004 FR-5 로부터 최초 생성(Proposed).

Intent

• ledger 레이어 도입에 따른 baseline 문서(runtime-flows/interface-contract/project-structure/data-model) 정합을 backlog 로 정규화.

Acceptance Criteria Delta

• Added:
  • 4개 baseline 반영, 코드 정합, 변경 이력 기록 3개 기준
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/runtime-flows.md, docs/interface-contract.md, docs/project-structure.md, docs/data-model.md
• Modules:
  • 없음
• Tests:
  • 문서-코드 정합 점검

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 편성(REQ-017~019 와 동일 batch 권장)

Validation Plan

• REQ-017~019 구현 후 4개 baseline 문서를 코드와 대조해 정합 확인.

CHG-20260604-02

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

Change Summary

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

Intent

• ledger 레이어 baseline 문서 정합 요구사항을 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 편성(REQ-017~019 와 동일 batch 권장)

Validation Plan

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