gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
37d23b0c5f303151d88f5f771ce5b2d8a00026fd
jarca-ledger-mcp/docs/srs/Interface/req-012_manual-asset-crud-snapshot-close-mcp-and-operator-dashboard-alignment.md
T

6.0 KiB
Raw Blame History

REQ-012 Manual asset CRUD / snapshot close MCP and operator dashboard alignment

  • Status: Implemented
  • Type: Interface
  • Priority: High
  • Owner: 렛저장인
  • Source Discovery: docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md
  • Batch: BAT-009
  • Created At (KST): 2026-07-01 09:00 KST
  • Approved At (KST): 2026-07-01 09:02 KST
  • Implemented At (KST): 2026-07-01 10:52 KST

1. 배경

BAT-008은 조회성 MCP와 대시보드 read alignment까지 구현했지만, 운영자가 수기 자산을 입력·수정·비활성 처리하거나 월말 snapshot preview/close를 실행할 인터페이스는 남겨 두었다. dcy-009 confirmed Discovery는 mutation MCP와 operator dashboard UX가 동일 source 표기 규칙과 dcy-007 contract envelope를 따르면서 month-end close workflow를 제공해야 한다고 결정했다.

2. Intent

수기 자산 CRUD와 month-end snapshot close를 운영자가 실제로 사용할 수 있는 MCP mutation 및 대시보드 인터페이스로 정렬한다. 이 REQ의 목적은 preview/close/operator messaging/source labeling/contract regression 범위를 구현 가능한 인터페이스 요구사항으로 고정하는 것이다.

3. 범위

In Scope

  • manual asset create/update/deactivate mutation MCP를 정의한다.
  • snapshot preview/close mutation MCP를 정의한다.
  • 대시보드에 manual asset 관리와 month-end snapshot preview/close operator UX를 정의한다.
  • 모든 관련 응답/화면에 source와 is_closed_snapshot 표기를 정렬한다.
  • dcy-007 response contract/contract regression 범위에 신규 mutation MCP를 포함한다.
  • docs/interface-contract.md와 필요 baseline 문서를 갱신한다.

Out of Scope

  • 외부 자동 시세 연동 UI/MCP.
  • 월말 자동 스케줄링 UI/MCP.
  • 투자 조언/리밸런싱 추천 UX.
  • production DB 실데이터를 이용한 수동 운영 evidence.

4. Requirement

FR-1. Manual asset mutation MCP

  • manual asset create/update/deactivate MCP 도구를 제공해야 한다.
  • 응답은 dcy-007 contract envelope와 호환되어야 하며 성공/오류 시 일관된 top-level shape를 유지해야 한다.
  • create/update 결과는 최소한 식별자, 현재 상태(active/deactivated), 최근 평가 기준일, liquidity_bucket, source note를 돌려줄 수 있어야 한다.

FR-2. Snapshot preview/close MCP

  • 특정 basis_date에 대한 snapshot preview MCP를 제공해야 한다.
  • preview 응답은 side effect 없이 항목 목록, bucket totals, liabilities, net worth, warnings, source='live_authority', is_closed_snapshot=false를 설명할 수 있어야 한다.
  • snapshot close MCP는 close 완료 후 close metadata와 source='snapshot', is_closed_snapshot=true를 포함한 결과를 반환해야 한다.
  • correction close가 발생하면 overwrite가 아니라 correction run임을 응답에서 구분할 수 있어야 한다.

FR-3. Operator dashboard UX

  • 대시보드는 manual asset 추가/수정/비활성 입력 경로를 제공해야 한다.
  • 대시보드는 month-end snapshot preview와 close 실행 경로를 제공해야 한다.
  • 화면은 현재 값이 live authority 기반 추정인지, 닫힌 snapshot 기반인지 명시적으로 구분해야 한다.
  • correction/재마감이 있었으면 운영자가 그 사실을 인지할 수 있는 상태 문구 또는 메타데이터를 노출해야 한다.

FR-4. Dashboard/read alignment

  • mutation 실행 후 대시보드와 read MCP는 동일 authority source와 동일 순자산 산식을 반영해야 한다.
  • close 이전 preview와 close 이후 read report는 같은 basis_date 기준 동일 집계 규칙을 사용해야 한다.
  • 신규 write model이 비어 있거나 미사용 상태여도 기존 REQ-005/REQ-010 경로는 안전 폴백을 유지해야 한다.

FR-5. Contract regression and documentation alignment

  • 신규 mutation MCP는 tests/test_contract_regression.py 또는 동등 회귀 검증 범위에서 discovery/shape drift를 검출할 수 있어야 한다.
  • docs/interface-contract.md는 manual asset CRUD 및 snapshot preview/close의 request/response contract를 반영해야 한다.
  • 필요 시 docs/runtime-flows.md, docs/project-structure.md는 operator workflow와 UI/service/server 책임 경계를 반영해야 한다.

5. Acceptance Criteria

  • AC-1: manual asset create/update/deactivate MCP가 정의되고 dcy-007 envelope와 정합한 응답을 반환한다.
  • AC-2: snapshot preview MCP가 side effect 없이 preview totals/warnings/source flags를 반환한다.
  • AC-3: snapshot close MCP가 close metadata와 closed snapshot source flags를 반환하고 correction close를 구분한다.
  • AC-4: 대시보드가 manual asset CRUD와 month-end snapshot preview/close operator UX를 제공한다.
  • AC-5: 대시보드/read MCP/close 결과가 source 및 is_closed_snapshot 표기를 일관되게 유지한다.
  • AC-6: contract regression과 baseline 문서가 본 REQ 범위를 반영한다.

6. Impacted Area

  • jarca_ledger_mcp/server.py
  • jarca_ledger_mcp/service.py
  • dashboard/app.py
  • tests/test_contract_regression.py
  • 필요 시 tests/test_asset_snapshots.py
  • docs/interface-contract.md
  • 필요 시 docs/runtime-flows.md
  • 필요 시 docs/project-structure.md

7. Notes

  • 이 REQ는 MCP mutation contract와 operator-facing dashboard flow를 다루므로 Interface 타입으로 관리한다.
  • persistence semantics와 correction storage model은 REQ-011을 선행 입력으로 사용한다.
  • 실제 월말 운영 루틴 세부값(누가 언제 마감하는지)은 구현/운영 evidence 단계에서 수집한다.

8. Change Log

  • 2026-07-01 09:00 KST: dcy-009 confirmed 범위를 바탕으로 Proposed 초안을 생성.
  • 2026-07-01 09:02 KST: dcy-009 confirmed 결정사항(source/is_closed_snapshot 표기, mutation MCP contract 정합)을 반영해 Approved로 전환.
  • 2026-07-01 10:52 KST: BAT-009 구현, full pytest PASS, MCP tool discovery, browser smoke evidence를 근거로 Implemented로 전환.
View Git Blame Copy Permalink