docs(discovery): require daemon-managed manual confirmation

docs/discovery/dcy-012_20260714_manual-ledger-write-api-owner-scoped.md

@@ -109,7 +109,7 @@
 - FR-10: manual ledger write 응답은 변경 후 snapshot을 포함해야 한다: 최소 `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`; `total_value_after` 포함 여부는 REQ에서 확정한다.
 - FR-11: manual ledger history 조회 API는 portfolio별 최근 ledger entries를 반환해야 한다. action, amount/quantity/price/fee/tax, note, recorded_at, after-snapshot을 trex-web이 표시할 수 있어야 한다.
 - FR-12: disabled portfolio write는 현행 state rule과 일관되게 거부한다.
-- FR-13: daemon-managed portfolio에 manual ledger write 시 완전 차단하지 않는다. 대신 response/request contract에 trex-web이 강한 경고와 명시 확인을 표현할 수 있는 정책을 포함한다.
+- FR-13: daemon-managed portfolio에 manual ledger write 시 완전 차단하지 않는다. 대신 API-level explicit confirmation을 요구한다. `managed_by_daemon_id IS NOT NULL`이고 confirmation flag가 없으면 HTTP 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION`을 반환한다. trex-web은 강한 경고를 표시한 뒤 사용자 명시 확인 시 confirmation flag를 포함해 재요청한다. 허용된 write는 actor, managed_by_daemon_id, confirmation evidence를 ledger/audit metadata에 남긴다.
 - FR-14: manual endpoint는 1차 범위에서 새 음수 상태를 만드는 write를 거부한다. `BUY`는 `quantity * price + fee + tax > cash_balance`이면 HTTP 409, `SELL`은 `quantity > asset_quantity`이면 HTTP 409, `BUFFER_OUT`/`WITHDRAW`는 `amount > profit_buffer`이면 HTTP 409, `BUFFER_IN`은 `amount > cash_balance`이면 HTTP 409로 거부한다. `INVEST`는 `amount > 0`이면 허용한다.
 
 ## 비기능 요구사항
@@ -145,8 +145,8 @@
   - 완화: API guard와 negative tests를 acceptance criteria에 포함한다.
 - R-2 (High): ledger row와 snapshot update가 분리되어 장부/상태 불일치 발생.
   - 완화: 단일 transaction + row lock + rollback tests.
-- R-3 (Medium): manual write와 daemon write가 같은 portfolio에서 혼재되어 운영자가 상태를 오해.
-  - 완화: source 분리, daemon-managed warning/explicit confirmation policy, history 표시.
+- R-3 (Mitigated): manual write와 daemon write가 같은 portfolio에서 혼재되어 운영자가 상태를 오해.
+  - 완화: source 분리, daemon-managed API-level explicit confirmation, history 표시. confirmation 없는 요청은 HTTP 409로 거부한다.
 - R-4 (Medium): 기존 CLI/domain 흐름과 신규 API 회계 공식이 divergence.
   - 완화: shared domain helper 추출 또는 동일 test vectors로 검증. manual API는 1차에서 부족 cash/quantity/buffer를 거부하므로 기존 CLI/domain validation 정책과 의도적 차이가 있다면 REQ에서 명시한다.
 - R-5 (Mitigated): `REVERSAL`이 target entry 참조 없이 notes 기반으로만 남아 audit성이 약해질 수 있음.
@@ -180,8 +180,12 @@
   - 근거: 수동 입력은 사전 검증 가능한 operation이고, `QUANTITY_ADJUSTMENT`를 1차 제외했으므로 부족 수량 SELL 허용은 우회 보정 기능이 될 수 있다.
   - 종료 조건: 완료
 - OQ-4: daemon-managed portfolio write 시 API가 `warning_required`/`confirmation_token` 같은 기계적 확인 필드를 요구할 것인가, 아니면 trex-web UI 경고만으로 충분한가?
-  - 상태: Open
-  - 종료 조건: API-level safety contract 확정
+  - 상태: Answered
+  - 결정: API-level explicit confirmation을 강제한다. daemon-managed portfolio(`managed_by_daemon_id IS NOT NULL`)에 confirmation 없는 manual write가 들어오면 HTTP 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION`을 반환한다. 사용자가 trex-web 경고를 확인한 뒤 confirmation flag를 포함해 재요청하면 허용한다.
+  - audit: 허용된 write는 actor_user_id, managed_by_daemon_id, confirmation reason/evidence를 ledger/audit metadata에 남긴다.
+  - 근거: UI 경고만으로는 API 직접 호출/우회/버그를 막을 수 없고, 자동/daemon 흐름과 수동 보정이 섞일 때 서버 측 감사 근거가 필요하다.
+  - REQ 세부화 항목: confirmation flag 이름, 409 error body, confirmation evidence 저장 위치(metadata JSONB vs note/context)를 확정한다.
+  - 종료 조건: 완료
 - OQ-5: history response에 `total_value_after`를 포함할 것인가?
   - 상태: Open
   - 종료 조건: trex-web display needs and existing schema 정합성 검토
