100 lines
6.7 KiB
Markdown
100 lines
6.7 KiB
Markdown
# REQ-011 Manual asset CRUD / month-end snapshot write model
|
|
|
|
- Status: Implemented
|
|
- Type: Data
|
|
- 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. 배경
|
|
|
|
REQ-009/REQ-010은 `manual_assets`, `asset_snapshots`, 조회성 MCP, 대시보드 정렬까지 구현했지만 쓰기 경로는 의도적으로 제외했다. 현재는 read model과 평가 helper는 존재하지만, 수기 자산을 생성·수정·비활성 처리하거나 특정 기준일 자산 상태를 마감해 `asset_snapshots`에 확정하는 1급 운영 경로가 없다. dcy-009 confirmed Discovery에 따라 write model, 재마감 정책, 이력 보존 규칙을 구현 가능한 데이터/서비스 요구사항으로 고정해야 한다.
|
|
|
|
## 2. Intent
|
|
|
|
수기 자산 CRUD와 월말 마감 스냅샷 생성을 임시 수기 절차가 아니라 명시적 저장 계층/서비스 계층 기능으로 정립한다. 이 REQ의 목적은 `manual_assets` write lifecycle, preview 입력 모델, `asset_snapshots` append-only correction 정책, soft delete 원칙, 백업/승인 연계 안전장치를 구현 가능한 데이터 책임으로 고정하는 것이다.
|
|
|
|
## 3. 범위
|
|
|
|
### In Scope
|
|
- `manual_assets`의 생성/수정/비활성(soft delete) write model을 정의한다.
|
|
- 특정 `basis_date` 기준 live authority(`accounts.last_balance` + 활성 `manual_assets`)를 스냅샷 행으로 고정하는 month-end snapshot close write path를 정의한다.
|
|
- snapshot preview를 위한 집계/검증 데이터 모델과 warning shape를 정의한다.
|
|
- 동일 `basis_date` 재마감 시 `append-only + 정정 행 추가` 정책과 중복/정정 메타데이터 규칙을 정의한다.
|
|
- dcy-002 운영 안전장치와 정합한 백업/승인 연계 규칙을 정의한다.
|
|
- `docs/data-model.md`와 필요 baseline 문서에 write model 책임을 반영한다.
|
|
|
|
### Out of Scope
|
|
- 외부 시세/부동산 자동 평가 연동.
|
|
- 월말 자동 스케줄링/cron 생성.
|
|
- read-only MCP 응답 shape 자체의 상세 설계(별도 Interface REQ에서 다룸).
|
|
- 투자 조언/리밸런싱/세금/수익률 계산.
|
|
|
|
## 4. Requirement
|
|
|
|
### FR-1. Manual asset CRUD write lifecycle
|
|
- `manual_assets`는 create/update/deactivate 흐름을 지원해야 한다.
|
|
- 생성/수정 시 최소 필드 `name`, `valuation_amount`, `valuation_date`, `liquidity_bucket`, `source_note`를 검증해야 한다.
|
|
- 허용 `liquidity_bucket` 값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`다.
|
|
- 삭제 기본 정책은 hard delete가 아니라 비활성/soft delete여야 한다.
|
|
- hard delete는 운영 복구가 불필요한 예외 정리 작업에 한해 별도 승인 하에서만 허용되어야 한다.
|
|
|
|
### FR-2. Snapshot preview data model
|
|
- snapshot close 실행 전 preview는 해당 `basis_date`에 스냅샷될 계좌/수기 자산 항목 목록, 평가값, `liquidity_bucket`, source type, 합계, 경고를 계산할 수 있어야 한다.
|
|
- preview는 write side effect 없이 동작해야 한다.
|
|
- preview는 미평가/제외 항목, stale valuation, 중복 위험을 warning 형태로 드러낼 수 있어야 한다.
|
|
|
|
### FR-3. Month-end snapshot close write path
|
|
- snapshot close는 특정 `basis_date`의 live authority를 항목 단위 `asset_snapshots` 행으로 고정해야 한다.
|
|
- close 시 각 행은 `source_type`, `source_id`, `display_name`, `valuation_amount`, `liquidity_bucket`, `basis_date`, close 근거 메모를 보존해야 한다.
|
|
- close 결과는 이후 read model이 동일 산식으로 재구성 가능한 형태여야 한다.
|
|
|
|
### FR-4. Append-only correction policy
|
|
- 동일 `basis_date` 재마감 기본 정책은 overwrite가 아니라 `append-only + 정정 행 추가`여야 한다.
|
|
- 정정 실행은 기존 마감 행을 지우지 않고 correction 메타데이터(정정 사유, 정정 실행 시각, 정정 대상 basis_date)를 남겨야 한다.
|
|
- 정정 실행 전에는 dcy-002 기준 백업/승인 절차를 선행할 수 있어야 한다.
|
|
- read side는 최신 유효 마감 집합을 결정할 수 있도록 정정 계보를 추적할 수 있어야 한다.
|
|
|
|
### FR-5. Valuation/rule consistency
|
|
- write path는 REQ-009/REQ-010이 확정한 권위 소스(`accounts.last_balance` + `manual_assets`)와 순자산 산식(자산성 버킷 합계 − `loan`, 미평가 제외)을 그대로 따라야 한다.
|
|
- write path가 생성한 snapshot과 read model의 보고 결과는 동일 `basis_date`에서 일치 검증 가능해야 한다.
|
|
|
|
### FR-6. Baseline documentation alignment
|
|
- `docs/data-model.md`는 manual asset write lifecycle, soft delete semantics, correction metadata, snapshot close policy를 반영해야 한다.
|
|
- 필요 시 `docs/runtime-flows.md`, `docs/project-structure.md`는 preview → close → corrected-close 흐름과 write/read 책임 경계를 반영해야 한다.
|
|
|
|
## 5. Acceptance Criteria
|
|
|
|
- AC-1: 신규/기존 DB 모두에서 manual asset create/update/deactivate에 필요한 필드와 상태가 additive/idempotent하게 저장된다.
|
|
- AC-2: snapshot preview가 side effect 없이 항목 목록, bucket totals, total assets, total liabilities, net worth, warnings를 반환할 수 있다.
|
|
- AC-3: month-end snapshot close가 특정 `basis_date`의 authority source를 `asset_snapshots`에 항목 단위로 고정 저장한다.
|
|
- AC-4: 동일 `basis_date` 재마감은 overwrite 없이 correction append 정책으로 처리되고, 원본/정정 이력이 모두 보존된다.
|
|
- AC-5: manual asset soft delete와 snapshot correction이 있어도 REQ-009/REQ-010 read model은 동일 산식으로 일관된 결과를 낸다.
|
|
- AC-6: `docs/data-model.md`와 필요 baseline 문서가 본 REQ 범위를 반영한다.
|
|
|
|
## 6. Impacted Area
|
|
|
|
- `jarca_ledger_mcp/db.py`
|
|
- `jarca_ledger_mcp/service.py`
|
|
- `tests/test_asset_snapshots.py`
|
|
- 필요 시 `tests/test_service.py`
|
|
- `docs/data-model.md`
|
|
- 필요 시 `docs/runtime-flows.md`
|
|
- 필요 시 `docs/project-structure.md`
|
|
|
|
## 7. Notes
|
|
|
|
- 이 REQ는 write model, correction policy, persistence semantics를 다루므로 `Data` 타입으로 관리한다.
|
|
- MCP mutation contract와 operator UX는 `REQ-012`에서 다룬다.
|
|
- 월말 자동 스케줄링은 Discovery 결정에 따라 후속 범위로 유지한다.
|
|
|
|
## 8. Change Log
|
|
|
|
- 2026-07-01 09:00 KST: dcy-009 confirmed 범위를 바탕으로 Proposed 초안을 생성.
|
|
- 2026-07-01 09:02 KST: dcy-009 confirmed 결정사항(append-only correction, soft delete 기본, auto scheduling 후속)을 반영해 Approved로 전환.
|
|
- 2026-07-01 10:52 KST: BAT-009 구현, full pytest PASS, MCP tool discovery, browser smoke evidence를 근거로 Implemented로 전환.
|