From 01a51d0c16f5505704a01049e3d49f894b7e7b74 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Thu, 4 Jun 2026 22:32:27 +0900 Subject: [PATCH] Advance dcy-004 ledger slice: confirm Discovery, draft+approve REQ-017~020, draft BAT-006 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - confirm-discovery dcy-004: draft→confirmed (Confirmed By: Justin Ko), OQ-1~3 resolved, scope/R-1 accepted, portfolio-hub contract deferred to REQ/delivery - draft-req: REQ-017 (LedgerPort + portfolio-hub adapter + stub), REQ-018 (fill→ledger recording + FillStatus exec_id/fee), REQ-019 (ledger outbox durability + correlation_id idempotency), REQ-020 (baseline alignment); NFR-1~3 absorbed - confirm-req: REQ-017~020 Proposed→Approved - draft-batch: BAT-006 (standard) bundling REQ-017~020 from dcy-004 - Update SRS/Discovery/batches indexes Co-Authored-By: Claude Opus 4.8 --- .../design.md | 42 +++++++ .../implementation.md | 35 ++++++ .../index.md | 30 +++++ .../planning.md | 47 +++++++ .../verification.md | 40 ++++++ docs/batches/index.md | 1 + ...260604_portfolio-hub-ledger-integration.md | 34 ++--- docs/discovery/index.md | 2 +- .../req-020_ledger-baseline-alignment.md | 114 +++++++++++++++++ ...19_ledger-outbox-durability-idempotency.md | 116 ++++++++++++++++++ ...7_ledger-port-and-portfolio-hub-adapter.md | 115 +++++++++++++++++ .../req-018_fill-to-ledger-recording.md | 116 ++++++++++++++++++ docs/srs/index.md | 10 +- 13 files changed, 681 insertions(+), 21 deletions(-) create mode 100644 docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/design.md create mode 100644 docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/implementation.md create mode 100644 docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/index.md create mode 100644 docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/planning.md create mode 100644 docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/verification.md create mode 100644 docs/srs/Documentation/req-020_ledger-baseline-alignment.md create mode 100644 docs/srs/Exception/req-019_ledger-outbox-durability-idempotency.md create mode 100644 docs/srs/Integration/req-017_ledger-port-and-portfolio-hub-adapter.md create mode 100644 docs/srs/Integration/req-018_fill-to-ledger-recording.md diff --git a/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/design.md b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/design.md new file mode 100644 index 0000000..6e9085a --- /dev/null +++ b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/design.md @@ -0,0 +1,42 @@ +# BAT-006 Design + +- Status: draft +- Batch: BAT-006 + +## Architecture Summary +- BAT-004 execution loop 위에 ledger write-back 레이어를 추가한다. **application** 에 `LedgerPort`와 ledger outbox use case, **adapters/ledger** 에 in-memory/stub 및 portfolio-hub HTTP 어댑터, **runtime** 에 ledger retry worker/config 를 둔다. execution fill 전이는 슬롯 상태 전이를 먼저 보장하고 ledger 기록은 outbox 로 적재해 eventually-consistent 하게 처리한다. + +## Changed Areas +- Docs: runtime-flows(체결→ledger outbox→portfolio-hub retry/conflict 흐름), interface-contract(`LedgerPort`, `FillStatus` 확장, portfolio-hub endpoint), project-structure(ledger adapter/outbox 위치), data-model(ledger trade fields, outbox work item, correlation_id). +- Modules: + - application: `LedgerPort`, ledger exceptions, ledger outbox command/service, execution fill hook. + - adapters/ledger: in-memory/stub ledger, portfolio-hub HTTP adapter. + - adapters/broker: paper/KIS `FillStatus.execution_id` 합성, fee 계산 운반. + - runtime: portfolio-hub config, ledger retry loop lifecycle. + - persistence: ledger outbox work item store/schema. +- Interfaces: `LedgerPort.record_trade(...)`, `FillStatus.execution_id/fee`, portfolio-hub `POST /v1/assets/{asset_id}/ledger/trades`. + +## Key Decisions +1. `asset_id == portfolio_id`: 슬롯의 `portfolio_id` 를 ledger path param 으로 직접 사용한다. 매핑 조회나 asset master 동기화는 후속 범위다. +2. outbox 우선: fill 전이 경로는 ledger 직접 HTTP write 대신 durable outbox work item 을 적재한다. 슬롯 전이는 ledger write 성공과 분리한다. +3. 멱등 키: `correlation_id = {asset_id}:{order_id}:{execution_id}` 로 로컬 dedup 하고 portfolio-hub 409 는 `conflict_blocked` 로 분류한다. +4. outcome 어휘: `completed`, `duplicate_completed`, `retryable_failure`, `conflict_blocked` 네 가지로 worker 결과를 고정한다. +5. 도메인 순수성: `trex_core/domain` 은 portfolio-hub, HTTP, ledger adapter 를 import 하지 않는다. LedgerPort 는 application 경계, HTTP adapter 는 adapters 경계에 둔다. +6. 단일 기록 주체: 전략/도메인이 아니라 execution fill path 만 ledger outbox item 을 생성한다. + +## Edge Cases +- 동일 `execution_id` work item 이 2회 생성/처리됨 → correlation_id 로 dedup, 원장 중복 0, outcome `duplicate_completed`. +- portfolio-hub 일시 실패/timeout → `retryable_failure`, 다음 worker tick 에 재시도, 슬롯 상태는 이미 전이된 상태 유지. +- portfolio-hub 409 conflict → `conflict_blocked`, 자동 무한 재시도 중단, 운영자 해소 대상으로 남김. +- `portfolio_id` 없는 체결 → 정의된 정책에 따라 ledger 기록 skip 또는 blocked outcome 으로 처리하되 슬롯 전이는 정상 수행. +- KIS 체결 데이터 부족 → 결정적 execution_id 합성 규칙으로 보강하고, fee 는 BrokerPort 계산, tax 는 0. +- retry worker 재시작 → persisted outbox 상태를 기준으로 미완료 item 만 재처리. + +## Architecture Impact +- both (project-structure + runtime-flows). interface-contract(`LedgerPort`, `FillStatus`)와 data-model(outbox/correlation_id)도 갱신한다. + +## Reference Doc Update Plan +- project-structure.md: `application` ledger port/outbox service, `adapters/ledger`, runtime retry worker, persistence schema 위치를 반영한다. +- runtime-flows.md: fill transition 이후 outbox 적재, retry worker, completed/duplicate/conflict/retryable 흐름을 추가한다. +- interface-contract.md: `LedgerPort.record_trade(...)`, `FillStatus.execution_id/fee`, portfolio-hub ledger endpoint/409 mapping 을 추가한다. +- data-model.md: ledger trade payload fields, outbox work item fields/status/outcome, `correlation_id` 멱등 규칙을 추가한다. diff --git a/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/implementation.md b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/implementation.md new file mode 100644 index 0000000..de9e42e --- /dev/null +++ b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/implementation.md @@ -0,0 +1,35 @@ +# BAT-006 Implementation + +- Status: draft +- Batch: BAT-006 + +## Plan Summary +- LedgerPort 계약과 portfolio-hub/stub adapter 를 추가하고, execution fill 경로가 ledger outbox work item 을 적재하도록 연결한다. retry worker 와 dedup/outcome 처리를 구현한 뒤 baseline 문서를 실제 코드와 맞춘다. + +## Changed Files +- 예정: + - `trex_core/application/*` — LedgerPort, ledger outbox service, execution fill hook. + - `trex_core/adapters/ledger/*` — in-memory/stub ledger, portfolio-hub adapter. + - `trex_core/adapters/broker/*` — FillStatus execution_id/fee 운반. + - `trex_core/runtime/*` — portfolio-hub config, retry worker lifecycle. + - persistence/migration 파일 — ledger outbox work item store. + - `docs/runtime-flows.md`, `docs/interface-contract.md`, `docs/project-structure.md`, `docs/data-model.md`. + - tests — ledger adapter, fill lifecycle, outbox retry/dedup/conflict, import sweep. + +## Execution Log +1. 대기: `draft-batch-planning`/`draft-batch-design` 확인 후 구현 시작. + +## Validation +- 예정: + - stub ledger `record_trade` 단위테스트. + - portfolio-hub adapter request contract + 409 mapping 테스트. + - buy/sell fill lifecycle 통합테스트. + - duplicate execution_id 중복 0 테스트. + - retryable failure 후 eventually completed 테스트. + - `conflict_blocked` 자동 재시도 중단 테스트. + - `trex_core/domain` import sweep. + - baseline 문서-코드 정합 리뷰. + +## Remaining Risks +- portfolio-hub 실제 계약/자격증명 미가용 시 external integration evidence 가 stub/contract 수준으로 제한될 수 있다. +- outbox persistence schema 가 기존 repository transaction 경계와 맞지 않으면 design 조정이 필요하다. diff --git a/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/index.md b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/index.md new file mode 100644 index 0000000..f650b39 --- /dev/null +++ b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/index.md @@ -0,0 +1,30 @@ +# BAT-006: portfolio-hub ledger 통합 + +- Status: draft +- Profile: standard +- Source Discovery: dcy-004 +- Included REQ: REQ-017, REQ-018, REQ-019, REQ-020 +- Excluded REQ: 없음 + +## Summary +- dcy-004 슬라이스(체결을 외부 회계/포지션 원장에 기록)를 하나의 delivery 단위로 묶는다. BAT-004 의 주문 집행 루프 위에 `LedgerPort` + portfolio-hub 어댑터 + fill hook + ledger outbox 재시도/멱등 처리를 추가하고, baseline 문서를 실제 ledger 레이어와 정합시킨다. + +## Scope +- In Scope: + - REQ-017: `LedgerPort.record_trade(...)` 계약, portfolio-hub ledger 어댑터, 결정론 stub/in-memory 원장, `TREX_PORTFOLIO_HUB_*` config. + - REQ-018: 매수/매도 fill 전이 시 ledger 기록 hook, `FillStatus.execution_id/fee` 확장, `asset_id = slot.portfolio_id` 사용, 단일 기록 주체 유지. + - REQ-019: ledger outbox work item, correlation_id 멱등, retry worker, outcome(`completed`/`duplicate_completed`/`retryable_failure`/`conflict_blocked`) 분류. + - REQ-020: runtime-flows/interface-contract/project-structure/data-model ledger baseline 정합. +- Out of Scope (후속 Discovery): + - `post_portfolio_transaction` 입출금 등 거래 외 트랜잭션, asset master 동기화, portfolio-hub ↔ core 양방향 reconciliation, 포지션 재구성, safety floor, 매수·매도 전략 데몬, 실계좌 go-live. + +## Documents +- Planning: [planning.md](./planning.md) +- Design: [design.md](./design.md) +- Implementation: [implementation.md](./implementation.md) +- Verification: [verification.md](./verification.md) + +## Notes +- Source Discovery dcy-004 단일. 확정 결정: `asset_id == portfolio_id`, 별도 ledger outbox + retry loop, execution_id 결정적 합성(KIS/paper), fee 는 BrokerPort 계산, tax 기본 0. +- 핵심 리스크: 원장 기록 유실/중복(R-1), portfolio-hub 장애가 execution path 를 막는 결합(R-3). outbox + dedup + adapter 격리 + stub failure injection 으로 완화한다. +- portfolio-hub 실제 계약/자격증명은 orbit `post_ledger_trade` 동일 가정을 시작점으로 두되, verification 에서 adapter contract evidence 또는 미가용 blocker 를 분리 기록한다. diff --git a/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/planning.md b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/planning.md new file mode 100644 index 0000000..f5ebba4 --- /dev/null +++ b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/planning.md @@ -0,0 +1,47 @@ +# BAT-006 Planning + +- Status: draft +- Batch: BAT-006 +- Profile: standard + +## Included REQ +- REQ-017 (Integration): LedgerPort 추상화 + portfolio-hub 어댑터 + stub 원장 +- REQ-018 (Integration): 체결→원장 기록 fill hook +- REQ-019 (Exception): ledger outbox durability + correlation_id 멱등 +- REQ-020 (Documentation): ledger 레이어 baseline 문서 정합 + +## Delivery Plan +- 의존 순서대로 구현한다. + 1. REQ-017: `trex_core/application` 에 `LedgerPort` 계약과 ledger 예외를 정의하고, `trex_core/adapters/ledger` 에 in-memory/stub 원장과 portfolio-hub HTTP 어댑터를 추가한다. + 2. REQ-018: `FillStatus` 가 `execution_id`/`fee` 를 운반하도록 broker port 와 paper/KIS 어댑터를 확장하고, execution fill 전이에 ledger 기록 입력을 연결한다. + 3. REQ-019: 직접 write 대신 ledger outbox 적재 + retry worker 로 경로를 고정하고, `correlation_id = {asset_id}:{order_id}:{execution_id}` dedup/outcome 분류를 구현한다. + 4. REQ-020: 실제 코드 경계와 data model 이 확정된 뒤 baseline 4문서(runtime-flows/interface-contract/project-structure/data-model)를 갱신한다. + +## Dependencies +- Internal: + - REQ-018 은 REQ-017 의 `LedgerPort`와 stub 원장 선행. + - REQ-019 는 REQ-018 의 fill 기록 이벤트를 직접 write 가 아니라 outbox work item 으로 전환. + - REQ-020 은 REQ-017~019 구현 결과에 의존. + - BAT-004 의 execution loop, BrokerPort, FillStatus, PostgreSQL runtime 위에서 확장한다. +- External: + - portfolio-hub ledger API(`POST /v1/assets/{asset_id}/ledger/trades`, orbit `post_ledger_trade` 패턴). + - portfolio-hub URL/token 환경 변수(`TREX_PORTFOLIO_HUB_*`). + - HTTP client, PostgreSQL(outbox persistence), 기존 .env loading(REQ-010). + +## Design Gate +- Design Required Before Implementation: yes +- Reason: 신규 application port + external adapter + execution fill lifecycle + outbox durability/retry worker + baseline data model 이 모두 구조/인터페이스/런타임에 영향. 구현 전 `record_trade` 계약, fill event shape, outbox schema/state machine, failure/outcome policy 를 design.md 에 고정해야 한다. + +## Milestones +1. M1 — REQ-017: LedgerPort + stub ledger + portfolio-hub adapter contract/409 handling + config. +2. M2 — REQ-018: FillStatus execution_id/fee 확장 + paper/KIS 결정적 값 운반 + buy/sell fill hook. +3. M3 — REQ-019: ledger outbox store + retry worker + correlation_id dedup + conflict/retry outcomes. +4. M4 — REQ-020: baseline 4문서 정합. +5. M5 — 통합 verification: buy/sell lifecycle, duplicate 0, retry eventually completed, conflict_blocked, import sweep. + +## Risks +- R-1 (High): 원장 기록 유실/중복. 대응: outbox persistence + correlation_id dedup + duplicate_completed/conflict_blocked outcome + failure injection tests. +- R-2 (High): fill 전이와 ledger write 결합으로 슬롯 전이 지연/실패. 대응: 슬롯 전이는 우선 진행하고 ledger write 는 outbox retry 로 분리. +- R-3 (Medium): portfolio-hub 계약/자격증명 미가용. 대응: stub/in-memory 완전 검증, adapter contract test, 실제 통합은 evidence 또는 blocker 로 분리. +- R-4 (Medium): 도메인 순수성/단일 기록 주체 침식. 대응: LedgerPort 는 application 계약, HTTP 는 adapters 격리, `trex_core/domain` import sweep, 기록 주체는 execution path 로 한정. +- R-5 (Medium): REQ-020 baseline 이 구현보다 먼저 확정되어 drift 발생. 대응: baseline 갱신은 M4 로 후행하고 verification 에 코드-문서 정합 점검 포함. diff --git a/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/verification.md b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/verification.md new file mode 100644 index 0000000..ba2e2bb --- /dev/null +++ b/docs/batches/bat-006_20260604_portfolio-hub-ledger-integration/verification.md @@ -0,0 +1,40 @@ +# BAT-006 Verification + +- Status: draft +- Batch: BAT-006 + +## Acceptance Mapping +- REQ-017: + - AC-1: in-memory stub 원장 `record_trade(...)` 1회 호출 시 거래 1건 적재와 필드 보존 evidence. + - AC-2: portfolio-hub adapter 가 `POST /v1/assets/{asset_id}/ledger/trades` 에 `execution_id` 포함 payload 를 전송하는 contract evidence. + - AC-3: portfolio-hub 409 응답이 `LedgerConflictError` 또는 `conflict_blocked` 경로로 표면화되는 evidence. + - AC-4: `trex_core/domain` portfolio-hub/HTTP 의존 0 import sweep evidence. +- REQ-018: + - AC-1: idle 슬롯 매수 intent 체결 시 holding 전이 + buy ledger item/record 1건 evidence. + - AC-2: holding 슬롯 매도 intent 체결 시 closed 전이 + sell ledger item/record 1건 evidence. + - AC-3: `FillStatus` 가 결정적 `execution_id`, fee, tax=0 을 운반하는 evidence. + - AC-4: `portfolio_id` 부재 체결 정책(skip/block)과 슬롯 전이 일관성 evidence. + - AC-5: ledger 기록 주체가 execution path 로 한정되는 code review/import evidence. +- REQ-019: + - AC-1: 동일 execution_id 2회 처리 시 원장 중복 0 evidence. + - AC-2: retryable portfolio-hub failure 후 retry 로 eventually completed evidence. + - AC-3: 409 conflict 가 `conflict_blocked` 로 남고 무한 자동 재시도하지 않는 evidence. + - AC-4: 이미 기록된 work item 재처리 시 `duplicate_completed` evidence. + - AC-5: portfolio-hub 불가 직후에도 슬롯 전이는 진행되는 분리 evidence. +- REQ-020: + - AC-1: 4개 baseline 문서에 ledger 레이어 반영 evidence. + - AC-2: LedgerPort, FillStatus, outbox 구조, 원장 필드 설명이 코드와 모순되지 않는 review evidence. + - AC-3: baseline 문서 변경 이력에 REQ-017~020 반영 기록 evidence. + +## Evidence +- Test: + - 대기: 구현 후 테스트 결과 기록. +- Manual: + - 대기: baseline 문서-코드 정합 리뷰 기록. +- Logs: + - 대기: 필요 시 portfolio-hub adapter contract 또는 skip/blocker 로그 기록. + +## Result +- Ready for Release: false +- Blocking Issues: + - 구현 및 검증 미진행. diff --git a/docs/batches/index.md b/docs/batches/index.md index 4e83c20..3f02c25 100644 --- a/docs/batches/index.md +++ b/docs/batches/index.md @@ -13,3 +13,4 @@ | BAT-003 | batch-lite | release-candidate | REQ-010 | dcy-002 | [bat-003](./bat-003_20260604_daemon-dotenv-config/) | | BAT-004 | standard | release-candidate | REQ-011, REQ-012, REQ-013, REQ-014, REQ-015 | dcy-003 | [bat-004](./bat-004_20260604_broker-execution-and-outbox/) | | BAT-005 | batch-lite | release-candidate | REQ-016 | dcy-003 | [bat-005](./bat-005_20260604_kis-token-redis-cache/) | +| BAT-006 | standard | draft | REQ-017, REQ-018, REQ-019, REQ-020 | dcy-004 | [bat-006](./bat-006_20260604_portfolio-hub-ledger-integration/) | diff --git a/docs/discovery/dcy-004_20260604_portfolio-hub-ledger-integration.md b/docs/discovery/dcy-004_20260604_portfolio-hub-ledger-integration.md index 815f7d4..d8ea423 100644 --- a/docs/discovery/dcy-004_20260604_portfolio-hub-ledger-integration.md +++ b/docs/discovery/dcy-004_20260604_portfolio-hub-ledger-integration.md @@ -1,14 +1,14 @@ # 0. 문서 상태 이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다. -- 상태: draft +- 상태: confirmed - 문서 ID: dcy-004_20260604_portfolio-hub-ledger-integration - 이슈명: portfolio-hub ledger 연동 — 체결을 외부 원장에 기록 - 작성 시각(KST): 2026-06-04 -- 마지막 갱신 시각(KST): 2026-06-04 +- 마지막 갱신 시각(KST): 2026-06-04 21:55 - 대체됨: 없음 - 후속 Discovery 참조: 없음 -- 생성된 REQ 참조: 없음 +- 생성된 REQ 참조: REQ-017, REQ-018, REQ-019, REQ-020 # 1. 계획 상태 요약 현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다. @@ -162,16 +162,16 @@ # 8. REQ로 넘기기 전 확인 체크 REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다. -- [ ] 범위(In Scope/Out of Scope) 확정 — 특히 거래 외 트랜잭션/asset 동기화 제외 - - 기준: 운영자가 슬라이스 경계를 확인했다. +- [x] 범위(In Scope/Out of Scope) 확정 — 특히 거래 외 트랜잭션/asset 동기화 제외 + - 기준: 운영자가 슬라이스 경계를 확인했다. (운영자 확정 2026-06-04 — 문서대로 수용) - [x] 성공 지표의 측정 방식/데이터 출처 확정 - 기준: S-1~S-5 측정 방식·출처 명시(본 문서 # 7). -- [ ] High 영향 리스크(R-1 원장 유실/중복) 처리 방침 확정 - - 기준: execution_id 멱등 + 재시도/보류로 수용 가능한지 운영자 확인. -- [ ] 모든 오픈 질문(OQ) `Open` 상태 없음 확인 +- [x] High 영향 리스크(R-1 원장 유실/중복) 처리 방침 확정 + - 기준: execution_id 멱등 + 재시도/보류로 수용 가능한지 운영자 확인. (운영자 확정 2026-06-04 — 멱등+outbox 재시도 수용) +- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인 - 기준: OQ 목록에 `Open` 0개 또는 잔여 전부 `Deferred` (OQ-1~OQ-3 전부 Answered → `Open` 0개) -- [ ] Freeze 확정 담당자(CONFIRMED_BY) 지정 - - 기준: 운영자가 confirm-discovery 시점에 CONFIRMED_BY 를 지정한다. +- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정 + - 기준: 운영자가 confirm-discovery 시점에 CONFIRMED_BY 를 지정한다. (Confirmed By = Justin Ko) # 9. 파일 처리 결과 이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다. @@ -191,10 +191,10 @@ REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 ## CONFIRM - ~~체결 데이터 출처~~ → 결정됨: execution_id 결정적 합성(KIS 규칙/paper) + fee BrokerPort 계산 + tax 0 (OQ-3, 2026-06-04) -- {{CONFIRM_SCOPE_DEFER}} — 거래 외 트랜잭션·asset 동기화·reconciliation 을 후속으로 미루는 범위 경계 확정 +- ~~범위 경계 확정~~ → 결정됨: 거래 외 트랜잭션(`post_portfolio_transaction`)·asset 동기화·reconciliation 을 후속 Discovery 로 미루는 In/Out Scope 경계를 문서대로 확정 (운영자 Justin Ko, 2026-06-04) ## DATA -- {{DATA_PORTFOLIO_HUB_CONTRACT}} — portfolio-hub ledger API 계약/자격증명(orbit 와 동일 가정 검증) +- ~~portfolio-hub ledger API 계약/자격증명~~ → REQ/delivery 단계 계측·확정으로 위임(비차단): 설계는 orbit `post_ledger_trade` 검증 패턴 + stub/in-memory 결정론 테스트(S-1~S-5)로 REQ 초안 작성에 충분하며, 실제 계약/자격증명(orbit 동일 가정 A-1) 검증은 REQ acceptance/verification evidence 로 수집. (운영자 Justin Ko, 2026-06-04) # 11. Discovery Freeze REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다. @@ -207,8 +207,8 @@ REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록 - 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약) ## Freeze 플래그 -- Handoff Decision: 보류 -- Handoff Rationale: 초기 Discovery 초안 생성 완료. OQ-1~OQ-3(asset_id 소스·기록 내구성·체결 데이터 출처)와 범위 경계가 미확정이며, confirm-discovery 에서 운영자 결정 후 REQ Drafting 으로 인계한다. -- Ready for REQ Drafting: false -- Confirmed By: TBD -- Confirmed At (KST): TBD +- Handoff Decision: 승인 +- Handoff Rationale: OQ-1~OQ-3(asset_id 소스·기록 내구성·체결 데이터 출처) 전부 Answered, 범위 경계·R-1 처리 방침 운영자 확정(문서대로). portfolio-hub ledger API 계약/자격증명(DATA)은 orbit 동일 가정 + stub 결정론 검증으로 REQ 초안 작성을 막지 않아 REQ/delivery 계측 evidence 로 위임(비차단). 저장소 사실 관계는 현재 상태와 일치(ledger 모듈 0, portfolio_id 배선만 됨, BAT-004 fill 전이 확인). REQ Drafting 으로 인계한다. +- Ready for REQ Drafting: true +- Confirmed By: Justin Ko +- Confirmed At (KST): 2026-06-04 21:47 diff --git a/docs/discovery/index.md b/docs/discovery/index.md index da14653..cb85669 100644 --- a/docs/discovery/index.md +++ b/docs/discovery/index.md @@ -9,4 +9,4 @@ | dcy-001_20260603_slot-pure-domain-migration | 20260603 | trex-core 베이스 수립 및 slot 순수 도메인 이식 | [Discovery](./dcy-001_20260603_slot-pure-domain-migration.md) | confirmed | | dcy-002_20260603_slot-core-daemon-http-api | 20260603 | trex-core 슬롯 코어 데몬화 + HTTP intent API | [Discovery](./dcy-002_20260603_slot-core-daemon-http-api.md) | confirmed | | dcy-003_20260604_broker-execution-and-outbox | 20260604 | 브로커 단일 세션 + 주문 집행 + durable outbox (불변식 B) | [Discovery](./dcy-003_20260604_broker-execution-and-outbox.md) | confirmed | -| dcy-004_20260604_portfolio-hub-ledger-integration | 20260604 | portfolio-hub ledger 연동 — 체결을 외부 원장에 기록 | [Discovery](./dcy-004_20260604_portfolio-hub-ledger-integration.md) | draft | \ No newline at end of file +| dcy-004_20260604_portfolio-hub-ledger-integration | 20260604 | portfolio-hub ledger 연동 — 체결을 외부 원장에 기록 | [Discovery](./dcy-004_20260604_portfolio-hub-ledger-integration.md) | confirmed | \ No newline at end of file diff --git a/docs/srs/Documentation/req-020_ledger-baseline-alignment.md b/docs/srs/Documentation/req-020_ledger-baseline-alignment.md new file mode 100644 index 0000000..a112086 --- /dev/null +++ b/docs/srs/Documentation/req-020_ledger-baseline-alignment.md @@ -0,0 +1,114 @@ +# 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 에서 검증. diff --git a/docs/srs/Exception/req-019_ledger-outbox-durability-idempotency.md b/docs/srs/Exception/req-019_ledger-outbox-durability-idempotency.md new file mode 100644 index 0000000..7f44001 --- /dev/null +++ b/docs/srs/Exception/req-019_ledger-outbox-durability-idempotency.md @@ -0,0 +1,116 @@ +# 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 에서 검증. diff --git a/docs/srs/Integration/req-017_ledger-port-and-portfolio-hub-adapter.md b/docs/srs/Integration/req-017_ledger-port-and-portfolio-hub-adapter.md new file mode 100644 index 0000000..9b691ac --- /dev/null +++ b/docs/srs/Integration/req-017_ledger-port-and-portfolio-hub-adapter.md @@ -0,0 +1,115 @@ +# req-017: LedgerPort 추상화 + portfolio-hub 어댑터 + stub 원장 + +- Status: Approved +- Type: Integration +- Priority: High +- Owner: project maintainers + +## Intent +- 체결을 외부 회계/포지션 원장(portfolio-hub)에 기록할 수 있도록, 도메인/네트워크 의존을 어댑터로 격리한 `LedgerPort` 계약과 portfolio-hub 어댑터, 그리고 결정론 검증용 stub/in-memory 원장을 제공한다. + +## Requirement +- `LedgerPort.record_trade(asset_id, order_id, execution_id, side, qty, price, fee, tax, executed_at)` Protocol 을 application 레이어에 정의한다. +- `PortfolioHubLedger` 어댑터는 trex-orbit `post_ledger_trade` 패턴을 따라 `POST /v1/assets/{asset_id}/ledger/trades` 로 거래를 기록하고, `execution_id` 로 멱등하며, portfolio-hub 가 반환하는 409 충돌을 `LedgerConflictError` 로 표면화한다. +- 결정론 테스트용 stub/in-memory 원장 구현을 제공해 네트워크 없이 체결→기록 lifecycle 을 검증할 수 있게 한다. +- 어댑터 자격증명/URL 은 .env(REQ-010 패턴, `TREX_PORTFOLIO_HUB_*`)로 주입한다. + +## Acceptance Criteria +1. Given in-memory stub 원장, When `record_trade(...)` 를 1회 호출, Then 원장에 거래 1건이 적재되고 인자(asset_id/side/qty/price/fee/tax/executed_at)가 보존된다. +2. Given portfolio-hub 어댑터, When `record_trade(...)`, Then `POST /v1/assets/{asset_id}/ledger/trades` 가 `execution_id` 를 포함해 호출된다(요청 계약은 orbit `post_ledger_trade` 와 동일). +3. Given portfolio-hub 가 409(중복/충돌)를 반환, When 어댑터가 응답을 처리, Then `LedgerConflictError` 로 표면화된다(예외를 삼키지 않는다). +4. Given 정적 import 스윕, When `trex_core/domain` 을 점검, Then portfolio-hub/네트워크 의존이 0 이다(LedgerPort 는 application 계약, 어댑터는 adapters 레이어 격리). (NFR-1) + +## Impacted Area +- Docs: docs/interface-contract.md(LedgerPort), docs/project-structure.md(ledger 어댑터) — REQ-020 에서 정합 +- Modules: 신규 `trex_core/application` LedgerPort 계약, 신규 `trex_core/adapters/ledger`(portfolio-hub 어댑터 + stub), `trex_core/runtime/config.py`(portfolio-hub URL/토큰) +- Tests: stub 원장 record_trade 단위테스트, 어댑터 요청 계약/409 처리 테스트, 도메인 import 스윕 + +## Notes +- 출처: dcy-004 FR-1, NFR-1. +- A-1 가정: portfolio-hub 는 orbit 과 동일 계약(`POST /v1/assets/{asset_id}/ledger/trades`, execution_id 멱등, 409 conflict)을 제공한다. 실제 계약/자격증명 검증은 dcy-004 confirm 시 REQ/delivery evidence 로 위임(비차단)됨 — 구현/검증 시 수집. +- 도메인 순수성(NFR-1)을 별도 REQ 로 승격하지 않고 본 REQ 의 AC-4(import 스윕)로 흡수한다. + +## Change Log + +### CHG-20260604-01 +- Date: 2026-06-04 +- Author: Justin Ko + +#### Change Summary +- dcy-004 FR-1 로부터 최초 생성(Proposed). NFR-1(도메인 순수성) 흡수. + +#### Intent +- 체결을 외부 원장에 기록하기 위한 LedgerPort 계약 + portfolio-hub 어댑터 + 결정론 stub 을 backlog 로 정규화. + +#### Acceptance Criteria Delta +- Added: + - stub record_trade 적재, 어댑터 POST 계약, 409→LedgerConflictError, 도메인 import 스윕 4개 기준 +- Updated: + - 없음 +- Removed: + - 없음 + +#### Impacted Area Delta +- Docs: + - docs/interface-contract.md, docs/project-structure.md +- Modules: + - LedgerPort 계약, portfolio-hub 어댑터 + stub, config +- Tests: + - stub/어댑터/도메인 import 스윕 테스트 + +#### 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 +- stub 원장 단위테스트 + 어댑터 요청 계약/409 테스트 + 도메인 import 스윕으로 검증. + +### CHG-20260604-02 +- Date: 2026-06-04 +- Author: Justin Ko + +#### Change Summary +- Status 변경: Proposed -> Approved. confirm-req 승인 게이트 통과. + +#### Intent +- LedgerPort 계약 + portfolio-hub 어댑터 + stub 원장을 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 에서 검증. diff --git a/docs/srs/Integration/req-018_fill-to-ledger-recording.md b/docs/srs/Integration/req-018_fill-to-ledger-recording.md new file mode 100644 index 0000000..9b8f5f7 --- /dev/null +++ b/docs/srs/Integration/req-018_fill-to-ledger-recording.md @@ -0,0 +1,116 @@ +# req-018: 체결→원장 기록 (집행 루프 fill hook) + +- Status: Approved +- Type: Integration +- Priority: High +- Owner: project maintainers + +## Intent +- 코어 집행 루프가 체결(매수/매도) 시 해당 거래를 portfolio-hub 원장에 기록하도록, fill 전이 경로에 ledger 기록 hook 을 더하고 체결 데이터(execution_id/fee)를 브로커 계약으로 운반한다. + +## Requirement +- 집행 루프가 매수 체결(`pending_buy→holding`)·매도 체결(`pending_sell→closed`) 시 LedgerPort 로 거래를 기록한다. ledger path 의 `asset_id` 는 슬롯 `portfolio_id`(= asset_id)를 직접 사용하고 side/qty/price/execution_id/fee/tax/executed_at 을 함께 보낸다. +- `FillStatus`(broker_port) 가 `execution_id` 와 `fee` 를 운반하도록 계약을 확장한다. `execution_id` 는 결정적으로 합성한다(KIS: `kis-daily-ccld:{ord_dt}:{ord_gno_brno}:{odno}:{tot_ccld_qty}`, paper: `paper:{broker_order_id}:{filled_qty}`). `fee` 는 BrokerPort fee 계산(orbit `calculate_fee(side, amount)` 패턴), `tax` 는 기본 0 으로 한다. +- 원장 기록 주체는 코어 집행 경로 단일로 한정한다(전략/도메인은 원장에 접근하지 않는다). + +## Acceptance Criteria +1. Given idle 슬롯에 매수 intent → 체결, When 집행 루프 fill 전이, Then 슬롯이 holding 으로 전이되고 원장에 buy 거래 1건이 기록된다(asset_id = 슬롯 portfolio_id). +2. Given holding 슬롯에 매도 intent → 체결, When 집행 루프 fill 전이, Then 슬롯이 closed 로 전이되고 원장에 sell 거래 1건이 기록된다. +3. Given 체결된 주문, When fill 을 읽음, Then `FillStatus` 가 결정적 `execution_id` 와 계산된 `fee`(tax=0)를 운반한다. +4. Given 슬롯에 `portfolio_id` 가 없는 체결, When fill 전이, Then 원장 기록을 건너뛰거나(또는 정의된 정책으로 처리) 슬롯 전이 자체는 정상 수행된다. +5. Given 전략/도메인 코드, When 점검, Then 원장 기록은 코어 집행 경로에서만 발생한다(단일 기록 주체). (NFR-3) + +## Impacted Area +- Docs: docs/runtime-flows.md(체결→원장 기록 흐름), docs/interface-contract.md(FillStatus 확장) — REQ-020 에서 정합 +- Modules: `trex_core/application/execution.py`(fill 전이에 ledger 기록 단계), `trex_core/application/broker_port.py`(FillStatus.execution_id/fee), `trex_core/adapters/broker/{paper,kis}.py`(execution_id 합성 + fee 계산) +- Tests: stub 원장으로 매수/매도 체결 시 buy/sell 1건 + 슬롯 전이, FillStatus execution_id/fee 운반, portfolio_id 부재 처리 + +## Notes +- 출처: dcy-004 FR-2, OQ-1(asset_id == portfolio_id, orbit 근거), OQ-3(execution_id/fee/tax 출처), NFR-3. +- OQ-1: 슬롯은 이미 buy intent 가 `portfolio_id` 를 공급해 캐시하므로 추가 매핑/조회 없이 path param 으로 사용한다. +- `portfolio_id` 부재 시 기록 skip vs 거부 정책은 구현 시 확정(AC-4 는 둘 다 허용하되 슬롯 전이 일관성을 요구). +- 멱등/무유실/재시도(correlation_id, outbox)는 REQ-019 에서 다룬다. 본 REQ 는 기록 호출 경로와 데이터 운반에 한정한다. + +## Change Log + +### CHG-20260604-01 +- Date: 2026-06-04 +- Author: Justin Ko + +#### Change Summary +- dcy-004 FR-2 로부터 최초 생성(Proposed). OQ-1/OQ-3 결정 반영, NFR-3(단일 기록 주체) 흡수. + +#### Intent +- 집행 루프 fill 전이에서 체결을 원장에 기록하는 경로와 FillStatus 확장(execution_id/fee)을 backlog 로 정규화. + +#### Acceptance Criteria Delta +- Added: + - 매수/매도 체결 기록+전이, FillStatus execution_id/fee, portfolio_id 부재, 단일 기록 주체 5개 기준 +- Updated: + - 없음 +- Removed: + - 없음 + +#### Impacted Area Delta +- Docs: + - docs/runtime-flows.md, docs/interface-contract.md +- Modules: + - execution.py(ledger hook), broker_port.py(FillStatus), paper/kis 어댑터(execution_id/fee) +- Tests: + - 체결→기록 통합테스트, FillStatus 운반, portfolio_id 부재 + +#### 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 +- stub 원장으로 매수/매도 체결 lifecycle 통합테스트 + FillStatus 확장 테스트로 검증. + +### CHG-20260604-02 +- Date: 2026-06-04 +- Author: Justin Ko + +#### Change Summary +- Status 변경: Proposed -> Approved. confirm-req 승인 게이트 통과. + +#### Intent +- 집행 루프 fill 전이의 ledger 기록 hook 과 FillStatus 확장을 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 에서 검증. diff --git a/docs/srs/index.md b/docs/srs/index.md index 23bbabc..0f16ef3 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -74,7 +74,7 @@ ## Next Requirement ID -- Current: `REQ-017` +- Current: `REQ-021` - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다. ## Requirement Register @@ -97,11 +97,15 @@ | REQ-014 | 주문 핸드오프 durability + reconciliation | Exception | Implemented | High | project maintainers | [req-014](./Exception/req-014_order-handoff-durability-reconciliation.md) | | REQ-015 | 브로커/집행 baseline 문서 정합 | Documentation | Implemented | Medium | project maintainers | [req-015](./Documentation/req-015_broker-execution-baseline-alignment.md) | | REQ-016 | KIS 인증 토큰 Redis 캐시 | Integration | Implemented | Medium | project maintainers | [req-016](./Integration/req-016_kis-token-redis-cache.md) | +| REQ-017 | LedgerPort 추상화 + portfolio-hub 어댑터 + stub | Integration | Approved | High | project maintainers | [req-017](./Integration/req-017_ledger-port-and-portfolio-hub-adapter.md) | +| REQ-018 | 체결→원장 기록 (집행 루프 fill hook) | Integration | Approved | High | project maintainers | [req-018](./Integration/req-018_fill-to-ledger-recording.md) | +| REQ-019 | ledger outbox durability + correlation_id 멱등 | Exception | Approved | High | project maintainers | [req-019](./Exception/req-019_ledger-outbox-durability-idempotency.md) | +| REQ-020 | ledger 레이어 baseline 문서 정합 | Documentation | Approved | Medium | project maintainers | [req-020](./Documentation/req-020_ledger-baseline-alignment.md) | ## Recent Change Log Summary +- 2026-06-04 :: REQ-017~020 Proposed -> Approved — 승인 게이트 통과. (confirm-req) +- 2026-06-04 :: REQ-017~020 최초 생성(Proposed) — dcy-004 FR-1~FR-5 분해(NFR-1~3 흡수). (draft-req) - 2026-06-04 :: REQ-016 생성 + Approved — KIS 토큰 Redis 캐시 (minor-change). (draft-req/confirm-req) - 2026-06-04 :: REQ-011~015 Approved → Implemented — BAT-004 verification evidence 기반. (confirm-req-implemented) - 2026-06-04 :: REQ-011~015 Proposed → Approved — 승인 게이트 통과. (confirm-req) -- 2026-06-04 :: REQ-011~015 최초 생성(Proposed) — dcy-003 FR-1~FR-6 분해. (draft-req) -- 2026-06-04 :: REQ-010 Approved → Implemented — BAT-003 verification evidence 기반. (confirm-req-implemented) \ No newline at end of file