68 lines
2.8 KiB
Markdown
68 lines
2.8 KiB
Markdown
# BAT-024 Planning
|
|
|
|
## 구현 의존 순서
|
|
|
|
1. **현재 구조 재확인**
|
|
- `CLAUDE.md`, `README.md`, `pyproject.toml`
|
|
- `app/api/v1_portfolios.py`, `app/schemas/v1.py`
|
|
- `app/domain/services.py`, `app/repositories/postgres.py`, `app/repositories/portfolio_repository.py`
|
|
- auth dependency와 기존 `/ledger/trades` tests
|
|
2. **스키마/API 계약**
|
|
- `ManualLedgerRequest`, `ManualLedgerResponse`, history/summary response field 정의
|
|
- action enum: `INVEST`, `BUFFER_OUT`, `BUFFER_IN`, `BUY`, `SELL`, `WITHDRAW`, `PROFIT`, `REVERSAL`
|
|
3. **domain/repository 회계 helper**
|
|
- 기존 invest/transfer/buy/sell flow 재사용 또는 공통 helper 추출
|
|
- 부족 cash/quantity/buffer validation
|
|
- PROFIT vs WITHDRAW classification
|
|
- REVERSAL target lookup/opposite effect/dedup
|
|
4. **auth/route 구현**
|
|
- `POST /v1/portfolios/{portfolio_id}/ledger/manual`
|
|
- owner-scoped user/session token only
|
|
- service-token/daemon-token fail-closed
|
|
- disabled portfolio 409
|
|
- daemon-managed confirmation 409/allowed flow
|
|
5. **history/summary read 구현**
|
|
- history response에 `total_value_after`
|
|
- `cumulative_profit_withdrawn` 별도 지표
|
|
6. **baseline docs 업데이트**
|
|
- `docs/interface-contract.md`
|
|
- `docs/runtime-flows.md`
|
|
- `docs/data-model.md`
|
|
7. **tests**
|
|
- API AC-1~17
|
|
- repository/concurrency AC-18
|
|
- regression AC-19
|
|
|
|
## Task Breakdown
|
|
|
|
### T-1: Contract/schema
|
|
- manual request/response schema와 error body shape 작성.
|
|
- extra numeric fields는 schema 또는 validation에서 422로 실패.
|
|
|
|
### T-2: Accounting helper/repository
|
|
- ledger append + portfolio snapshot update를 단일 transaction/row lock으로 보장.
|
|
- accepted action만 허용하고 `QUANTITY_ADJUSTMENT`는 422.
|
|
- `target_ledger_entry_id` 저장 위치는 design에서 확정. migration 필요 시 별도 명시.
|
|
|
|
### T-3: Route/auth
|
|
- owner token만 허용.
|
|
- service-token/daemon-token은 manual endpoint 403.
|
|
- non-owner 403, disabled 409.
|
|
- daemon-managed confirmation 없으면 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION`.
|
|
|
|
### T-4: History/summary
|
|
- history items에 after-snapshot 4종 포함.
|
|
- summary/return response에 `cumulative_profit_withdrawn` 포함.
|
|
|
|
### T-5: Docs/tests/verification
|
|
- baseline docs 갱신.
|
|
- `uv run pytest` 또는 repo 표준 test command로 targeted + regression 수행.
|
|
- `verification.md`에 AC별 evidence 기록.
|
|
|
|
## Risks / Constraints
|
|
|
|
- Auth regression: existing daemon `/ledger/trades`와 user manual endpoint 권한을 혼동하면 보안 결함.
|
|
- Accounting regression: PROFIT/WITHDRAW effect는 유사하지만 performance classification이 다름.
|
|
- Migration risk: reversal/confirmation metadata를 기존 구조로 담을 수 없으면 migration이 필요하다.
|
|
- Concurrency risk: row lock 없이 simultaneous manual writes는 lost update 가능.
|