70 lines
1.9 KiB
Markdown
70 lines
1.9 KiB
Markdown
# 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.
|