97 lines
6.0 KiB
Markdown
97 lines
6.0 KiB
Markdown
# 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로 전환.
|