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,69 @@
+# BAT-024 Design
+
+## 결정해야 할 구현 설계점
+
+### D-1: reversal target / confirmation metadata 저장 위치
+
+REQ-056은 `target_ledger_entry_id` 필수와 confirmation evidence 저장을 요구한다. 구현 전 아래 중 하나를 선택한다.
+
+- Option A: 기존 metadata/note/context 필드가 있다면 구조화된 JSON metadata로 저장
+- Option B: `portfolio_ledger`에 컬럼 추가(`target_ledger_entry_id`, `source`, `confirmation_metadata`) — migration 필요
+- Option C: note에만 저장 — 감사성이 약하므로 비권장
+
+권장: 기존 구조화 metadata가 없고 중복 reversal을 DB 수준에서 검증해야 한다면 Option B를 설계하고 migration을 batch에 포함하되, 운영 DB 적용은 release gate에서 별도 승인한다.
+
+### D-2: manual endpoint shape
+
+```http
+POST /v1/portfolios/{portfolio_id}/ledger/manual
+```
+
+단일 action-dispatch body:
+
+```json
+{
+  "action": "BUY",
+  "amount": null,
+  "quantity": 10,
+  "price": 80000,
+  "fee": 100,
+  "tax": 0,
+  "target_ledger_entry_id": null,
+  "note": "manual buy",
+  "confirm_daemon_managed_manual_write": false,
+  "confirmation_evidence": null
+}
+```
+
+### D-3: response shape
+
+```json
+{
+  "ledger_entry_id": "...",
+  "portfolio_id": "...",
+  "action": "BUY",
+  "source": "manual",
+  "cash_balance_after": 199900,
+  "asset_quantity_after": 10,
+  "profit_buffer_after": 0,
+  "total_value_after": 999900,
+  "recorded_at": "..."
+}
+```
+
+### D-4: error codes
+
+- 403: non-owner or service-token manual endpoint access
+- 409 `PORTFOLIO_DISABLED`
+- 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION`
+- 409 `INSUFFICIENT_CASH`
+- 409 `INSUFFICIENT_QUANTITY`
+- 409 `INSUFFICIENT_BUFFER`
+- 409 `LEDGER_ENTRY_ALREADY_REVERSED`
+- 422: invalid action/field/value
+
+### D-5: verification strategy
+
+- API TestClient tests for AC-1~17.
+- repository/concurrency test for row lock/lost update when feasible.
+- regression tests for existing `/ledger/trades`, list/read, CLI/domain flows.