portfolio-hub/docs/batches/bat-024_20260714_manual-ledger-api/index.md

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

• Batch ID: BAT-024
• Profile: standard
• Status: implemented
• 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이며 순입금액 계산에는 포함하지 않는다.