feat(api): add owner-scoped manual ledger endpoint

docs/data-model.md

@@ -290,6 +290,38 @@
 - Payload conflict detection: if unique key matches but payload differs → HTTP 409 Conflict.
 - portfolio_id is TEXT (not a FK) but must correspond to a valid portfolios.portfolio_id before insertion.
 
+
+
+## Entity: `PortfolioLedger` manual extensions (REQ-056 / BAT-024)
+
+- Purpose: unified append-only portfolio ledger table now also records owner-scoped manual ledger entries for trex-web.
+- Source of Truth: `portfolio_ledger` table.
+- Lifecycle: manual API appends rows with `source='manual'`; previous rows are never updated/deleted. Corrections use `REVERSAL` rows referencing a target ledger entry.
+
+### Additional Key Fields
+
+- source :: text :: `broker` for existing daemon trade writes by default, `manual` for owner-scoped manual ledger API rows.
+- target_ledger_entry_id :: bigint|null :: required for `REVERSAL`; references the reversed ledger entry logically.
+- confirmation_evidence :: text|null :: records API-level explicit confirmation evidence for daemon-managed portfolio manual writes.
+- actor_user_id :: text|null :: user/session actor that appended the manual ledger entry.
+
+### Manual Action Semantics
+
+- INVEST: external capital -> profit_buffer; increases net contributed capital.
+- WITHDRAW: profit_buffer -> external capital as contributed-capital withdrawal; decreases net contributed capital.
+- PROFIT: profit_buffer -> external capital as pure profit withdrawal; does not affect net contributed capital and is exposed separately as `cumulative_profit_withdrawn`.
+- BUFFER_OUT: profit_buffer -> cash_balance.
+- BUFFER_IN: cash_balance -> profit_buffer.
+- BUY: cash_balance -> asset_quantity.
+- SELL: asset_quantity -> cash_balance.
+- REVERSAL: append-only inverse effect of `target_ledger_entry_id`.
+
+### State Rules
+
+- Manual writes lock the portfolio row while calculating/appending/updating snapshots to avoid lost updates.
+- Manual writes reject insufficient cash/quantity/buffer with HTTP 409 rather than creating a new negative state.
+- `total_value_after` for manual entries is the portfolio snapshot value after the mutation and includes cash, asset valuation, and profit buffer.
+
 ## Shared Consistency Rules
 
 - auth_tokens.user_id and portfolios.owner_user_id should resolve to existing users before protected flows run.
@@ -317,6 +349,7 @@
 
 ## Change Log
 
+- 2026-07-14 KST: BAT-024 (REQ-056) — documented portfolio_ledger manual extensions (`source`, `target_ledger_entry_id`, `confirmation_evidence`, `actor_user_id`) and PROFIT/WITHDRAW return semantics.
 - 2026-05-21 KST: BAT-010 (REQ-032) — v1 portfolio surface 데이터 모델 보강: Portfolio.status 필드 신설 (`"enabled"` | `"disabled"` 의미, soft delete 정책); Portfolio.managed_by_daemon_id에 soft delete 시 NULL 설정 명시; tag_ids 소프트 삭제 보존 정책 추가; Portfolio State Rules에 disabled 상태 정책 + 의존 데이터 보존 + 상태 복원 규칙 추가; Source Discovery/Batch 헤더 갱신.
 - 2026-05-21 KST: BAT-008 (REQ-019) — 토큰 surface 정합성 회복: AuthToken token_type "client" 제거 반영; idx_auth_tokens_service_name_unique에 AND revoked_at IS NULL 조건 추가(REQ-017); Daemon 비활성화 시 바인딩 서비스 토큰 자동 revoke 정책 반영(REQ-022); User/AuthToken Purpose 문구 갱신.
 - 2026-05-20 KST: bat-005 — REQ-008 AC-1: added Entity: Tag (tags master table, BAT-003 migration 20260519_0017); updated Portfolio.tag_ids UUID[] field; removed portfolio_tags table note; updated Portfolio Relationships and State Rules; updated Model Summary.