@@ -211,7 +215,7 @@
 - [x] API endpoint shape 확정(OQ-1) — 기존 `/ledger/trades` 유지 + 신규 `POST /v1/portfolios/{portfolio_id}/ledger/manual` 추가
 - [x] REVERSAL target/reference policy 확정(OQ-2) — `target_ledger_entry_id` 필수
 - [x] 부족 잔고/수량 validation policy 확정(OQ-3) — manual write가 새 음수 상태를 만드는 것은 1차 거부
-- [ ] daemon-managed confirmation contract 확정(OQ-4)
+- [x] daemon-managed confirmation contract 확정(OQ-4) — API-level explicit confirmation 강제
 - [ ] history response fields 확정(OQ-5)
 - [ ] legacy `PROFIT` mapping policy 확정(OQ-6)
 - [ ] Scope owner: `portfolio-hub-dev` primary, `trex-web/service-dev` consumer, `qc-reviewer` verification
@@ -234,7 +238,7 @@
 - ~~API shape: 단일 action-dispatch endpoint vs action별 endpoint~~ → 기존 `/ledger/trades` 유지, 신규 `POST /v1/portfolios/{portfolio_id}/ledger/manual` + `action` enum 추가
 - ~~REVERSAL target ledger id/reference 필수 여부~~ → `target_ledger_entry_id` 필수
 - ~~부족 cash/quantity 시 validation 거부 vs 결과 음수 허용~~ → manual write는 부족 cash/quantity/buffer 409 거부, read/display 음수 표시는 허용
-- daemon-managed portfolio warning/confirmation을 API-level로 강제할지 UI-level로 둘지
+- ~~daemon-managed portfolio warning/confirmation을 API-level로 강제할지 UI-level로 둘지~~ → API-level explicit confirmation 강제
 - history response에 `total_value_after` 포함 여부
 - legacy `PROFIT` action 노출/매핑 정책
 
@@ -249,7 +253,7 @@
 
 # 11. Discovery Freeze
 - Handoff Decision: 보류(draft)
-- Handoff Rationale: trex-web dcy-011의 backend-first 후속 Discovery로 생성했다. 현행 portfolio-hub 구조와 action/effect는 확인했고, 기존 `/ledger/trades` 유지 + 신규 `/ledger/manual` 추가 방향은 확정했다. 남은 결정은 daemon-managed confirmation contract, history fields, legacy PROFIT mapping이다.
+- Handoff Rationale: trex-web dcy-011의 backend-first 후속 Discovery로 생성했다. 현행 portfolio-hub 구조와 action/effect는 확인했고, 기존 `/ledger/trades` 유지 + 신규 `/ledger/manual` 추가 방향은 확정했다. 남은 결정은 history fields, legacy PROFIT mapping이다.
 - Ready for REQ Drafting: false
 - Confirmed By: 미정
 - Confirmed At (KST): 미정