trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e32eb786564ce38e4d148ce7c73e47d093047e2f
trex-core/docs/srs/Documentation/req-020_ledger-baseline-alignment.md
T
genichinandClaude Opus 4.8 b851b927ee fix(ledger): dcy-015 outbox 영속 오류 분류 + 백오프/dead-letter (BAT-019) 
portfolio-hub 404(미등록 포트폴리오)가 retryable 로 분류되어 백오프·상한 없이
초당 영구 재시도되던 버그(issue #13, 실측 930회) 정정.

거버넌스: 전부 change-req (신규 REQ 없음, dcy-015 OQ-3; 백오프 env 는 REQ-019 흡수).
- REQ-017: 404/400/422 → LedgerPermanentError 분류 (409 conflict / 408·429·5xx·
  network retryable 불변). LedgerPort 에 permanent 타입 추가
- REQ-019: 영속 → 터미널 delivery_failed 즉시(재시도 0). retryable 지수 백오프
  +jitter+next_retry_at, max_attempts 초과 시 dead-letter delivery_failed.
  list_pending 이 백오프 행 스킵(head-of-line 보호). 마이그레이션 007(status enum
  +next_retry_at). 백오프 env(base/cap/max-attempts)
- REQ-018: 터미널/dead-letter WARN + WriterStats.delivery_failed 카운터 가시화
- REQ-020: runtime-flows/data-model/interface-contract 정합

단일 터미널 delivery_failed(permanent/dead-letter, last_outcome 로 사유 구분) —
conflict_blocked 패턴과 동형. dead-letter 는 운영자 재처리 가능 상태.

검증: 단위 311 passed/34 skipped, 인프라 게이트(PG+RabbitMQ) 345 passed, ruff clean.
신규 test_ledger_outbox_backoff + adapter/PG 테스트, 기존 retryable 백오프 정합.
BAT-019 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 16:12:17 +09:00

6.1 KiB
Raw Blame History

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

  • Status: Implemented
  • 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 에서 검증.

CHG-20260604-03

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

Change Summary

  • Status 변경: Approved -> Implemented. BAT-006 release-candidate verification evidence 기반.

Intent

  • runtime-flows / interface-contract / project-structure / data-model 4문서를 ledger 레이어와 정합시킨 baseline 갱신을 구현 완료 상태로 동기화.

Acceptance Criteria Delta

  • Added/Updated/Removed: 없음

Impacted Area Delta

  • Docs/Modules/Tests: 없음 (변경은 상태 전이만)

Delivery Trace Delta

  • Batches:
    • BAT-006 (release-candidate)
  • Releases:
    • none

Revalidation Impact

  • Reverification Needed: no
  • Existing Implementation Invalidated: no
  • Status Recommendation: Implemented
  • Follow-up Action: release 단계는 별도 진행

Validation Plan

  • AC-1: 4 baseline 문서(runtime-flows/interface-contract/project-structure/data-model) 에 ledger 레이어 섹션 반영 완료.
  • AC-2: baseline 문서 ↔ 코드 정합 manual review (verification.md Manual 섹션). NFR-1 import 스윕 + grep 결과로 보강.
  • AC-3: 4 baseline 문서 Change Log 모두 2026-06-04 BAT-006 항목 추가.

CHG-20260608-01

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

Change Summary

  • (change-req, dcy-015) baseline 문서를 ledger 오류 분류·백오프·터미널 상태에 맞춰 정합: docs/runtime-flows.md(ledger writer permanent/backoff/dead-letter + list_pending 백오프 스킵 + env), docs/data-model.md(ledger_outbox status delivery_failed·next_retry_at·last_outcome 확장), docs/interface-contract.md(LedgerPermanentError 오류 계약). BAT-019 정합 완료 → Implemented 유지.

Intent

  • 코드(ledger_port/portfolio_hub/ledger_outbox/postgresql/config) 변경과 baseline 문서를 일치(S 기준)시켜 운영자 참조 정합 유지.

Acceptance Criteria Delta

  • Updated:
    • runtime-flows/data-model/interface-contract 의 ledger 오류 분류·백오프·터미널 상태 기술 정합.

Impacted Area Delta

  • Docs: docs/runtime-flows.md, docs/data-model.md, docs/interface-contract.md

Delivery Trace Delta

  • Batches: BAT-019
  • Releases: none

Revalidation Impact

  • Reverification Needed: no (문서 정합)
  • Existing Implementation Invalidated: no
  • Status Recommendation: Implemented (change-req → BAT-019 정합)
  • Follow-up Action: confirm-req-implemented(BAT-019).

Validation Plan

  • BAT-019: 코드-문서 diff 대조.
Reference in New Issue View Git Blame Copy Permalink