From 29bf6de22a5d957e65404ac6d757d6aae9caa4d0 Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Tue, 14 Jul 2026 15:33:03 +0900 Subject: [PATCH] docs(discovery): require reversal target ledger id --- ...14_manual-ledger-write-api-owner-scoped.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/discovery/dcy-012_20260714_manual-ledger-write-api-owner-scoped.md b/docs/discovery/dcy-012_20260714_manual-ledger-write-api-owner-scoped.md index 7d498c2..42c4520 100644 --- a/docs/discovery/dcy-012_20260714_manual-ledger-write-api-owner-scoped.md +++ b/docs/discovery/dcy-012_20260714_manual-ledger-write-api-owner-scoped.md @@ -148,8 +148,8 @@ - 완화: source 분리, daemon-managed warning/explicit confirmation policy, history 표시. - R-4 (Medium): 기존 CLI/domain 흐름과 신규 API 회계 공식이 divergence. - 완화: shared domain helper 추출 또는 동일 test vectors로 검증. -- R-5 (Medium): `REVERSAL`이 target entry 참조 없이 notes 기반으로만 남아 audit성이 약함. - - 완화: target ledger id/reference 필드 필요 여부를 REQ에서 결정. +- R-5 (Mitigated): `REVERSAL`이 target entry 참조 없이 notes 기반으로만 남아 audit성이 약해질 수 있음. + - 완화: 사용자 결정(2026-07-14)에 따라 `target_ledger_entry_id`를 필수로 한다. REQ에서는 컬럼/metadata 저장 위치와 중복 reversal 방지 규칙을 구체화한다. - R-6 (Low): `PROFIT` legacy action과 `BUFFER_IN`/`WITHDRAW` 의미가 사용자 UI에서 혼동. - 완화: 신규 user-facing API는 trex-web dcy-011 action taxonomy를 기준으로 명명하고, legacy CLI alias와 매핑을 문서화한다. @@ -167,8 +167,11 @@ - 근거: `/ledger/trades`는 trex-core/daemon/service-token broker 체결 보고이며, manual write는 user/session-token owner-scoped operation이다. auth/source/idempotency/audit 의미가 달라 HTTP endpoint는 분리한다. 단, 내부 회계 helper는 공유한다. - 종료 조건: 완료 - OQ-2: `REVERSAL`은 target ledger entry id를 필수로 둘 것인가? - - 상태: Open - - 종료 조건: audit/reference policy 확정 + - 상태: Answered + - 결정: `target_ledger_entry_id` 필수. REVERSAL은 기존 ledger row를 직접 수정/삭제하지 않고, 지정된 target entry의 반대 effect를 새 entry로 append한다. + - 근거: 감사 추적, 중복 reversal 방지, 서버 측 정확한 반대 effect 계산을 위해 target reference가 필요하다. + - REQ 세부화 항목: target이 같은 portfolio 소속인지 검증, 이미 reversed 된 entry의 재 reversal 금지 여부, REVERSAL 자체 reversal 허용 여부, target reference 저장 위치(정식 컬럼 vs metadata)를 확정한다. + - 종료 조건: 완료 - OQ-3: manual `BUY`/`SELL`에서 잔고/수량 부족을 거부할 것인가, 표시 음수 허용 정책과 맞춰 결과 음수를 허용할 것인가? - 사용자 정책: trex-web UI 입력 음수 금지, 기존/결과 표시 음수 허용. - 상태: Open @@ -203,7 +206,7 @@ # 8. REQ로 넘기기 전 확인 체크 - [x] API endpoint shape 확정(OQ-1) — 기존 `/ledger/trades` 유지 + 신규 `POST /v1/portfolios/{portfolio_id}/ledger/manual` 추가 -- [ ] REVERSAL target/reference policy 확정(OQ-2) +- [x] REVERSAL target/reference policy 확정(OQ-2) — `target_ledger_entry_id` 필수 - [ ] 부족 잔고/수량 validation policy 확정(OQ-3) - [ ] daemon-managed confirmation contract 확정(OQ-4) - [ ] history response fields 확정(OQ-5) @@ -226,7 +229,7 @@ # 10. 사용자 결정 필요 항목 요약 ## DECIDE - ~~API shape: 단일 action-dispatch endpoint vs action별 endpoint~~ → 기존 `/ledger/trades` 유지, 신규 `POST /v1/portfolios/{portfolio_id}/ledger/manual` + `action` enum 추가 -- REVERSAL target ledger id/reference 필수 여부 +- ~~REVERSAL target ledger id/reference 필수 여부~~ → `target_ledger_entry_id` 필수 - 부족 cash/quantity 시 validation 거부 vs 결과 음수 허용 - daemon-managed portfolio warning/confirmation을 API-level로 강제할지 UI-level로 둘지 - history response에 `total_value_after` 포함 여부 @@ -238,12 +241,12 @@ ## DATA - 현행 auth dependencies 중 session/user-token owner-scoped write에 가장 적합한 guard -- portfolio_ledger에 reversal target reference를 담을 별도 컬럼이 필요한지 여부 +- portfolio_ledger에 reversal target reference를 담을 별도 컬럼이 필요한지 여부 — OQ-2는 target id 필수로 결정, 저장 위치는 REQ에서 세부화 - existing tests coverage for CLI invest/transfer/buy/sell flows # 11. Discovery Freeze - Handoff Decision: 보류(draft) -- Handoff Rationale: trex-web dcy-011의 backend-first 후속 Discovery로 생성했다. 현행 portfolio-hub 구조와 action/effect는 확인했고, 기존 `/ledger/trades` 유지 + 신규 `/ledger/manual` 추가 방향은 확정했다. 남은 결정은 reversal reference, validation, 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` 추가 방향은 확정했다. 남은 결정은 validation, daemon-managed confirmation contract, history fields, legacy PROFIT mapping이다. - Ready for REQ Drafting: false - Confirmed By: 미정 - Confirmed At (KST): 미정