# 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

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

## DoD

- [x] REQ-056 AC-1~19 테스트 전수 통과
- [x] 기존 `/ledger/trades`, `GET /v1/portfolios`, CLI/domain flow 회귀 없음
- [x] baseline docs(`interface-contract`, `runtime-flows`, `data-model`) 갱신
- [x] 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이며 순입금액 계산에는 포함하지 않는다.