BAT-024 — owner-scoped 수동 장부 입력 HTTP API

Batch ID: BAT-024
Profile: standard
Status: release-candidate
Discovery: dcy-012_20260714_manual-ledger-write-api-owner-scoped
Included REQ: REQ-056
Folder: docs/batches/bat-024_20260714_manual-ledger-api/
Created: 2026-07-14

Summary

REQ-056 구현: trex-web이 user/session token으로 자기 소유 portfolio에 수동 장부 entry를 append/read할 수 있는 portfolio-hub v1 API를 추가한다.

기존 POST /v1/portfolios/{portfolio_id}/ledger/trades는 trex-core/daemon/service-token broker 체결 보고 전용으로 유지한다. 신규 manual API는 owner-scoped user/session token 전용으로 분리한다.

Included REQ

REQ	제목	Type	의존
REQ-056	owner-scoped 수동 장부 입력 HTTP API	Interface	dcy-012 confirmed, existing portfolio_ledger/snapshot model

DoR

dcy-012 confirmed by Justin Ko
REQ-056 Approved
기존 /ledger/trades 보존 정책 확정
action/effect, PROFIT/WITHDRAW 수익률 의미, confirmation, validation 정책 확정

DoD

REQ-056 AC-1~19 테스트 전수 통과
기존 /ledger/trades, GET /v1/portfolios, CLI/domain flow 회귀 없음
baseline docs(interface-contract, runtime-flows, data-model) 갱신
draft-batch-verification 문서에 AC별 PASS/FAIL evidence 기록
independent QC PASS 후 lead confirm-batch-verification

비가역 결재 게이트

DB migration 가능성: reversal target reference/confirmation metadata 저장 방식에 따라 migration 필요 가능. migration이 필요하면 design에서 명시하고, 운영 DB 적용은 release gate로 분리한다.
HTTP API 계약: 신규 additive endpoint. 기존 /ledger/trades semantics는 변경하지 않는다.
Security: owner-scoped write API 및 service-token fail-closed가 핵심 gate다.

Notes

QUANTITY_ADJUSTMENT는 1차 제외.
PROFIT은 신규 manual API 필수 action이며 순입금액 계산에는 포함하지 않는다.

Verification / Gate Result

Developer verification: PASS — 594 passed, 12 warnings in 37.24s.
Independent QC: PASS — delegation deleg_f2337a39, HEAD b3447f6, 594 passed, 12 warnings in 37.29s, focused remediation 4 passed.
Lead gate: confirm-batch-verification accepted 2026-07-14 KST.
REQ gate: confirm-req-implemented accepted for REQ-056.
Release note: Production rollout still requires release gate; Alembic migration/runbook for additive portfolio_ledger columns remains a release risk to decide before production DB rollout.

2.6 KiB Raw Blame History