docs(batch): start manual ledger API delivery

2026-07-14 18:52:34 +09:00
parent 0c00f851e7
commit 762cf11376
6 changed files with 208 additions and 0 deletions
@@ -0,0 +1,47 @@
+# BAT-024 — owner-scoped 수동 장부 입력 HTTP API
+
+- Batch ID: BAT-024
+- Profile: standard
+- Status: in-progress
+- 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
+
+- [ ] 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이며 순입금액 계산에는 포함하지 않는다.