Implement BAT-009 manual asset CRUD and snapshot close

docs/discovery/dcy-008_20260630_asset-snapshot-manual-valuation-system.md

@@ -7,7 +7,7 @@
 - 작성 시각(KST): 2026-06-30 20:38 KST
 - 마지막 갱신 시각(KST): 2026-06-30 21:17 KST
 - 대체됨: 없음
-- 후속 Discovery 참조: 없음
+- 후속 Discovery 참조: `docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md` (후속으로 미룬 manual asset CRUD·snapshot creation/mutation·월말 마감 운영 워크플로우를 독립 주기로 이어받음)
 - 생성된 REQ 참조: `REQ-009`, `REQ-010`
 
 # 1. 계획 상태 요약

docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md

@@ -0,0 +1,237 @@
+# 0. 문서 상태
+이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
+
+- 상태: confirmed
+- 문서 ID: dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow
+- 이슈명: 수기 자산 CRUD + 월말 스냅샷 생성/마감 운영 워크플로우
+- 작성 시각(KST): 2026-07-01 08:52 KST
+- 마지막 갱신 시각(KST): 2026-07-01 09:00 KST
+- 대체됨: 없음
+- 후속 Discovery 참조: 없음
+- 생성된 REQ 참조: `REQ-011`, `REQ-012`
+
+# 1. 계획 상태 요약
+현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
+
+- 연계 문서 현황:
+	- 선행 Discovery: dcy-008(`docs/discovery/dcy-008_20260630_asset-snapshot-manual-valuation-system.md`) — `asset_snapshots`/`manual_assets` 모델·평가 체계·조회성 MCP 범위를 confirmed로 확정하고, 스냅샷 생성·수기 자산 CRUD 같은 mutation MCP는 명시적으로 후속 범위로 분리함
+	- 관련 TODO/메모: `docs/data-model.md` 207행과 `docs/runtime-flows.md` 68·73·134행이 "manual asset CRUD와 snapshot creation MCP는 future scope / 후속 REQ 필요"라고 명시 보류
+- 해석:
+	- 현재 BAT-008 구현으로 `manual_assets`/`asset_snapshots` 스키마, 공유 평가 helper, 조회성 read model(`get_asset_snapshot_report`/`get_net_worth_timeseries`/`list_manual_assets`)은 존재하지만, 수기 자산을 등록·수정·삭제하거나 월말 스냅샷을 생성·마감하는 mutation 경로와 운영자 워크플로우가 없어 데이터가 채워지지 않으면 read model이 빈 폴백 상태로만 동작한다.
+	- 이번 Discovery는 dcy-008이 후속으로 미룬 manual asset CRUD, snapshot creation/mutation path, 월말 마감 운영자 워크플로우(preview/review, overwrite policy, basis-date 중복 처리)와 dashboard live vs snapshot source 명확화를 독립 주기로 정의한다.
+
+# 2. 요구사항 판정 결과
+이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
+
+- 판정: 신규
+- 근거
+	- 가장 근접한 dcy-008은 `asset_snapshots`/`manual_assets` 모델과 평가 체계, 조회(read) 중심 MCP 범위를 confirmed로 다루며 mutation MCP(스냅샷 생성·수기 자산 CRUD)를 Out of Scope로 명시 제외했다. 이번 요청은 그 제외된 mutation 경로와 월말 마감 운영 워크플로우를 신규로 정의하므로 dcy-008의 문구·측정 보강 수준 미세 조정이 아니다.
+	- dcy-008은 confirmed 상태로 REQ-009/REQ-010/BAT-008(구현 완료)까지 진행돼 read model 전제가 고정돼 있어, 쓰기 경로·overwrite/중복 정책·운영자 마감 절차 같은 새 책임을 같은 문서에 누적하면 책임 경계가 흐려진다. 후속 반복을 독립 주기로 추적하는 편이 명확하다.
+
+# 3. 문제점의 요약
+문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
+
+- 현재 상태
+	- `docs/data-model.md`(207행)와 `docs/runtime-flows.md`(73·134행)는 BAT-008이 `manual_assets`/`asset_snapshots`에 read-only MCP/report 지원만 추가했고 "snapshot creation/manual asset CRUD mutation MCP는 future scope"라고 명시한다. 즉 쓰기 경로가 의도적으로 비어 있다.
+	- `docs/runtime-flows.md`(67~73행) `Asset snapshot and net-worth read model` flow는 월말 수동 마감이 `asset_snapshots`에 항목 단위 행을 기록한다고 기술하지만, "BAT-008 stores the schema and service helper but does not expose snapshot creation as an MCP mutation"이라 실제 스냅샷 생성·마감을 수행하는 운영 경로가 없다.
+	- `docs/data-model.md`(85~86행)는 스냅샷 행이 BAT-008 기준 append-only이며 파괴적 덮어쓰기를 하지 않는다고만 규정할 뿐, 동일 basis-date 재마감 시 중복 처리·overwrite·정정 정책은 정의돼 있지 않다.
+	- `docs/runtime-flows.md`(51~52·71행) 기준 dashboard/read report는 live authority(`accounts.last_balance` + `manual_assets`)와 stored snapshot을 상황에 따라 섞어 쓰며, snapshot rows가 있으면 stored, 없으면 `source='live_authority'`로 폴백한다. 그러나 운영자/사용자가 화면에서 보는 값이 live인지 마감된 snapshot인지 구분·표기하는 규칙이 약하다.
+	- 관련 구현은 `jarca_ledger_mcp/service.py`(평가 helper·snapshot/timeseries read), `jarca_ledger_mcp/db.py`(`manual_assets`/`asset_snapshots` 스키마), `jarca_ledger_mcp/server.py`(조회성 MCP), `dashboard/app.py`(`get_asset_liquidity_report`)에 존재하나, 수기 자산 입력 UI/MCP write, 스냅샷 생성·마감 핸들러는 존재하지 않는다.
+	- `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/data-model.md`, `docs/interface-contract.md` baseline 문서는 read model까지만 반영하며 mutation 경로·운영자 마감 워크플로우를 아직 담지 않는다.
+- 기대 상태
+	- 사용자가 수기 자산/부채를 생성·수정·삭제(CRUD)할 수 있고, 각 변경이 기준일·출처 메모·`liquidity_bucket`과 함께 일관되게 검증·기록된다.
+	- 월말 마감 운영자 워크플로우가 정의돼, 마감 전 preview/review로 어떤 항목이 어떤 평가값으로 스냅샷될지 확인한 뒤 특정 basis-date의 자산 스냅샷을 생성·마감한다.
+	- 동일 basis-date 재마감, overwrite/정정, 중복 행 처리 정책이 단일 정의로 확정돼 이력 보존성과 정정 가능성이 양립한다.
+	- 대시보드/리포트가 표시하는 값이 live authority인지 마감된 snapshot인지 명확히 구분·표기되어 사용자가 "확정 마감값"과 "현재 추정값"을 혼동하지 않는다.
+- 이해관계자
+	- 월말에 자산/부채를 입력·마감하고 순자산 추이를 관리하는 사용자 겸 운영자(대시보드 1차 사용자)
+	- 문서/요구사항 리뷰어 및 승인자(Hermes/사용자)
+	- 데이터 모델·서비스·DB·MCP·대시보드 mutation 경로를 구현/운영하는 개발 담당자
+- 제약사항
+	- DB 스키마/데이터 변경은 additive/idempotent 원칙을 따르고, 파괴적 마이그레이션·일괄 덮어쓰기는 명시 승인·백업 후에만 한다(`docs/data-model.md` Persistence Notes, dcy-002 운영 안전장치).
+	- dcy-008/REQ-009·REQ-010 read model의 평가 권위 소스(`accounts.last_balance` + `manual_assets`)·순자산 산식(자산 합계 − `loan` 차감, 미평가 제외)과 충돌하지 않아야 한다.
+	- 신규 mutation MCP는 dcy-007/BAT-007에서 확정한 MCP response contract(성공/오류 envelope, contract versioning)와 정합해야 한다.
+	- 본 Discovery 단계에서는 소스 코드/테스트/스키마를 변경하지 않고 사양만 정의한다.
+
+## 주요 사용자 시나리오
+사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
+
+- 사용자가 새 전세보증금·예적금·대출 항목을 수기 자산으로 등록하고, 이후 평가값이 바뀌면 같은 항목을 수정하거나 더 이상 보유하지 않는 항목을 비활성/삭제한다.
+- 운영자가 월말 마감 시 "이번 달 말 기준으로 어떤 계좌·수기 자산이 어떤 평가값으로 스냅샷될지"를 preview로 검토한 뒤 해당 basis-date 스냅샷을 생성·마감한다.
+- 운영자가 이미 마감한 basis-date에 입력 오류를 발견해 재마감/정정을 시도할 때, 시스템이 중복 생성 대신 정해진 overwrite·정정 정책에 따라 처리하고 이력을 남긴다.
+- 사용자가 대시보드에서 특정 월 순자산을 볼 때, 그 값이 마감된 snapshot인지 아직 마감 전 live 추정값인지 화면 표기로 즉시 구분한다.
+
+# 4. 이번에 정의할 변경
+이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
+
+- 수기 자산 CRUD 경로 정의: `manual_assets` 항목의 생성·수정·삭제(또는 비활성)와 입력 검증(필수 필드: 자산명, 평가 금액, 기준일, `liquidity_bucket`, 출처 메모), 대시보드 입력 UI 및 조회성 외 mutation MCP 응답 계약을 사양으로 정의한다.
+- 월말 스냅샷 생성/마감 경로 정의: 특정 basis-date에 대해 live authority(`accounts.last_balance` + `manual_assets`)를 항목 단위로 고정해 `asset_snapshots`에 기록하는 생성·마감 핸들러와, 마감 전 preview/review(스냅샷될 항목·평가값·합계 미리보기) 단계를 정의한다.
+- overwrite/중복/정정 정책 정의: 동일 basis-date 재마감은 append-only를 유지하되 기존 마감값을 덮어쓰지 않고 정정 행을 추가하는 정책으로 확정한다. basis-date 중복 키는 "기존 마감 존재 + 정정 사유/근거 메모를 가진 추가 정정 실행"으로 처리하고, 정정 전 백업/승인 연계를 필수로 둔다.
+- live vs snapshot source 명확화: 대시보드/리포트/ MCP 응답이 표시값의 출처(`live_authority` vs stored snapshot)와 마감 여부를 명시적으로 구분·표기하도록 표기 규칙을 정의한다.
+- baseline 문서 반영: 위 mutation 데이터 흐름(CRUD, 스냅샷 생성/마감, preview, overwrite 정책, source 표기)을 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/interface-contract.md` 갱신 요구로 등록한다.
+
+## 영향 범위
+변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
+
+- 코드 영향:
+	- `jarca_ledger_mcp/db.py` 수기 자산 CRUD·스냅샷 생성/마감 write helper(additive, idempotent 키 처리), `jarca_ledger_mcp/service.py` 마감·preview·overwrite 정책 로직, `jarca_ledger_mcp/server.py` mutation MCP 도구(수기 자산 CRUD, 스냅샷 생성/마감) 및 dcy-007 response contract 정합.
+	- `dashboard/app.py` 수기 자산 입력/편집 UI, 월말 마감 preview/실행 화면, live vs snapshot source 표기.
+- 문서 영향:
+	- `docs/data-model.md`(스냅샷 overwrite/중복/정정 정책, `manual_assets` mutation 규칙), `docs/runtime-flows.md`(CRUD·스냅샷 생성/마감·preview 흐름, source 표기), `docs/project-structure.md`(mutation 경로 모듈), `docs/interface-contract.md`(mutation MCP 응답 계약) 갱신.
+	- dcy-008/REQ-009·REQ-010 read model 및 dcy-007 response contract와의 정합성 명시.
+- 운영 영향:
+	- 월말 마감 절차·수기 자산 입력 루틴이 운영 표준 워크플로우로 신설되며, 정정/재마감 시 백업·승인 절차(dcy-002)와 연계된다.
+
+# 5. 요구사항 목록
+실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
+
+## 기능 요구사항
+- FR-1: 수기 자산/부채 항목의 생성·수정·삭제(또는 비활성) 경로를 도입한다. 각 mutation은 필수 필드(자산명, 평가 금액, 기준일, `liquidity_bucket` ∈ `cash`/`investment`/`deposit`/`real_estate`/`loan`/`other`, 출처 메모)를 검증하고, 삭제는 이력 보존을 위해 비활성/soft delete를 기본 정책으로 확정한다. hard delete는 운영 복구가 불필요한 예외 정리 작업에 한해 별도 승인 하에서만 허용한다.
+- FR-2: 특정 basis-date에 대해 live authority(`accounts.last_balance` + 활성 `manual_assets`)를 항목 단위로 고정해 `asset_snapshots`에 기록하는 스냅샷 생성/마감 경로를 도입한다. 마감은 항목별 source_type(`account`/`manual_asset`)·source_id·평가값·`liquidity_bucket`을 capture 시점 기준으로 보존한다.
+- FR-3: 스냅샷 마감 실행 전 preview/review 단계를 제공한다. preview는 해당 basis-date에 스냅샷될 항목 목록·평가값·버킷별 합계·총자산·총부채·순자산을 마감 실행 없이 보여주고, 미평가/제외 항목을 경고로 표기한다.
+- FR-4: 동일 basis-date 재마감·중복·정정 정책을 단일 정의로 확정한다. 기본 정책은 append-only + 정정 행 추가이며, basis-date 중복 키는 overwrite가 아니라 정정 실행으로 처리한다. 정정 시에는 dcy-002 백업·승인 절차를 선행하고, 원본 마감 행과 정정 행이 함께 남아 기준일별 재현 가능성을 유지해야 한다.
+- FR-5: 대시보드/리포트/MCP 응답이 표시값의 출처를 명확히 구분한다. 각 자산·순자산 값이 stored snapshot 기반인지 `live_authority` 추정인지, 그리고 마감 여부를 응답 필드/화면 표기로 노출한다.
+- FR-6: 수기 자산 CRUD·스냅샷 생성/마감 mutation MCP 도구는 dcy-007/BAT-007의 MCP response contract(성공/오류 envelope, contract versioning)와 정합한 응답 계약을 따른다.
+- FR-7: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/interface-contract.md` baseline 문서에 수기 자산 CRUD·스냅샷 생성/마감·preview·overwrite 정책·source 표기 데이터 흐름 갱신을 포함한다.
+
+## 비기능 요구사항
+성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
+
+- NFR-1 (일관성): mutation 경로가 채운 값과 dcy-008 read model이 읽는 값은 동일한 평가 권위 소스·순자산 산식(자산 합계 − `loan` 차감, 미평가 제외)을 따라야 하며, 쓰기/읽기 간 산식 불일치가 없어야 한다.
+- NFR-2 (이력 보존성): 수기 자산 삭제와 스냅샷 정정은 과거 마감 기록을 파괴적으로 잃지 않도록 soft delete/이력 행을 기본으로 하고, 기준일별 재현 가능성을 보장한다.
+- NFR-3 (안전성): 스냅샷 생성/마감·정정 mutation은 additive/idempotent로 적용하고, dcy-002 백업·복구 안전장치와 연계해 재마감/정정 시 데이터 유실 위험을 통제한다.
+- NFR-4 (계약 안정성): 신규 mutation MCP 도구는 dcy-007 response contract 버전·envelope를 깨지 않고, contract-regression CI 범위에서 검증 가능해야 한다.
+
+## 범위 경계
+이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
+
+- In Scope
+	- 수기 자산 CRUD(생성/수정/삭제 또는 비활성) 사양과 입력 검증 규칙.
+	- 월말 스냅샷 생성/마감 경로, preview/review 단계, basis-date overwrite/중복/정정 정책.
+	- live vs snapshot source 표기 규칙 및 dcy-007 response contract 정합 mutation MCP 응답 계약.
+	- 위 흐름의 `docs/data-model.md`/`docs/project-structure.md`/`docs/runtime-flows.md`/`docs/interface-contract.md` 갱신 요구.
+- Out of Scope
+	- 외부 시세/부동산 평가 자동 연동, 실시간 잔액 연동, 자동 리밸런싱/세금·수익률 계산(dcy-008 Out of Scope 유지).
+	- 자산 스냅샷 자동 생성(스케줄러/cron) — 본 반복은 운영자 수동 마감 중심으로 한정하고, 월말 자동 스케줄링은 후속 반복으로 둔다.
+	- 본 단계에서의 실제 스키마/코드/테스트 변경(사양 정의만 수행).
+
+# 6. 리스크/가정 목록
+불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
+
+## 리스크
+- R-1 (High): 동일 basis-date 재마감/정정 정책이 모호하면 스냅샷 중복 행, 순자산 이중 집계, 과거 마감값 훼손이 발생할 수 있다.
+	- 완화 방안: FR-4에서 basis-date 중복 키 처리·overwrite/정정 규칙을 먼저 확정하고, 정정은 dcy-002 백업·승인 절차와 연계하며 append-only 이력과 양립하도록 REQ 초안에 명시한다.
+- R-2 (High): mutation 경로(쓰기)와 dcy-008 read model(읽기)이 서로 다른 권위 소스·산식을 쓰면 마감값과 화면 표시값이 어긋난다.
+	- 완화 방안: NFR-1로 공유 평가 helper/산식 단일화를 고정하고, 마감 직후 read report로 동일 basis-date 순자산이 일치하는지 검증을 성공 기준에 포함한다.
+- R-3 (Medium): 수기 자산 hard delete가 과거 스냅샷이 참조하는 source_id를 끊어 이력 재현을 깨뜨릴 수 있다.
+	- 완화 방안: FR-1/NFR-2에서 soft delete/비활성을 기본으로 하고, 스냅샷은 capture 시점 값을 자체 보존(`asset_snapshots` 복사 필드)하도록 정책을 명시한다.
+- R-4 (Medium): 신규 mutation MCP 도구가 dcy-007 response contract/contract-regression 범위와 어긋나면 CI 계약 게이트가 깨진다.
+	- 완화 방안: FR-6/NFR-4로 contract envelope 정합을 요구하고, mutation success/오류 envelope를 contract snapshot 범위에 포함하도록 REQ에 명시한다.
+
+## 가정
+아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
+
+- A-1: 평가 권위 소스(`accounts.last_balance` + `manual_assets`)와 순자산 산식은 dcy-008/REQ-009·REQ-010에서 확정된 정의를 그대로 계승하며, 이번 반복은 그 위에 쓰기 경로만 추가한다.
+- A-2: `asset_snapshots`는 dcy-008 기준 BAT-008에서 append-only로 도입돼 있으므로, 정정/overwrite는 기존 append-only 전제를 의도적으로 확장·재정의하는 변경이다.
+- A-3: 스냅샷 생성/마감은 초기 운영 정책상 운영자 수동 실행을 권위 경로로 확정하고, 자동 스케줄링은 후속 범위로 둔다.
+- A-4: mutation MCP는 dcy-007/BAT-007 response contract가 이미 mutation success envelope를 정의하고 있다는 전제를 재사용한다.
+
+## 오픈 질문
+답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
+
+- OQ-1: 동일 basis-date 재마감 시 정책을 무엇으로 확정할지(① append-only 유지 + 정정 행 추가, ② 기존 행 overwrite, ③ 차단 후 명시적 재마감 명령) 결정한다.
+	- 상태: Answered
+	- 답: 기본 정책은 append-only 유지 + 정정 행 추가로 확정한다. overwrite는 기본 경로에서 허용하지 않으며, 동일 basis-date 재마감은 정정 실행과 백업/승인 연계로 처리한다.
+	- 반영 위치: `# 4. 이번에 정의할 변경`, FR-4, NFR-2, NFR-3
+- OQ-2: 수기 자산 삭제 시맨틱을 soft delete(비활성)로 고정할지, 조건부 hard delete를 허용할지 결정한다.
+	- 상태: Answered
+	- 답: 기본 정책은 soft delete(비활성)로 확정한다. hard delete는 운영 복구가 불필요한 예외 정리 작업에 한해 별도 승인 하에서만 허용한다.
+	- 반영 위치: FR-1, NFR-2, R-3 완화 방안
+- OQ-3: 스냅샷 생성/마감을 운영자 수동에 한정할지, 본 반복에서 월말 자동 스케줄링까지 포함할지 결정한다.
+	- 상태: Answered
+	- 답: 본 반복은 운영자 수동 마감에 한정하고, 월말 자동 스케줄링은 후속 반복으로 유지한다.
+	- 반영 위치: `# 4. 이번에 정의할 변경`, Out of Scope, A-3
+
+### 오픈 질문 처리 기준
+- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
+- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
+- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
+- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
+- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
+- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
+- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.
+
+# 7. 초기 성공 기준
+이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
+
+- S-1: 수기 자산 CRUD와 월말 스냅샷 생성/마감(preview 포함) 경로가 입력 검증·source_type 보존·dcy-007 response contract 정합을 포함해 사양으로 정의된다.
+- S-2: 동일 basis-date 재마감/중복/정정 정책과 수기 자산 삭제 시맨틱이 이력 보존성과 양립하는 단일 정의로 확정되고, 마감값과 dcy-008 read model 순자산이 같은 basis-date에서 일치하도록 검증 기준이 정의된다.
+- S-3: 대시보드/리포트/MCP가 표시값의 출처(live vs snapshot)와 마감 여부를 구분 표기하는 규칙이 정의된다.
+- S-4: 위 mutation 데이터 흐름이 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/interface-contract.md`에 반영되고, dcy-008 read model·dcy-007 contract와의 정합성이 문서로 확인된다.
+
+## 측정 방식 및 데이터 출처
+각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
+
+- S-1 측정 방식: CRUD·스냅샷 생성/마감/preview 사양이 필드·검증·응답 envelope 수준까지 REQ로 내릴 수 있는지 검토 / 데이터 출처: dcy-008 `manual_assets`/`asset_snapshots` 모델, dcy-007 response contract, `jarca_ledger_mcp/service.py`·`db.py`·`server.py`
+- S-2 측정 방식: 표본 basis-date 재마감·정정·삭제 케이스로 정책 결과와 read model 순자산 일치를 손검증과 비교 / 데이터 출처: `docs/data-model.md` 스냅샷 정책, `get_asset_snapshot_report`/`get_net_worth_timeseries` read model, dcy-005 순자산 정의
+- S-3 측정 방식: read report/대시보드 표기에 `source`(live_authority vs snapshot)·마감 여부 필드가 노출되는지 사양 검토 / 데이터 출처: `docs/runtime-flows.md` 71행 source 폴백 규칙, `docs/interface-contract.md`
+- S-4 측정 방식: baseline 문서 diff에서 CRUD·스냅샷 생성/마감·preview·overwrite 정책·source 표기·dcy-008/dcy-007 정합 반영 여부 확인 / 데이터 출처: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/interface-contract.md`
+
+# 8. REQ로 넘기기 전 확인 체크
+REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
+
+- [x] 범위(In Scope/Out of Scope) 확정
+	- 기준: 수기 자산 CRUD·스냅샷 생성/마감/preview 포함 범위와 자동 스케줄링 제외 여부가 사용자 confirm으로 확정됐는가.
+- [x] 성공 지표의 측정 방식/데이터 출처 확정
+	- 기준: S-1~S-4 검수 방식과 데이터 출처가 REQ 초안으로 내릴 수 있을 정도로 정의됐는가.
+- [x] High 영향 리스크 우선순위 및 해소 정책 확정
+	- 기준: R-1(재마감/정정 정책)·R-2(쓰기/읽기 산식 정합) 해소 정책이 Discovery 범위에서 확정됐고, 세부 구현 책임자 지정은 REQ/batch planning 단계로 이관한다.
+- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
+	- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료.
+- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
+	- 기준: 사용자가 overwrite 정책·삭제 시맨틱·자동화 범위 결정을 승인하고 confirm을 지시했는가.
+
+# 9. 파일 처리 결과
+이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
+
+- 처리 결과: 생성
+- 생성 경로: docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md
+- 참조 문서:
+	- docs/discovery/dcy-008_20260630_asset-snapshot-manual-valuation-system.md (선행 Discovery; read model·평가 체계 확정 및 mutation MCP 후속 보류 출처)
+	- docs/data-model.md (`manual_assets`/`asset_snapshots` 모델, append-only/source_type 보존 규칙, mutation·overwrite 정책 갱신 대상; stage-pilot/templates/project-structure.md를 논리 템플릿 참조로 사용)
+	- docs/runtime-flows.md, docs/project-structure.md, docs/interface-contract.md (CRUD·스냅샷 생성/마감·preview·source 표기 흐름/응답 계약 갱신 대상; stage-pilot/templates/runtime-flows.md, stage-pilot/templates/project-structure.md를 논리 템플릿 참조로 사용)
+	- docs/discovery/dcy-007_20260630_mcp-response-contract-ci-contract-versioning.md (mutation MCP 응답 계약 정합 근거)
+	- docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md (정정/재마감 시 백업·승인 안전장치 연계)
+	- jarca_ledger_mcp/service.py, jarca_ledger_mcp/db.py, jarca_ledger_mcp/server.py, dashboard/app.py (현재 read model·평가 helper 구현 근거)
+
+# 10. 사용자 결정 필요 항목 요약
+사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
+
+## DECIDE
+- DECIDE_SNAPSHOT_OVERWRITE_POLICY: append-only + 정정 행 추가로 확정. overwrite는 기본 경로에서 허용하지 않고, 동일 basis-date 재마감은 정정 실행 + 백업/승인 연계로 처리한다.
+- DECIDE_MANUAL_ASSET_DELETE_SEMANTICS: soft delete(비활성)를 기본으로 확정. hard delete는 운영 복구가 불필요한 예외 정리 작업에 한해 별도 승인 하에서만 허용한다.
+- DECIDE_AUTO_SNAPSHOT_SCHEDULING: 본 반복 범위에서는 제외하고, 월말 자동 스케줄링은 후속 반복으로 둔다.
+
+## CONFIRM
+- CONFIRM_SOURCE_LABELING: 대시보드/리포트/MCP는 모든 자산·순자산 응답에 `source`(`live_authority` 또는 `snapshot`)와 `is_closed_snapshot`를 명시하고, 화면에서도 마감값/실시간 추정값을 구분 표기하는 방향으로 확정.
+- CONFIRM_MUTATION_MCP_CONTRACT: 수기 자산 CRUD·스냅샷 생성/마감 mutation MCP 응답은 dcy-007 contract envelope를 따르고 contract-regression 범위에 포함하는 방향으로 확정.
+
+## DATA
+- DATA_MONTH_END_CLOSE_ROUTINE: 실제 월말 마감 운영 루틴(마감 시점, 입력 책임자, 정정 빈도)은 REQ/delivery 단계 입력 데이터로 수집한다. Discovery confirm의 차단 항목으로 남기지 않는다.
+
+# 11. Discovery Freeze
+REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
+
+## 섹션 참조
+- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
+- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
+- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
+- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
+- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
+
+## Freeze 플래그
+- Handoff Decision: 승인
+- Handoff Rationale: 권장안 기준으로 append-only + 정정 행 정책, soft delete 기본, 자동 스케줄링 후속 분리, source 표기, mutation MCP contract 정합 방향을 모두 확정했다. 월말 운영 루틴의 실제 입력 데이터는 REQ/delivery 단계 수집 항목이며 REQ 초안 작성을 막지 않는다.
+- Ready for REQ Drafting: true
+- Confirmed By: 진환 고
+- Confirmed At (KST): 2026-07-01 08:59 KST

docs/discovery/index.md

@@ -14,3 +14,4 @@
 | dcy-006_20260630_pytest-apptest-smoke-ci-automation | 20260630 | pytest/AppTest/Smoke CI 자동화 | [Discovery](./dcy-006_20260630_pytest-apptest-smoke-ci-automation.md) | confirmed |
 | dcy-007_20260630_mcp-response-contract-ci-contract-versioning | 20260630 | MCP response contract / CI contract versioning 정립 | [Discovery](./dcy-007_20260630_mcp-response-contract-ci-contract-versioning.md) | confirmed |
 | dcy-008_20260630_asset-snapshot-manual-valuation-system | 20260630 | 자산 스냅샷/수기 자산 테이블/평가 체계 정립 | [Discovery](./dcy-008_20260630_asset-snapshot-manual-valuation-system.md) | confirmed |
+| dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow | 20260701 | 수기 자산 CRUD + 월말 스냅샷 생성/마감 운영 워크플로우 | [Discovery](./dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md) | confirmed |