[verified] Implement account valuation history for issue 12

docs/interface-contract.md

@@ -259,3 +259,130 @@ Set-Cookie: __Host-jarca_dashboard_auth=; Max-Age=0; Secure; HttpOnly; SameSite=
 AppTest는 callback, query mapping, synthetic renderer output과 error/loading event를 검증하지만 실제 browser의 document navigation 부재, paint timing, focus/scroll, network request 또는 perceived shell continuity를 증명하지 않는다. 따라서 `REQ-002.03-AC01`은 authenticated real-browser evidence가 필수이며 AppTest는 companion evidence일 뿐이다. history/back-forward와 path URL은 계약에서 제외한다.
 
 상세 acceptance target은 `docs/requirements/req-002_dashboard-menu-transition.md`의 `REQ-002.01-AC01`부터 `REQ-002.09-AC01`까지를 따른다.
+
+## 계좌 평가·자산 마감 계약 — REQ-003
+
+### valuation-service
+
+- 책임: `register_account_valuation()`, `list_account_valuations()`, `select_account_valuation()`, `correct_account_valuation()`을 통해 exact/as_of verified leaf와 append-only history를 제공한다.
+- 종류·프로토콜: Python service function; `jarca_ledger_mcp.service` re-export
+- 호출 대상·operation: `jarca_ledger_mcp.application.account_valuation_service`
+- 버전: additive v1
+- 호출 주체: Dashboard accounts gateway, MCP tool, import/account write service
+- 인증 방식: service layer 자체 MCP auth는 주장하지 않음; Dashboard는 기존 `gate` 선행
+- 필요 권한: caller가 DB path와 approval context를 제공
+
+#### 입력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 기본값 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|---|
+| `account_id`/`basis_date`/`amount` | function/MCP | `string/string/int` | register 필수 | 없음 | account id, YYYY-MM-DD, exact integer | valuation identity/value | 아니오 |
+| `currency`/`valuation_kind`/`source_type`/`verification_status` | function/MCP | `string` | 선택 | KRW/balance/manual/unverified | actual enums in source | 아니오 |
+| `idempotency_key` | function/MCP | `string` | 선택 | `''` | stable caller key | retry identity | 아니오 |
+| `as_of_at`/`timezone`, optional metrics, loan definition | function/MCP | nullable string/int/float | 선택 | NULL | source validation; loan definition required | evidence metrics | 아니오 |
+
+#### 출력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|
+| `success` | envelope | `bool` | 항상 | true/false | outcome | 아니오 |
+| `valuation`/`valuations` | result | object/list | 성공 시 | persisted rows | history/evidence | source_ref may be sensitive |
+| `reused`, `carried_forward`, `warning`, `unverified_candidates` | result | bool/string/list | 조건부 | additive | idempotency/selection evidence | 아니오 |
+
+#### 오류
+
+| 코드 | 분류 | 발생 조건 | 재시도 가능 여부 | 호출자 대응 | 실패 시 상태 변경 |
+|---|---|---|---|---|---|
+| `validation_error` | request | invalid date/type/currency/loan definition | 수정 후 가능 | payload 수정 | 없음 |
+| `not_found` | lookup | account/valuation missing | 수정 후 가능 | id 확인 | 없음 |
+| `idempotency_conflict` | conflict | same key different payload | 아니오 | new key or inspect | 없음 |
+| `correction_conflict`/`ambiguous_valuation` | conflict | second child/multiple leaves | 수동 검토 | correct evidence | 없음 |
+
+### snapshot-close
+
+- 책임: `preview_asset_snapshot_close()` is read-only; `close_asset_snapshot()` writes an immutable run and rows.
+- 종류·프로토콜: Python service, Streamlit `assets_gateway`, MCP tools
+- 호출 대상·operation: `jarca_ledger_mcp.application.assets_service`
+- 버전: additive v1
+- 호출 주체: authenticated Dashboard operator or MCP caller
+- 인증 방식: Dashboard existing auth gate; MCP authentication is outside this contract
+- 필요 권한: close conditional approval fields when warnings require it
+
+#### 입력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 기본값 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|---|
+| `basis_date`/`selection_policy` | function/MCP/form | `string/string` | basis optional | today/exact | YYYY-MM-DD, exact/as_of | close scope | 아니오 |
+| `idempotency_key`/`correction_reason` | function/MCP/form | `string` | conditional | empty | stable key; reason on re-close | retry/correction | 아니오 |
+| `allow_missing_exclusions`/`allow_as_of_carry_forward` | function/MCP | `bool` | optional | false | explicit flags | conditional approval need | 아니오 |
+| `approved_by`/`approval_reason`/`approval_reference` | function/MCP/form | `string` | conditional | empty | all required together | approval evidence | 아니오 |
+
+#### 출력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|
+| `source`/`is_closed_snapshot`/`snapshot_run_id` | result | string/bool/string | success | live_authority/snapshot | preview vs close | 아니오 |
+| `close_status`/`selection_policy`/`warnings` | result | string/string/list | success | complete_exact/incomplete_draft/conditional | authority state | 아니오 |
+| `total_assets`/`total_liabilities`/`net_worth` | result | integer | success | exact integer | formula summary | 아니오 |
+
+#### 오류
+
+| 코드 | 분류 | 발생 조건 | 재시도 가능 여부 | 호출자 대응 | 실패 시 상태 변경 |
+|---|---|---|---|---|---|
+| `conditional_approval_required` | policy | unsafe exclusions/carry-forward without explicit approval | 수정 후 가능 | preview, approve explicitly | 없음 |
+| `idempotency_conflict` | conflict | close key payload differs | 아니오 | inspect run | 없음 |
+| `validation_error` | request | invalid policy or unreasoned correction | 수정 후 가능 | provide reason | no partial rows |
+
+### shared contract and adapter limits
+
+All new interfaces retain the existing `success`/`error_code` envelope. `preview_asset_snapshot_close()` and Dashboard render/report are read-only; only explicit register/update/close forms or MCP calls write. MCP tools are `register_account_valuation`, `list_account_valuations`, `select_account_valuation`, `correct_account_valuation`, `preview_asset_snapshot_close`, `close_asset_snapshot`, `get_asset_snapshot_report`, and `get_net_worth_timeseries`; actual decorators are in `jarca_ledger_mcp/adapters/mcp/server.py`. Dashboard uses `accounts_gateway.py`, `assets_gateway.py`, and `page_views/accounts.py`/`assets.py`.
+
+## 호환성 추가 규칙 — REQ-003
+
+- 유지할 기존 호출 방식: REQ-001 auth config/login/cleanup/logout/gate, REQ-002 exact 10 menu labels/order, `page` query sibling preservation, stable shell/background and browser evidence; existing MCP stdio/streamable-http runtime.
+- 버전 변경 정책: additive fields only; no rename/removal of existing response keys.
+- 폐기 정책: 없음; guessed migration, fake transactions and MCP auth claim are excluded.
+- 재시도 계약: same idempotency payload reuses; changed payload conflicts; DB conflict does not retry blindly.
+- 중복 처리 계약: valuation/run idempotency keys and single correction indexes.
+- 순서 보장: Dashboard auth → DB path → page/gateway; preview → explicit approval → atomic close; selection → report.
+
+## 예시 추가
+
+### example-valuation — synthetic verified valuation
+
+- 대상 인터페이스: `valuation-service`
+
+#### 호출
+
+```text
+register_account_valuation(account_id="acct-synthetic", basis_date="2026-06-30", amount=1000000, verification_status="verified", idempotency_key="fixture-v1")
+```
+
+#### 결과
+
+```text
+{"success": true, "reused": false, "valuation": {"basis_date": "2026-06-30", "amount": 1000000, "verification_status": "verified"}}
+```
+
+### example-preview — read-only close preview
+
+- 대상 인터페이스: `snapshot-close`
+
+#### 호출
+
+```text
+preview_asset_snapshot_close(basis_date="2026-06-30", selection_policy="exact")
+```
+
+#### 결과
+
+```text
+{"success": true, "source": "live_authority", "is_closed_snapshot": false, "close_status": "complete_exact", "warnings": []}
+```
+
+## 검증 추가
+
+- 정상 계약: `tests/test_account_valuations.py`, `tests/test_asset_snapshots.py`, `tests/test_contract_regression.py`
+- 실패 계약: idempotency/correction/conditional approval tests and source validation
+- 경계 계약: exact/as_of, NULL/0, future/unverified candidate, correction/re-close
+- 구현·스키마·예시 정합성: `tests/test_requirement_docs.py`, actual service/MCP/gateway symbols