gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
558bfd9dbd6d17ff952dd76be595d8a5f70265b4
jarca-ledger-mcp/docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md
T

27 KiB
Raw Blame History

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 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

  • 범위(In Scope/Out of Scope) 확정
    • 기준: 수기 자산 CRUD·스냅샷 생성/마감/preview 포함 범위와 자동 스케줄링 제외 여부가 사용자 confirm으로 확정됐는가.
  • 성공 지표의 측정 방식/데이터 출처 확정
    • 기준: S-1~S-4 검수 방식과 데이터 출처가 REQ 초안으로 내릴 수 있을 정도로 정의됐는가.
  • High 영향 리스크 우선순위 및 해소 정책 확정
    • 기준: R-1(재마감/정정 정책)·R-2(쓰기/읽기 산식 정합) 해소 정책이 Discovery 범위에서 확정됐고, 세부 구현 책임자 지정은 REQ/batch planning 단계로 이관한다.
  • 모든 오픈 질문(OQ) Open 상태 없음 확인
    • 기준: OQ 목록에 Open 상태 항목이 0개이거나, 잔여 항목 전부 Deferred 처리 완료.
  • 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 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

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
View Git Blame Copy Permalink