# 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 가능.