portfolio-hub/docs/batches/bat-024_20260714_manual-ledger-api/planning.md

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