diff --git a/dashboard/app.py b/dashboard/app.py index 4f53e3d..85f844d 100644 --- a/dashboard/app.py +++ b/dashboard/app.py @@ -649,6 +649,29 @@ def cancel_original_candidates_dialog(tx: dict[str, Any], db_path: str) -> None: st.divider() +def render_review_decision_actions(gateway: Any, target_type: str, target_id: str, key_prefix: str, db_path: str, target_payload: dict[str, Any] | None = None) -> None: + decision_type = st.selectbox( + "판정", + ["unknown", "account_transfer", "real_expense", "real_income", "investment_transfer", "excluded_from_analysis", "duplicate_or_cancel"], + key=f"{key_prefix}_decision_type", + ) + reason_code = st.text_input("사유 코드", value="operator_review", key=f"{key_prefix}_reason") + memo = st.text_input("결정 메모", value="", key=f"{key_prefix}_memo") + cols = st.columns(4) + if cols[0].button("결정 저장", key=f"{key_prefix}_decided", use_container_width=True, type="primary"): + res = gateway.upsert_review_decision(target_type, target_id, status="decided", decision_type=decision_type, reason_code=reason_code, memo=memo, target_payload=target_payload or {}, db_path=db_path) + clear_cache(); st.success("저장했습니다." if res.get("success") else res.get("error", res)); st.rerun() + if cols[1].button("보류", key=f"{key_prefix}_held", use_container_width=True): + res = gateway.hold_review_decision(target_type, target_id, reason_code=reason_code or "held", memo=memo, db_path=db_path) + clear_cache(); st.success("보류했습니다." if res.get("success") else res.get("error", res)); st.rerun() + if cols[2].button("재검토", key=f"{key_prefix}_recheck", use_container_width=True): + res = gateway.mark_review_recheck(target_type, target_id, reason_code=reason_code or "needs_recheck", memo=memo, db_path=db_path) + clear_cache(); st.success("재검토로 표시했습니다." if res.get("success") else res.get("error", res)); st.rerun() + if cols[3].button("해제", key=f"{key_prefix}_release", use_container_width=True): + res = gateway.release_review_decision(target_type, target_id, memo=memo, db_path=db_path) + clear_cache(); st.success("pending으로 해제했습니다." if res.get("success") else res.get("error", res)); st.rerun() + + RULE_MATCH_FIELDS = ["merchant", "raw_summary", "counterparty", "payment_method", "branch", "description", "memo"] RULE_MATCH_TYPES = ["contains", "equals", "starts_with", "ends_with", "regex"] RULE_TX_TYPES = ["", "income", "expense", "transfer", "refund", "adjustment"] @@ -888,6 +911,8 @@ def render_uncategorized_work_items(rows: list[dict[str, Any]], db_path: str, re linked_transfer_candidates_dialog(row, db_path) if action_cols[4].button("원거래찾기", key=f"uncat_cancel_{row['id']}_{idx}", use_container_width=True): cancel_original_candidates_dialog(row, db_path) + with st.expander(f"Review decision · 현재 {row.get('review_status', 'pending')}", expanded=False): + render_review_decision_actions(categorization_gateway, "uncategorized_transaction", row["id"], f"uncat_review_decision_{row['id']}_{idx}", db_path, target_payload=row) @@ -944,6 +969,8 @@ def page_overview(db_path: str) -> None: uncategorized_res = overview_gateway.list_uncategorized_transactions(limit=1000, db_path=db_path) transfer_queue_res = overview_gateway.list_cross_transfer_review_queue(limit=300, db_path=db_path) reconciliation_res = reconciliation_gateway.get_balance_reconciliation_report(db_path=db_path) + review_indicators_res = reconciliation_gateway.get_review_operating_indicators(db_path=db_path) + review_indicators = review_indicators_res.get("indicators", {}) if review_indicators_res.get("success") else {} backups_res = overview_gateway.list_ledger_backups(limit=1) imports_res = overview_gateway.list_ledger_import_batches(limit=1, db_path=db_path) @@ -1008,11 +1035,12 @@ def page_overview(db_path: str) -> None: reconciliation_items = reconciliation_res.get("items", []) if reconciliation_res.get("success") else [] reconciliation_review = [item for item in reconciliation_items if item.get("status") == "REVIEW_NEEDED"] missing_balance = asset_report.get("missing_balance_accounts", []) - w1, w2, w3, w4 = st.columns(4) - w1.metric("미분류 거래", f"{uncategorized_res.get('count', 0):,}건") - w2.metric("확인필요 큐", f"{len(review_items):,}건") - w3.metric("잔액대조 필요", f"{len(reconciliation_review):,}건") - w4.metric("잔액 미입력", f"{len(missing_balance):,}건") + w1, w2, w3, w4, w5 = st.columns(5) + w1.metric("미처리 review", f"{review_indicators.get('pending_review_count', len(review_items)):,}건") + w2.metric("보류/재검토", f"{review_indicators.get('held_recheck_count', 0):,}건") + w3.metric("미대조 계좌", f"{review_indicators.get('unreconciled_account_count', len(reconciliation_review)):,}개") + w4.metric("최근 대조 마감", review_indicators.get("last_reconciliation_closed_at") or "-") + w5.metric("미분류 추천 대기", f"{review_indicators.get('uncategorized_recommendation_backlog', uncategorized_res.get('count', 0)):,}건") latest_backup = (backups_res.get("backups") or [{}])[0] if backups_res.get("success") else {} latest_import = (imports_res.get("import_batches") or [{}])[0] if imports_res.get("success") else {} st.caption( @@ -1231,7 +1259,11 @@ def page_cross_transfer_review(db_path: str) -> None: for r in rows } selected = st.selectbox("수동 수정할 거래", list(options.keys())) - update_transaction_form(options[selected], "transfer_review", db_path) + selected_row = options[selected] + st.caption(f"현재 review_status: {selected_row.get('review_status', 'pending')}") + with st.expander("Review decision 저장/보류/재검토/해제", expanded=False): + render_review_decision_actions(transfers_gateway, "cross_transfer", selected_row["id"], f"transfer_review_decision_{selected_row['id']}", db_path, target_payload=selected_row) + update_transaction_form(selected_row, "transfer_review", db_path) def page_uncategorized(db_path: str) -> None: @@ -1679,6 +1711,33 @@ def page_accounts(db_path: str) -> None: st.dataframe(items[show_cols], width="stretch") review_count = int((items["status"] == "REVIEW_NEEDED").sum()) if "status" in items else 0 st.metric("확인필요", f"{review_count}건") + selectable = report.get("items", []) + if selectable: + labels = {f"{item.get('account_name')} · {item.get('status')} · {format_krw(item.get('difference'))}": item for item in selectable} + chosen_label = st.selectbox("대조 세션/판정 대상", list(labels.keys())) + chosen = labels[chosen_label] + with st.expander("Reconciliation session 기록/마감", expanded=False): + status = st.selectbox("Session status", ["open", "closed", "needs_recheck", "ignored"], key="recon_session_status") + memo = st.text_input("Session memo", value="", key="recon_session_memo") + if st.button("Session 저장/갱신", key="recon_session_save", type="primary"): + res = reconciliation_gateway.upsert_reconciliation_session( + chosen["account_id"], + str(chosen.get("baseline_at", ""))[:10], + expected_balance=chosen.get("baseline_balance"), + actual_balance=chosen.get("calculated_balance"), + difference=chosen.get("difference"), + status=status, + source_note=source_note, + memo=memo, + db_path=db_path, + ) + clear_cache(); st.success("저장했습니다." if res.get("success") else res.get("error", res)); st.rerun() + existing_session = chosen.get("reconciliation_session") or {} + if existing_session.get("id") and st.button("기존 Session 마감", key="recon_session_close"): + res = reconciliation_gateway.close_reconciliation_session(session_id=existing_session["id"], memo=memo, db_path=db_path) + clear_cache(); st.success("마감했습니다." if res.get("success") else res.get("error", res)); st.rerun() + with st.expander(f"Review decision · 현재 {chosen.get('review_status', 'pending')}", expanded=False): + render_review_decision_actions(reconciliation_gateway, "reconciliation_account", chosen["account_id"], f"recon_review_{chosen['account_id']}", db_path, target_payload=chosen) else: st.info("잔액대조 대상 계좌가 없습니다.") else: diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md index 067db82..82d41ba 100644 --- a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/design.md @@ -1,31 +1,47 @@ # BAT-016 Design: Review decision persistence and reconciliation workbench ## Design Status -- Status: draft -- Owner: delivery-runner to complete with dev-impl input before implementation. +- Status: completed +- Owner: 가웨인 direct recovery path; Kanban prohibited by user. -## Required Design Decisions -1. Persistence schema - - Define exact columns, indexes, uniqueness/idempotency keys, and schema migration path for `review_decisions` and `reconciliation_sessions`. - - Define whether target payload is JSON text and how sensitive content is minimized. -2. State model - - Map UI labels to internal `status` and `decision_type` values from REQ-020. - - Define allowed transitions for pending/decided/held/needs_recheck/ignored. -3. Application contracts - - Define additive fields returned by review queue, reconciliation report, and uncategorized workbench services. - - Define compatibility expectations for existing MCP and Streamlit consumers. -4. MCP tool contracts - - Define names, arguments, responses, error handling, and non-goals for review decision/session tools. - - Explicitly exclude destructive delete/reset operations. -5. Streamlit interaction model - - Define minimum UI actions, confirmation patterns, and feedback messages. -6. Verification design - - Define fixtures and representative scenarios for persistence round-trip, contract compatibility, dashboard behavior, and DB safety. +## Architecture Summary +BAT-016 adds a small review-state layer beside the existing ledger facts. Transactions, accounts, imports, categories, and reports remain the financial source of truth; `review_decisions` and `reconciliation_sessions` store operator workflow state only. MCP and Streamlit adapters use the existing `service.py` facade and page/domain gateways, so the new behavior is additive to current consumers. -## Initial Recommendation -Use a common decision envelope with fields aligned to REQ-020 and target-specific payload fields stored as minimal JSON. Use reconciliation sessions as account/basis-date close records and allow review decisions to target either a session or a specific item. +## Changed Areas +- SQLite schema/migrations: schema version `11`, new `review_decisions` and `reconciliation_sessions` tables plus indexes. +- Application: new `review_decision_service.py` owns decision/session persistence, payload sanitization, operating indicators, and attachment helpers. +- Existing services: cross-transfer queue, reconciliation report, and uncategorized workbench attach persisted review/session state with additive fields. +- MCP: safe review decision/session tools registered through `tool_contracts.py` and `server.py`. +- Streamlit: dashboard actions for review decisions and reconciliation sessions through existing gateways. +- Docs/tests: data model/project structure/runtime flow baselines and pytest coverage. -## Design Completion Criteria -- Schema and state transitions are explicit enough for dev-impl to implement without product reinterpretation. -- MCP and Streamlit contracts are additive and testable. -- Verification scenarios map directly to REQ-020 AC 1-10. +## Key Decisions +1. **Schema** + - `review_decisions`: common decision envelope with `target_type`, `target_id`, `status`, `decision_type`, `reason_code`, `memo`, `operator`, `decided_at`, `review_after`, `target_payload`, timestamps. + - `reconciliation_sessions`: account/basis-date session records with expected/actual/difference, `status`, `closed_at`, source/memo/operator, timestamps. + - Migrations are additive and idempotent using `CREATE TABLE IF NOT EXISTS` and `CREATE INDEX IF NOT EXISTS`. +2. **State model** + - Review statuses: `pending`, `decided`, `held`, `needs_recheck`, `ignored`. + - Decision types: `account_transfer`, `real_expense`, `real_income`, `investment_transfer`, `excluded_from_analysis`, `duplicate_or_cancel`, `unknown`. + - Reconciliation statuses: `open`, `closed`, `needs_recheck`, `ignored`. +3. **Payload safety** + - `target_payload` is minimal JSON text; known sensitive keys such as `raw_payload`, password/token/secret/file_path are dropped before persistence. +4. **Contracts** + - Existing payloads remain compatible; new fields such as `review_status`, `review_decision`, and `reconciliation_session` are additive. + - MCP adds non-destructive tools only; no delete/reset tool is exposed. +5. **Operating indicators** + - The service computes pending review, held/recheck, unreconciled account count, last reconciliation close time, and uncategorized recommendation backlog from persisted state plus current ledger state. + +## Edge Cases +- Unknown/invalid status or decision type returns validation errors rather than writing inconsistent state. +- Release/hold/recheck operations target the latest decision for a given target and preserve audit timestamps. +- Reconciliation session `difference` can be supplied or derived from expected/actual values. +- Empty or unparsable `target_payload` is reduced to `{}` or a short summary, never raw financial evidence expansion. + +## Architecture Impact +- `both`: project structure gains `application/review_decision_service.py`; runtime flows gain review-decision/reconciliation workbench flow. + +## Reference Doc Update Plan +- `docs/data-model.md`: add review/session entities, state values, and payload-minimization rules. +- `docs/project-structure.md`: list `review_decision_service.py` ownership. +- `docs/runtime-flows.md`: add review decision and reconciliation workbench runtime flow. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md index f7eda22..59f6b0c 100644 --- a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/implementation.md @@ -1,17 +1,52 @@ # BAT-016 Implementation Log ## Status -- Not started. +- Implemented locally; release-candidate after verification. +- Completed At (KST): 2026-07-08 07:11 KST +- Branch: `feat/bat-016-review-decision-workbench` ## Implementation Owner -- dev-builder / dev-impl under delivery-runner orchestration. +- 가웨인 direct recovery path. User explicitly prohibited Kanban after prior worker failures. -## Expected Evidence -- Code diff summary by slice. -- Migration and validation DB evidence. -- MCP tool discovery and representative call evidence. -- Streamlit AppTest/HTTP smoke evidence. -- Full lint/test evidence. +## Changed Files +- `jarca_ledger_mcp/infrastructure/sqlite/schema.py` +- `jarca_ledger_mcp/infrastructure/sqlite/migrations.py` +- `jarca_ledger_mcp/application/review_decision_service.py` +- `jarca_ledger_mcp/application/cross_transfer_service.py` +- `jarca_ledger_mcp/application/reconciliation_service.py` +- `jarca_ledger_mcp/application/uncategorized_workbench_service.py` +- `jarca_ledger_mcp/application/system_services.py` +- `jarca_ledger_mcp/service.py` +- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py` +- `jarca_ledger_mcp/adapters/mcp/server.py` +- `jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py` +- `jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py` +- `jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py` +- `dashboard/app.py` +- `tests/test_review_decision_workbench.py` +- `tests/test_service.py` +- `tests/test_ledger_categories.py` +- `docs/data-model.md` +- `docs/project-structure.md` +- `docs/runtime-flows.md` -## Log -- 2026-07-08 00:00 KST: Batch scaffolded by lead. No implementation performed yet. +## Implementation Summary +- Raised SQLite schema version to `11` and added additive/idempotent `review_decisions` and `reconciliation_sessions` schema objects. +- Added `review_decision_service.py` for safe non-destructive review decision and reconciliation session operations. +- Added payload minimization to prevent raw payload/password/token/secret/file-path persistence. +- Added review/session state enrichment to cross-transfer queue, balance reconciliation report, and uncategorized workbench outputs. +- Added MCP tools for list/upsert/hold/recheck/release review decisions, list/upsert/close reconciliation sessions, and review operating indicators. +- Added Streamlit actions and gateway exports for review decision/session workflow state. +- Added regression tests for schema idempotency, sensitive payload filtering, reconciliation session round trip, report integration, and MCP tool surface. + +## Commands and Results +- `python -m ruff check .` → passed. +- `python -m pytest tests/test_review_decision_workbench.py -q` → `.... [100%]`. +- `python -m pytest -q` → passed, with existing skipped tests preserved. +- MCP surface smoke: required 9 review/session tools present; destructive delete/reset absent; tool count `65`. +- DB safety smoke: schema version `11`, `PRAGMA integrity_check` `ok`, new tables present and empty on synthetic DB. + +## Notes +- No production DB destructive operation was performed. +- No raw financial evidence or secrets were added to repository fixtures. +- Final PR/CI evidence remains the next gate after commit/push. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md index ecfd3f7..1b2af9b 100644 --- a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/index.md @@ -1,16 +1,17 @@ # BAT-016: Review decision persistence and reconciliation workbench - Profile: standard -- Status: draft +- Status: release-candidate - Included REQ: REQ-020 - Source Discovery: dcy-012 - Created At (KST): 2026-07-08 00:00 KST +- Verification Completed At (KST): 2026-07-08 07:11 KST ## Objective Deliver the approved REQ-020 scope for persisted review decisions, reconciliation sessions, Streamlit workbench actions, network MCP additive tools, operating hub indicators, and baseline documentation. ## Included Scope -- Additive/idempotent persistence for `review_decisions` and `reconciliation_sessions` or an equivalent structure. +- Additive/idempotent persistence for `review_decisions` and `reconciliation_sessions`. - Application/service integration for cross-transfer review queue, reconciliation report, and uncategorized workbench. - Streamlit workbench actions for decision create/update/hold/recheck/release. - Network MCP tools for safe review decision/session read and mutation operations. @@ -31,6 +32,6 @@ Deliver the approved REQ-020 scope for persisted review decisions, reconciliatio - [implementation.md](implementation.md) - [verification.md](verification.md) -## Harness Notes -- This batch is `standard` because REQ-020 changes persistence, interface surface, runtime flow, Streamlit UI, MCP tools, and baseline docs. -- After this batch scaffold is committed, lead should issue a kanban-backed `lead -> delivery-runner` kickoff on the shared development execution board. +## Delivery Notes +- User explicitly prohibited Kanban for this recovery path; delivery was completed directly on feature branch `feat/bat-016-review-decision-workbench`. +- Local verification evidence is recorded in `verification.md`; final merge remains subject to PR/CI review. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md index 246cf7c..e28b0b7 100644 --- a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/planning.md @@ -1,18 +1,18 @@ # BAT-016 Planning: Review decision persistence and reconciliation workbench ## Planning Status -- Status: draft +- Status: completed - Profile: standard - Design Gate: yes - Design Gate Rationale: REQ-020 changes persistence schema, application service contracts, MCP tools, Streamlit UI flow, and operating hub aggregation. A design document is required before implementation. ## Objective -Turn REQ-020 into a delivery plan that can be executed by delivery-runner with separated implementation and QC roles. +Turn REQ-020 into a delivery plan for persisted review decisions and reconciliation sessions without changing existing public contracts destructively. ## Work Slices 1. Persistence foundation - Add review decision and reconciliation session schema via additive/idempotent migration. - - Add repository/service helpers with validation DB coverage. + - Add service helpers with validation DB coverage. 2. Application integration - Connect cross-transfer review queue, reconciliation report, and uncategorized workbench to persisted decision/session state. - Preserve existing response fields with additive extensions only. @@ -24,11 +24,22 @@ Turn REQ-020 into a delivery plan that can be executed by delivery-runner with s - Exclude destructive delete/reset tools. 5. Baseline and verification - Update data model, project structure, runtime flows. - - Add pytest, contract/smoke, Streamlit AppTest/HTTP smoke, and DB safety evidence. + - Add pytest, MCP surface smoke, Streamlit/dashboard and DB safety evidence. ## Acceptance Source - REQ-020 Acceptance Criteria 1-10. +## Dependencies +- dcy-013/BAT-015 network MCP endpoint remains the deployment substrate; BAT-016 does not redesign transport. +- Existing SQLite migration path must remain additive/idempotent. +- Existing dashboard and MCP consumers must keep their current response fields. + +## Milestones +1. Schema + service implementation. +2. Adapter/UI integration. +3. Targeted tests and full local regression. +4. StagePilot artifact update and PR/CI validation. + ## Risks - Source-of-truth ambiguity between current transaction/account state and persisted decision state. - Session granularity mismatch across account-level reconciliation and item-level review decisions. @@ -36,6 +47,7 @@ Turn REQ-020 into a delivery plan that can be executed by delivery-runner with s - MCP/Streamlit contract drift. ## Handoff Readiness -- Ready for design drafting: yes. -- Ready for implementation: no; design must define schema, state transitions, and interface contracts first. +- Ready for design drafting: completed. +- Ready for implementation: completed after design decisions below. - Lead authority needed before delivery: no additional user decision is currently open; scope is approved in dcy-012 and REQ-020. +- Kanban status: deliberately not used for this recovery path per explicit user instruction. diff --git a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md index f470ff8..abeea9f 100644 --- a/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md +++ b/docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/verification.md @@ -1,22 +1,74 @@ # BAT-016 Verification ## Status -- Not started. +- local-pass +- Verified At (KST): 2026-07-08 07:11 KST ## QC Owner -- dev-reviewer / dev-qc under delivery-runner orchestration. +- 가웨인 direct recovery path; independent QC still recommended before merge because Kanban-based dev-reviewer was explicitly disabled by user instruction. -## Required Verification -- REQ-020 AC 1-10 must be verified with direct evidence. -- `ruff check .` must pass. -- Full pytest must pass. -- MCP contract/regression and network MCP representative smoke must pass. -- Streamlit AppTest and HTTP smoke must pass. -- DB safety/migration regression must pass. -- Baseline document updates must be inspected. +## Required Verification Mapping +| REQ-020 AC | Evidence | +|---|---| +| AC1 additive/idempotent persistence | `tests/test_review_decision_workbench.py::test_review_decision_and_reconciliation_schema_are_additive_idempotent`; DB safety smoke showed schema `11`, integrity `ok`. | +| AC2 review decision round-trip | `test_review_decision_round_trip_payload_sanitizes_sensitive_fields`. | +| AC3 reconciliation session round-trip/hub basis | `test_reconciliation_session_round_trip_and_report_integration`. | +| AC4 additive existing service payloads | Full pytest passed; report/workbench tests preserved; new fields are additive. | +| AC5 network MCP safe tools | MCP tool surface smoke found required review/session tools and no destructive delete/reset tools. | +| AC6 Streamlit workbench regression | Full pytest includes `tests/test_dashboard_app.py`; local pass. | +| AC7 operating indicators | `get_review_operating_indicators` included in MCP smoke and session test checks last reconciliation close time. | +| AC8 financial data safety | Payload sanitization test drops `raw_payload` and `file_path`; no real DB or raw evidence used. | +| AC9 regression gates | `ruff check .` and full pytest passed locally. CI/PR evidence pending. | +| AC10 baseline docs | `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md` updated. | + +## Local Evidence +```text +python -m ruff check . +All checks passed! + +python -m pytest tests/test_review_decision_workbench.py -q +.... [100%] + +python -m pytest -q +........................ss......................ss... [100%] + +python -m pytest tests/test_contract_regression.py -q +... [100%] + +python -m pytest --ignore=tests/test_dashboard_app.py -q +....................ss......................ss... [100%] + +python -m pytest tests/test_dashboard_app.py -q +.... [100%] + +python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45 +success=true, http_status=200, fixture=synthetic + +python scripts/ci_db_safety_smoke.py --timeout 45 +success=true, fixture_integrity=ok, restored_integrity=ok, operating_db_used=false + +MCP surface smoke +close_reconciliation_session OK +get_review_operating_indicators OK +hold_review_decision OK +list_reconciliation_sessions OK +list_review_decisions OK +mark_review_recheck OK +release_review_decision OK +upsert_reconciliation_session OK +upsert_review_decision OK +tool_count 65 + +DB safety smoke +schema_version 11 +integrity_check ok +review_decisions 0 +reconciliation_sessions 0 +``` + +## Residual Risk +- Independent dev-reviewer QC was not run because user prohibited Kanban. Treat PR review/CI as the next independent gate. +- Local verification passed, but GitHub Actions CI must still be checked after push. ## Verdict -- Pending. - -## Evidence -- None yet. +- Local release-candidate. diff --git a/docs/batches/index.md b/docs/batches/index.md index 3495dc9..d8ec54c 100644 --- a/docs/batches/index.md +++ b/docs/batches/index.md @@ -23,4 +23,6 @@ | BAT-013 | standard | release-candidate | REQ-017 | dcy-011 | [bat-013_20260703_advanced-workflow-service-split](bat-013_20260703_advanced-workflow-service-split/) | | BAT-014 | standard | release-candidate | REQ-018 | dcy-011 | [bat-014_20260703_adapter-surface-narrowing-baseline-refresh](bat-014_20260703_adapter-surface-narrowing-baseline-refresh/) | | BAT-015 | standard | release-candidate | REQ-019 | dcy-013 | [bat-015_20260707_docker-network-mcp-deployment](bat-015_20260707_docker-network-mcp-deployment/) | -| BAT-016 | standard | draft | REQ-020 | dcy-012 | [bat-016_20260708_review-decision-reconciliation-workbench](bat-016_20260708_review-decision-reconciliation-workbench/) | +| BAT-016 | standard | release-candidate | REQ-020 | dcy-012 | [bat-016_20260708_review-decision-reconciliation-workbench](bat-016_20260708_review-decision-reconciliation-workbench/) | + +- 2026-07-08 07:11 KST: BAT-016을 local verification 통과 근거로 release-candidate 상태로 전환했다. Kanban은 사용자 명시 지시로 사용하지 않았다. diff --git a/docs/data-model.md b/docs/data-model.md index 0e2200d..8334a2e 100644 --- a/docs/data-model.md +++ b/docs/data-model.md @@ -193,6 +193,20 @@ - Backup artifacts and validation DB copies must not be committed to git. - Restore execution is not a persisted MCP operation and requires script/runbook approval controls. +## Entity: ReviewDecision +- Source of Truth: `review_decisions` +- Purpose: 공통 review/workbench envelope for cross-transfer review rows, reconciliation targets, and uncategorized recommendation items. +- Lifecycle: pending -> decided/held/needs_recheck/ignored -> pending release when operator clears hold/recheck. +- Key Fields: `id`, `target_type`, `target_id`, `status`, `decision_type`, `reason_code`, `memo`, `operator`, `decided_at`, `review_after`, sanitized JSON `target_payload`, `created_at`, `updated_at`. +- State Rules: decisions are non-destructive and do not rewrite accounting fields by themselves. Existing read contracts are preserved by attaching additive `review_status` / `review_decision` metadata. `target_payload` omits raw payloads, passwords, tokens, secrets, and source file paths. + +## Entity: ReconciliationSession +- Source of Truth: `reconciliation_sessions` +- Purpose: 계좌별/기준일별 잔액대조 session close/open state and difference evidence. +- Lifecycle: open -> closed, with `needs_recheck`/`ignored` available for operator triage. +- Key Fields: `id`, `account_id`, `basis_date`, `expected_balance`, `actual_balance`, `difference`, `status`, `closed_at`, `source_note`, `memo`, `operator`, `created_at`, `updated_at`. +- State Rules: account/basis-date rows are upserted idempotently; close records `closed_at`; destructive delete/reset workflow is not exposed. + ## Consistency Rules - Actual cashflow reports include only categories whose `cashflow_kind` represents actual income or expense according to report semantics. - Account movement summaries should be separate from actual household income/expense summaries. @@ -202,6 +216,8 @@ - DB corrections should be narrow and memo-tagged. - Dashboard/MCP asset and net-worth reports use a shared valuation helper: account-backed items from `accounts.last_balance` plus non-transaction items from `manual_assets`. - Net worth is asset buckets (`cash`, `investment`, `deposit`, `real_estate`, `other`) minus absolute `loan` liabilities; missing valuations are excluded and reported, never inferred from transactions. +- Review workbench state is sourced from `review_decisions`; pending/held/recheck counts must not be inferred by overwriting raw transaction evidence. +- Reconciliation operating state is sourced from `reconciliation_sessions`; last close time is the max closed session `closed_at`. ## Persistence Notes - Schema changes should be additive/idempotent unless a destructive migration is explicitly approved and backed up. @@ -209,11 +225,12 @@ - Validation DB copies should live outside the repository and should be selected explicitly via `JARCA_LEDGER_DB_PATH` when used. - Passwords for encrypted imports are runtime-only inputs and are not part of the persisted model. - Raw payloads may contain sensitive financial evidence and should not be committed to git. +- ReviewDecision `target_payload` is sanitized to omit `raw_payload`, passwords, tokens, secrets, and file paths before persistence. ## Current Gaps / Planned Changes - Formal schema migration documentation should be added before larger DB changes. - Some UI workflows need final E2E verification against real rows. -- Statement-unavailable account handling is tracked by REQ-003/BAT-003; future work may add a dedicated reconciliation workbench and persistent review-decision queue. +- Statement-unavailable account handling is tracked by REQ-003/BAT-003; REQ-020/BAT-016 adds dedicated reconciliation sessions and persistent review-decision queue metadata. - BAT-009 implements manual asset CRUD mutation and month-end snapshot preview/close/correction service/MCP/dashboard workflow. Future work may add automatic market/real-estate valuation or scheduled month-end close. ## Change Log @@ -223,3 +240,4 @@ - 2026-06-29 KST: REQ-005/BAT-005 기준으로 `accounts.liquidity_bucket`, `last_balance` 기반 자산 유동성/부채/순자산 규칙 추가. - 2026-06-30 KST: REQ-009/REQ-010/BAT-008 기준으로 `manual_assets`, `asset_snapshots`, 권위 소스(`accounts.last_balance` + `manual_assets`), 순자산 산식/미평가 제외 정책 추가. - 2026-07-01 KST: REQ-011/REQ-012/BAT-009 기준으로 manual asset CRUD, snapshot preview/close, append-only correction metadata, latest-run read policy 추가. +- 2026-07-08 KST: REQ-020/BAT-016 기준으로 `review_decisions`, `reconciliation_sessions`, review 상태값, payload 최소보관/마스킹 규칙, 운영 허브 집계 source-of-truth를 추가. diff --git a/docs/project-structure.md b/docs/project-structure.md index c878ef6..76ee531 100644 --- a/docs/project-structure.md +++ b/docs/project-structure.md @@ -4,8 +4,8 @@ - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml` - Status: draft - Owner: Jarca / project maintainer -- Last Updated (KST): 2026-07-07 -- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015 +- Last Updated (KST): 2026-07-08 +- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015, dcy-012/REQ-020/BAT-016 ## Project Summary - Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 자산/스냅샷, 현금흐름 분석을 SQLite에 저장하고 운영한다. @@ -71,6 +71,7 @@ jarca-ledger-mcp/ │ │ ├── imports_service.py │ │ ├── cross_transfer_service.py │ │ ├── reconciliation_service.py +│ │ ├── review_decision_service.py │ │ ├── categorization_services.py │ │ └── uncategorized_workbench_service.py │ ├── infrastructure/ @@ -165,6 +166,8 @@ jarca-ledger-mcp/ - Cross-account/self-transfer/cancel-original matching workflow ownership. - `jarca_ledger_mcp/application/reconciliation_service.py` - Manual/partial-import balance reconciliation preview ownership. +- `jarca_ledger_mcp/application/review_decision_service.py` + - Persistent review-decision and reconciliation-session workflow ownership. Provides safe non-destructive create/update/hold/recheck/release/close helpers shared by Streamlit and MCP adapters. - `jarca_ledger_mcp/application/categorization_services.py` - Category rules, categorization preview/apply, ledger categories, and compatibility delegation to `uncategorized_workbench_service.py`. - `jarca_ledger_mcp/application/uncategorized_workbench_service.py` @@ -242,3 +245,4 @@ jarca-ledger-mcp/ - 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 application / infrastructure / adapter layering, compatibility facade/shim, Streamlit gateway 구조를 반영했다. - 2026-07-03 KST: REQ-016/REQ-017/REQ-018 및 BAT-012/BAT-013/BAT-014 기준으로 import/advanced owning services, parser seam, MCP contract helper, page/domain Streamlit gateways를 반영했다. - 2026-07-07 KST: REQ-019/BAT-015 기준으로 Dockerfile/compose, `jarca-ledger` independent container, streamable-http MCP endpoint, Synology volume `/volume1/docker/jarca-ledger/data`, and Docker deployment runbook을 반영했다. +- 2026-07-08 KST: REQ-020/BAT-016 기준으로 review decision service, schema version 11, MCP/Streamlit review workflow integration을 반영했다. diff --git a/docs/runtime-flows.md b/docs/runtime-flows.md index 452aea7..31162f9 100644 --- a/docs/runtime-flows.md +++ b/docs/runtime-flows.md @@ -4,8 +4,8 @@ - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml` - Status: draft - Owner: Jarca / project maintainer -- Last Updated (KST): 2026-07-07 -- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015 +- Last Updated (KST): 2026-07-08 +- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010, BAT-012, BAT-013, BAT-014, dcy-013/BAT-015, dcy-012/REQ-020/BAT-016 - Primary Runtime: mixed ## Project Summary @@ -100,6 +100,15 @@ 3. Matched self-transfers become `이체 / 본인계좌이동`; investment movements become `이체 / 투자이동`; ambiguous rows remain `확인필요`. 4. Cancel/refund rows can be linked to original expense rows; memo tags preserve manual link evidence. +## Flow: `Review decision and reconciliation workbench persistence` +1. Operator reviews cross-account transfer candidates, reconciliation differences, or uncategorized recommendations in Streamlit or via MCP. +2. UI/MCP calls safe review decision tools such as `upsert_review_decision`, `hold_review_decision`, `mark_review_recheck`, and `release_review_decision`. +3. `review_decision_service.py` validates status/decision type, minimizes `target_payload`, drops sensitive keys, and writes `review_decisions`. +4. Reconciliation workflows call `upsert_reconciliation_session` or `close_reconciliation_session` for account/basis-date sessions stored in `reconciliation_sessions`. +5. Cross-transfer queue, balance reconciliation report, and uncategorized workbench re-read persisted state and return additive fields such as `review_status`, `review_decision`, and `reconciliation_session`. +6. Operating hub indicators aggregate pending review, held/recheck, unreconciled account count, last reconciliation close timestamp, and uncategorized recommendation backlog. +7. MCP tool surface remains non-destructive; delete/reset of review/session state is intentionally absent. + ## Flow: `Operational backup, validation DB, and restore smoke` 1. Operator captures non-sensitive DB status evidence with `get_ledger_db_status`: path, size, mtime, sha256, integrity check, major table row counts, and aggregate totals. 2. Operator creates a timestamped backup in `/root/.local/share/jarca/backups/ledger/` with `create_ledger_backup`; retention keeps the most recent 30 days or newest 20 files. @@ -156,3 +165,4 @@ - 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 service facade → application, db shim → infrastructure/sqlite, MCP/Streamlit adapter seam flow를 반영했다. - 2026-07-03 KST: REQ-016/REQ-017/REQ-018 및 BAT-012/BAT-013/BAT-014 기준으로 imports/advanced owning services, parser seam, MCP tool_contracts, Streamlit page/domain gateway flow를 반영했다. - 2026-07-07 KST: REQ-019/BAT-015 기준으로 Docker network MCP service flow와 legacy `jarca` DB → `jarca-ledger` volume migration flow를 추가했다. +- 2026-07-08 KST: REQ-020/BAT-016 기준으로 review decision/reconciliation workbench persistence flow와 운영 허브 지표 집계를 추가했다. diff --git a/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md b/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md index 382dd57..186111a 100644 --- a/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md +++ b/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md @@ -1,6 +1,6 @@ # req-020: Review decision persistence and reconciliation workbench -- Status: Approved +- Status: Implemented - Type: Interface - Priority: High - Owner: 렛저장인 @@ -161,3 +161,52 @@ #### Validation Plan - Validate through StagePilot doctor, index consistency checks, and CI after commit. Delivery validation remains owned by the later batch verification gate. + + +### CHG-20260708-02 +- Date: 2026-07-08 +- Author: 가웨인 + +#### Change Summary +- BAT-016 local implementation and verification evidence completed; REQ-020 Status moved to Implemented. + +#### Intent +- dcy-012 confirmed scope now has additive persistence, Streamlit/MCP integration, operating indicators, tests, and baseline document updates on feature branch `feat/bat-016-review-decision-workbench`. + +#### Acceptance Criteria Delta +- Added: + - none +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - `docs/batches/bat-016_20260708_review-decision-reconciliation-workbench/*` + - `docs/data-model.md` + - `docs/project-structure.md` + - `docs/runtime-flows.md` +- Modules: + - `jarca_ledger_mcp/application/review_decision_service.py` + - `jarca_ledger_mcp/infrastructure/sqlite/schema.py` + - `jarca_ledger_mcp/infrastructure/sqlite/migrations.py` + - MCP, Streamlit, reconciliation, transfer, and uncategorized workbench integration surfaces +- Tests: + - `tests/test_review_decision_workbench.py` + - schema-version expectations in existing DB health tests + +#### Delivery Trace Delta +- Batches: + - BAT-016 release-candidate +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: yes before merge/release +- Existing Implementation Invalidated: no +- Status Recommendation: implemented-after-local-verification +- Follow-up Action: push branch, open PR, and verify GitHub Actions CI. + +#### Validation Plan +- Local evidence: `ruff check .`, targeted pytest, full pytest, MCP tool surface smoke, and DB safety smoke passed at 2026-07-08 07:11 KST. GitHub Actions CI remains the next external gate. diff --git a/docs/srs/index.md b/docs/srs/index.md index 10b2be8..29465b0 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -59,7 +59,7 @@ | REQ-017 | Advanced finance workflow service split and compatibility-preserving domain isolation | Non-Functional | Implemented | High | 렛저장인 | [req-017_advanced-finance-workflow-service-split.md](Non-Functional/req-017_advanced-finance-workflow-service-split.md) | | REQ-018 | MCP/Streamlit adapter surface narrowing and baseline refresh for dcy-011 completion | Interface | Implemented | High | 렛저장인 | [req-018_adapter-surface-narrowing-baseline-refresh.md](Interface/req-018_adapter-surface-narrowing-baseline-refresh.md) | | REQ-019 | Docker network MCP deployment and operating DB migration | Deployment | Implemented | High | 렛저장인 | [req-019_docker-network-mcp-deployment.md](Deployment/req-019_docker-network-mcp-deployment.md) | -| REQ-020 | Review decision persistence and reconciliation workbench | Interface | Approved | High | 렛저장인 | [req-020_review-decision-persistence-reconciliation-workbench.md](Interface/req-020_review-decision-persistence-reconciliation-workbench.md) | +| REQ-020 | Review decision persistence and reconciliation workbench | Interface | Implemented | High | 렛저장인 | [req-020_review-decision-persistence-reconciliation-workbench.md](Interface/req-020_review-decision-persistence-reconciliation-workbench.md) | ## Recent Change Log Summary @@ -97,3 +97,5 @@ - 2026-07-07 22:23 KST: dcy-013 Docker network MCP 배포 범위로 REQ-019를 생성하고, BAT-015 구현·검증 evidence 및 운영 DB 이전 완료를 근거로 Implemented 상태로 등록했다. - 2026-07-07 23:53 KST: dcy-012 confirmed 범위를 `REQ-020` Proposed 상태로 생성하고 review decision persistence/reconciliation workbench 요구사항으로 등록했다. - 2026-07-08 00:00 KST: REQ-020을 승인 게이트 검토 후 Approved 상태로 전환했다. + +- 2026-07-08 07:11 KST: REQ-020을 BAT-016 local verification 근거로 Implemented 상태로 전환했다. CI/PR review는 후속 외부 gate로 남아 있다. diff --git a/jarca_ledger_mcp/adapters/mcp/server.py b/jarca_ledger_mcp/adapters/mcp/server.py index a82d06b..0eb342c 100644 --- a/jarca_ledger_mcp/adapters/mcp/server.py +++ b/jarca_ledger_mcp/adapters/mcp/server.py @@ -166,6 +166,51 @@ def get_balance_reconciliation_report(account_id: str = "", baseline_balance: in """Preview balance reconciliation for manual_only/partial_import accounts without mutating the DB.""" return contracts.get_balance_reconciliation_report(account_id, baseline_balance, baseline_at, source_note, memo, tolerance) +@mcp.tool() +def list_review_decisions(target_type: str = "", target_id: str = "", status: str = "", limit: int = 100) -> dict: + """List persisted review decisions for workbench targets.""" + return contracts.list_review_decisions(target_type=target_type, target_id=target_id, status=status, limit=limit) + +@mcp.tool() +def upsert_review_decision(target_type: str, target_id: str, status: str = "decided", decision_type: str = "unknown", reason_code: str = "", memo: str = "", operator: str = "operator", review_after: str = "", target_payload: dict | None = None, decision_id: str = "") -> dict: + """Create or update a non-destructive persisted review decision.""" + return contracts.upsert_review_decision(target_type, target_id, status, decision_type, reason_code, memo, operator, review_after, target_payload, decision_id) + +@mcp.tool() +def hold_review_decision(target_type: str, target_id: str, reason_code: str = "held", memo: str = "", operator: str = "operator", review_after: str = "") -> dict: + """Mark a review target as held without deleting evidence.""" + return contracts.hold_review_decision(target_type, target_id, reason_code, memo, operator, review_after) + +@mcp.tool() +def mark_review_recheck(target_type: str, target_id: str, reason_code: str = "needs_recheck", memo: str = "", operator: str = "operator", review_after: str = "") -> dict: + """Mark a review target as needing recheck.""" + return contracts.mark_review_recheck(target_type, target_id, reason_code, memo, operator, review_after) + +@mcp.tool() +def release_review_decision(target_type: str, target_id: str, memo: str = "", operator: str = "operator") -> dict: + """Release a held/recheck review target back to pending.""" + return contracts.release_review_decision(target_type, target_id, memo, operator) + +@mcp.tool() +def list_reconciliation_sessions(account_id: str = "", status: str = "", basis_date: str = "", limit: int = 100) -> dict: + """List persisted reconciliation sessions.""" + return contracts.list_reconciliation_sessions(account_id=account_id, status=status, basis_date=basis_date, limit=limit) + +@mcp.tool() +def upsert_reconciliation_session(account_id: str, basis_date: str, expected_balance: int | None = None, actual_balance: int | None = None, difference: int | None = None, status: str = "open", source_note: str = "", memo: str = "", operator: str = "operator", session_id: str = "") -> dict: + """Create or update an account/basis-date reconciliation session.""" + return contracts.upsert_reconciliation_session(account_id, basis_date, expected_balance, actual_balance, difference, status, source_note, memo, operator, session_id) + +@mcp.tool() +def close_reconciliation_session(session_id: str = "", account_id: str = "", basis_date: str = "", memo: str = "", operator: str = "operator") -> dict: + """Close an existing reconciliation session without destructive reset/delete.""" + return contracts.close_reconciliation_session(session_id=session_id, account_id=account_id, basis_date=basis_date, memo=memo, operator=operator) + +@mcp.tool() +def get_review_operating_indicators() -> dict: + """Return workbench indicators: pending, held/recheck, unreconciled, last close, uncategorized backlog.""" + return contracts.get_review_operating_indicators() + @mcp.tool() def create_ledger_transaction(transaction_date: str = "", type: str = "expense", amount: int = 0, category: str = "", subcategory: str = "", merchant: str = "", description: str = "", account_id: str = "", payment_method: str = "", person: str = "", project: str = "", tags: list[str] | str | None = None, is_fixed: bool = False, currency: str = "KRW", posted_date: str = "", source: str = "manual", external_id: str = "", memo: str = "", dedupe: bool = True) -> dict: """Create an income, expense, transfer, refund, or adjustment transaction. Amount is positive KRW minor unit; type determines direction.""" diff --git a/jarca_ledger_mcp/adapters/mcp/tool_contracts.py b/jarca_ledger_mcp/adapters/mcp/tool_contracts.py index 69170b5..5a90f67 100644 --- a/jarca_ledger_mcp/adapters/mcp/tool_contracts.py +++ b/jarca_ledger_mcp/adapters/mcp/tool_contracts.py @@ -26,7 +26,16 @@ from ...service import ( get_ledger_db_status as get_ledger_db_status, get_monthly_cashflow_report as get_monthly_cashflow_report, get_net_worth_timeseries as get_net_worth_timeseries, + get_review_operating_indicators as get_review_operating_indicators, get_uncategorized_merchant_summary as get_uncategorized_merchant_summary, + hold_review_decision as hold_review_decision, + list_reconciliation_sessions as list_reconciliation_sessions, + list_review_decisions as list_review_decisions, + mark_review_recheck as mark_review_recheck, + release_review_decision as release_review_decision, + upsert_reconciliation_session as upsert_reconciliation_session, + upsert_review_decision as upsert_review_decision, + close_reconciliation_session as close_reconciliation_session, health_check as health_check, import_kb_bank_pdf as import_kb_bank_pdf, import_seoulpay_xlsx as import_seoulpay_xlsx, @@ -86,7 +95,16 @@ __all__ = [ "get_ledger_db_status", "get_monthly_cashflow_report", "get_net_worth_timeseries", + "get_review_operating_indicators", "get_uncategorized_merchant_summary", + "hold_review_decision", + "list_reconciliation_sessions", + "list_review_decisions", + "mark_review_recheck", + "release_review_decision", + "upsert_reconciliation_session", + "upsert_review_decision", + "close_reconciliation_session", "health_check", "import_kb_bank_pdf", "import_seoulpay_xlsx", diff --git a/jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py b/jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py index 2178533..93fdc38 100644 --- a/jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py +++ b/jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py @@ -10,7 +10,11 @@ from ...service import ( delete_ledger_category as delete_ledger_category, get_uncategorized_merchant_summary as get_uncategorized_merchant_summary, get_uncategorized_workbench as get_uncategorized_workbench, + hold_review_decision as hold_review_decision, list_category_rules as list_category_rules, + mark_review_recheck as mark_review_recheck, + release_review_decision as release_review_decision, + upsert_review_decision as upsert_review_decision, list_ledger_categories as list_ledger_categories, list_uncategorized_transactions as list_uncategorized_transactions, preview_categorization as preview_categorization, @@ -29,7 +33,11 @@ __all__ = [ "delete_ledger_category", "get_uncategorized_merchant_summary", "get_uncategorized_workbench", + "hold_review_decision", "list_category_rules", + "mark_review_recheck", + "release_review_decision", + "upsert_review_decision", "list_ledger_categories", "list_uncategorized_transactions", "preview_categorization", diff --git a/jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py b/jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py index 9460488..dc864f0 100644 --- a/jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py +++ b/jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py @@ -1,7 +1,25 @@ from __future__ import annotations -from ...service import get_balance_reconciliation_report as get_balance_reconciliation_report +from ...service import ( + close_reconciliation_session as close_reconciliation_session, + get_balance_reconciliation_report as get_balance_reconciliation_report, + get_review_operating_indicators as get_review_operating_indicators, + hold_review_decision as hold_review_decision, + list_reconciliation_sessions as list_reconciliation_sessions, + mark_review_recheck as mark_review_recheck, + release_review_decision as release_review_decision, + upsert_reconciliation_session as upsert_reconciliation_session, + upsert_review_decision as upsert_review_decision, +) __all__ = [ + "close_reconciliation_session", "get_balance_reconciliation_report", + "get_review_operating_indicators", + "hold_review_decision", + "list_reconciliation_sessions", + "mark_review_recheck", + "release_review_decision", + "upsert_reconciliation_session", + "upsert_review_decision", ] diff --git a/jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py b/jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py index eb91cb6..485cd92 100644 --- a/jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py +++ b/jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py @@ -3,9 +3,13 @@ from __future__ import annotations from ...service import ( find_cancel_original_candidates as find_cancel_original_candidates, find_self_transfer_candidates as find_self_transfer_candidates, + hold_review_decision as hold_review_decision, link_cancel_to_original as link_cancel_to_original, link_self_transfer_pair as link_self_transfer_pair, list_cross_transfer_review_queue as list_cross_transfer_review_queue, + mark_review_recheck as mark_review_recheck, + release_review_decision as release_review_decision, + upsert_review_decision as upsert_review_decision, preview_cross_account_transfers as preview_cross_account_transfers, run_cross_account_transfer_match as run_cross_account_transfer_match, ) @@ -13,9 +17,13 @@ from ...service import ( __all__ = [ "find_cancel_original_candidates", "find_self_transfer_candidates", + "hold_review_decision", "link_cancel_to_original", "link_self_transfer_pair", "list_cross_transfer_review_queue", + "mark_review_recheck", + "release_review_decision", + "upsert_review_decision", "preview_cross_account_transfers", "run_cross_account_transfer_match", ] diff --git a/jarca_ledger_mcp/application/cross_transfer_service.py b/jarca_ledger_mcp/application/cross_transfer_service.py index c13568b..44ec1e2 100644 --- a/jarca_ledger_mcp/application/cross_transfer_service.py +++ b/jarca_ledger_mcp/application/cross_transfer_service.py @@ -19,6 +19,7 @@ from .shared import ( re, row_to_dict, ) +from .review_decision_service import attach_review_decisions def _build_cross_transfer_index(transactions: list[dict[str, Any]]) -> dict[tuple[str, int, str], list[dict[str, Any]]]: index: dict[tuple[str, int, str], list[dict[str, Any]]] = {} @@ -607,4 +608,5 @@ def list_cross_transfer_review_queue(limit: int = 300, db_path: str | None = Non f"SELECT * FROM transactions t{where} ORDER BY t.transaction_date DESC, t.created_at DESC LIMIT ?", (max(1, min(int(limit), 1000)),), ).fetchall() - return ok(transactions=[row_to_dict(r) for r in rows], count=len(rows), source="cross_transfer_review_queue") + transactions = attach_review_decisions(conn, [row_to_dict(r) for r in rows], "cross_transfer", "id") + return ok(transactions=transactions, count=len(transactions), source="cross_transfer_review_queue") diff --git a/jarca_ledger_mcp/application/reconciliation_service.py b/jarca_ledger_mcp/application/reconciliation_service.py index e6020cc..b5b9888 100644 --- a/jarca_ledger_mcp/application/reconciliation_service.py +++ b/jarca_ledger_mcp/application/reconciliation_service.py @@ -11,8 +11,10 @@ from .shared import ( normalize_snapshot_at, now_iso, ok, + row_to_dict, sqlite3, ) +from .review_decision_service import _fetch_latest_decisions def _transaction_signed_amount(tx_type: str, amount: int) -> int: @@ -72,6 +74,13 @@ def get_balance_reconciliation_report(account_id: str = "", baseline_balance: in clauses.append(f"statement_status IN ({placeholders})") params.extend(sorted(RECONCILIATION_TARGET_STATUSES)) accounts = conn.execute(f"SELECT * FROM accounts WHERE {' AND '.join(clauses)} ORDER BY name", params).fetchall() + account_targets = [("reconciliation_account", account["id"]) for account in accounts] + latest_decisions = _fetch_latest_decisions(conn, account_targets) + session_rows = conn.execute("SELECT * FROM reconciliation_sessions ORDER BY basis_date DESC, updated_at DESC").fetchall() + latest_sessions: dict[str, dict[str, Any]] = {} + for row in session_rows: + session = row_to_dict(row) + latest_sessions.setdefault(session["account_id"], session) items: list[dict[str, Any]] = [] for account in accounts: effective_baseline = baseline_balance_int if baseline_balance_int is not None else account["last_balance"] @@ -99,6 +108,9 @@ def get_balance_reconciliation_report(account_id: str = "", baseline_balance: in "difference_ratio": ratio, "status": status, "recommended_decisions": ["계좌이동", "실지출", "실수입", "투자이동", "분석제외", "확인필요"] if status == "REVIEW_NEEDED" else [], + "reconciliation_session": latest_sessions.get(account["id"]), + "review_status": latest_decisions.get(("reconciliation_account", account["id"]), {}).get("status", "pending"), + "review_decision": latest_decisions.get(("reconciliation_account", account["id"])), "source_note": source_note, "memo": memo, **calc, diff --git a/jarca_ledger_mcp/application/review_decision_service.py b/jarca_ledger_mcp/application/review_decision_service.py new file mode 100644 index 0000000..d8cf4db --- /dev/null +++ b/jarca_ledger_mcp/application/review_decision_service.py @@ -0,0 +1,359 @@ +from __future__ import annotations + +from .shared import ( + Any, + db, + fail, + json, + new_id, + normalize_date, + now_iso, + ok, + row_to_dict, +) + +VALID_REVIEW_STATUSES = {"pending", "decided", "held", "needs_recheck", "ignored"} +VALID_DECISION_TYPES = { + "account_transfer", + "real_expense", + "real_income", + "investment_transfer", + "excluded_from_analysis", + "duplicate_or_cancel", + "unknown", +} +VALID_RECONCILIATION_STATUSES = {"open", "closed", "needs_recheck", "ignored"} +SENSITIVE_PAYLOAD_KEYS = {"raw_payload", "password", "account_password", "secret", "token", "file_path"} + + +def _normalize_review_status(value: str | None) -> str: + status = (value or "pending").strip() or "pending" + if status not in VALID_REVIEW_STATUSES: + raise ValueError(f"status must be one of {sorted(VALID_REVIEW_STATUSES)}") + return status + + +def _normalize_decision_type(value: str | None) -> str: + decision_type = (value or "unknown").strip() or "unknown" + if decision_type not in VALID_DECISION_TYPES: + raise ValueError(f"decision_type must be one of {sorted(VALID_DECISION_TYPES)}") + return decision_type + + +def _normalize_reconciliation_status(value: str | None) -> str: + status = (value or "open").strip() or "open" + if status not in VALID_RECONCILIATION_STATUSES: + raise ValueError(f"status must be one of {sorted(VALID_RECONCILIATION_STATUSES)}") + return status + + +def _safe_payload(target_payload: Any) -> str: + if target_payload in (None, ""): + return "{}" + if isinstance(target_payload, str): + try: + parsed = json.loads(target_payload) + except json.JSONDecodeError: + return json.dumps({"summary": target_payload[:500]}, ensure_ascii=False) + elif isinstance(target_payload, dict): + parsed = target_payload + else: + parsed = {"value": str(target_payload)[:500]} + safe: dict[str, Any] = {} + for key, value in parsed.items(): + key_text = str(key) + if key_text.lower() in SENSITIVE_PAYLOAD_KEYS: + continue + if isinstance(value, (str, int, float, bool)) or value is None: + safe[key_text] = str(value)[:500] if isinstance(value, str) else value + elif isinstance(value, (list, tuple)): + safe[key_text] = [str(item)[:200] for item in value[:20]] + else: + safe[key_text] = str(value)[:500] + return json.dumps(safe, ensure_ascii=False, sort_keys=True) + + +def _decode_payload(row: dict[str, Any]) -> dict[str, Any]: + raw = row.get("target_payload") or "{}" + try: + row["target_payload"] = json.loads(raw) + except json.JSONDecodeError: + row["target_payload"] = {} + return row + + +def _fetch_latest_decisions(conn: Any, targets: list[tuple[str, str]]) -> dict[tuple[str, str], dict[str, Any]]: + if not targets: + return {} + by_target: dict[tuple[str, str], dict[str, Any]] = {} + for target_type, target_id in targets: + row = conn.execute( + """ + SELECT * FROM review_decisions + WHERE target_type=? AND target_id=? + ORDER BY decided_at DESC, updated_at DESC, created_at DESC + LIMIT 1 + """, + (target_type, target_id), + ).fetchone() + if row: + by_target[(target_type, target_id)] = _decode_payload(row_to_dict(row)) + return by_target + + +def attach_review_decisions(db_conn: Any, items: list[dict[str, Any]], target_type: str, id_field: str = "id") -> list[dict[str, Any]]: + targets = [(target_type, str(item.get(id_field) or "")) for item in items if item.get(id_field)] + decisions = _fetch_latest_decisions(db_conn, targets) + enriched: list[dict[str, Any]] = [] + for item in items: + target_id = str(item.get(id_field) or "") + decision = decisions.get((target_type, target_id)) + state = decision.get("status") if decision else "pending" + enriched.append({**item, "review_status": state, "review_decision": decision}) + return enriched + + +def list_review_decisions(target_type: str = "", target_id: str = "", status: str = "", limit: int = 100, db_path: str | None = None) -> dict[str, Any]: + clauses: list[str] = [] + params: list[Any] = [] + if target_type: + clauses.append("target_type=?") + params.append(target_type) + if target_id: + clauses.append("target_id=?") + params.append(target_id) + if status: + try: + status = _normalize_review_status(status) + except ValueError as exc: + return fail("validation_error", str(exc)) + clauses.append("status=?") + params.append(status) + where = " WHERE " + " AND ".join(clauses) if clauses else "" + max_limit = max(1, min(int(limit), 1000)) + with db(db_path) as conn: + rows = conn.execute( + f"SELECT * FROM review_decisions{where} ORDER BY decided_at DESC, updated_at DESC LIMIT ?", + (*params, max_limit), + ).fetchall() + decisions = [_decode_payload(row_to_dict(row)) for row in rows] + return ok(review_decisions=decisions, decisions=decisions, count=len(decisions)) + + +def upsert_review_decision( + target_type: str, + target_id: str, + status: str = "decided", + decision_type: str = "unknown", + reason_code: str = "", + memo: str = "", + operator: str = "operator", + review_after: str = "", + target_payload: Any = None, + decision_id: str = "", + db_path: str | None = None, +) -> dict[str, Any]: + target_type = (target_type or "").strip() + target_id = (target_id or "").strip() + if not target_type or not target_id: + return fail("validation_error", "target_type and target_id are required") + try: + normalized_status = _normalize_review_status(status) + normalized_decision_type = _normalize_decision_type(decision_type) + normalized_review_after = normalize_date(review_after, default_today=False) if review_after else "" + except Exception as exc: + return fail("validation_error", str(exc)) + ts = now_iso() + payload_text = _safe_payload(target_payload) + with db(db_path) as conn: + existing = None + if decision_id: + existing = conn.execute("SELECT * FROM review_decisions WHERE id=?", (decision_id,)).fetchone() + if not existing: + return fail("not_found", f"review decision not found: {decision_id}") + else: + existing = conn.execute( + "SELECT * FROM review_decisions WHERE target_type=? AND target_id=? ORDER BY decided_at DESC, updated_at DESC LIMIT 1", + (target_type, target_id), + ).fetchone() + row_id = decision_id or (existing["id"] if existing else new_id("rd")) + created_at = existing["created_at"] if existing else ts + decided_at = ts if normalized_status in {"decided", "held", "needs_recheck", "ignored"} else "" + conn.execute( + """ + INSERT INTO review_decisions(id, target_type, target_id, status, decision_type, reason_code, memo, operator, decided_at, review_after, target_payload, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(id) DO UPDATE SET + target_type=excluded.target_type, + target_id=excluded.target_id, + status=excluded.status, + decision_type=excluded.decision_type, + reason_code=excluded.reason_code, + memo=excluded.memo, + operator=excluded.operator, + decided_at=excluded.decided_at, + review_after=excluded.review_after, + target_payload=excluded.target_payload, + updated_at=excluded.updated_at + """, + (row_id, target_type, target_id, normalized_status, normalized_decision_type, reason_code or "", memo or "", operator or "operator", decided_at, normalized_review_after, payload_text, created_at, ts), + ) + row = conn.execute("SELECT * FROM review_decisions WHERE id=?", (row_id,)).fetchone() + return ok(review_decision=_decode_payload(row_to_dict(row)), decision_id=row_id) + + +def hold_review_decision(target_type: str, target_id: str, reason_code: str = "held", memo: str = "", operator: str = "operator", review_after: str = "", db_path: str | None = None) -> dict[str, Any]: + return upsert_review_decision(target_type, target_id, status="held", decision_type="unknown", reason_code=reason_code, memo=memo, operator=operator, review_after=review_after, db_path=db_path) + + +def mark_review_recheck(target_type: str, target_id: str, reason_code: str = "needs_recheck", memo: str = "", operator: str = "operator", review_after: str = "", db_path: str | None = None) -> dict[str, Any]: + return upsert_review_decision(target_type, target_id, status="needs_recheck", decision_type="unknown", reason_code=reason_code, memo=memo, operator=operator, review_after=review_after, db_path=db_path) + + +def release_review_decision(target_type: str, target_id: str, memo: str = "", operator: str = "operator", db_path: str | None = None) -> dict[str, Any]: + return upsert_review_decision(target_type, target_id, status="pending", decision_type="unknown", reason_code="released", memo=memo, operator=operator, review_after="", db_path=db_path) + + +def list_reconciliation_sessions(account_id: str = "", status: str = "", basis_date: str = "", limit: int = 100, db_path: str | None = None) -> dict[str, Any]: + clauses: list[str] = [] + params: list[Any] = [] + if account_id: + clauses.append("account_id=?") + params.append(account_id) + if status: + try: + status = _normalize_reconciliation_status(status) + except ValueError as exc: + return fail("validation_error", str(exc)) + clauses.append("status=?") + params.append(status) + if basis_date: + try: + basis_date = normalize_date(basis_date) + except Exception as exc: + return fail("validation_error", str(exc)) + clauses.append("basis_date=?") + params.append(basis_date) + where = " WHERE " + " AND ".join(clauses) if clauses else "" + with db(db_path) as conn: + rows = conn.execute( + f"SELECT * FROM reconciliation_sessions{where} ORDER BY basis_date DESC, updated_at DESC LIMIT ?", + (*params, max(1, min(int(limit), 1000))), + ).fetchall() + sessions = [row_to_dict(row) for row in rows] + return ok(reconciliation_sessions=sessions, sessions=sessions, count=len(sessions)) + + +def upsert_reconciliation_session( + account_id: str, + basis_date: str, + expected_balance: int | None = None, + actual_balance: int | None = None, + difference: int | None = None, + status: str = "open", + source_note: str = "", + memo: str = "", + operator: str = "operator", + session_id: str = "", + db_path: str | None = None, +) -> dict[str, Any]: + account_id = (account_id or "").strip() + if not account_id: + return fail("validation_error", "account_id is required") + try: + basis = normalize_date(basis_date, default_today=False) + normalized_status = _normalize_reconciliation_status(status) + expected = int(expected_balance) if expected_balance is not None else None + actual = int(actual_balance) if actual_balance is not None else None + diff = int(difference) if difference is not None else ((expected - actual) if expected is not None and actual is not None else None) + except Exception as exc: + return fail("validation_error", str(exc)) + ts = now_iso() + closed_at = ts if normalized_status == "closed" else "" + with db(db_path) as conn: + account = conn.execute("SELECT id FROM accounts WHERE id=?", (account_id,)).fetchone() + if not account: + return fail("not_found", f"account not found: {account_id}") + existing = None + if session_id: + existing = conn.execute("SELECT * FROM reconciliation_sessions WHERE id=?", (session_id,)).fetchone() + if not existing: + return fail("not_found", f"reconciliation session not found: {session_id}") + else: + existing = conn.execute("SELECT * FROM reconciliation_sessions WHERE account_id=? AND basis_date=?", (account_id, basis)).fetchone() + row_id = session_id or (existing["id"] if existing else new_id("rs")) + created_at = existing["created_at"] if existing else ts + if normalized_status != "closed" and existing: + closed_at = existing["closed_at"] if existing["status"] == "closed" and normalized_status == "closed" else "" + conn.execute( + """ + INSERT INTO reconciliation_sessions(id, account_id, basis_date, expected_balance, actual_balance, difference, status, closed_at, source_note, memo, operator, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(id) DO UPDATE SET + account_id=excluded.account_id, + basis_date=excluded.basis_date, + expected_balance=excluded.expected_balance, + actual_balance=excluded.actual_balance, + difference=excluded.difference, + status=excluded.status, + closed_at=excluded.closed_at, + source_note=excluded.source_note, + memo=excluded.memo, + operator=excluded.operator, + updated_at=excluded.updated_at + """, + (row_id, account_id, basis, expected, actual, diff, normalized_status, closed_at, source_note or "", memo or "", operator or "operator", created_at, ts), + ) + row = conn.execute("SELECT * FROM reconciliation_sessions WHERE id=?", (row_id,)).fetchone() + return ok(reconciliation_session=row_to_dict(row), session_id=row_id) + + +def close_reconciliation_session(session_id: str = "", account_id: str = "", basis_date: str = "", memo: str = "", operator: str = "operator", db_path: str | None = None) -> dict[str, Any]: + with db(db_path) as conn: + if session_id: + row = conn.execute("SELECT * FROM reconciliation_sessions WHERE id=?", (session_id,)).fetchone() + elif account_id and basis_date: + try: + basis = normalize_date(basis_date, default_today=False) + except Exception as exc: + return fail("validation_error", str(exc)) + row = conn.execute("SELECT * FROM reconciliation_sessions WHERE account_id=? AND basis_date=?", (account_id, basis)).fetchone() + else: + return fail("validation_error", "session_id or account_id+basis_date is required") + if not row: + return fail("not_found", "reconciliation session not found") + existing = row_to_dict(row) + return upsert_reconciliation_session( + account_id=existing["account_id"], + basis_date=existing["basis_date"], + expected_balance=existing.get("expected_balance"), + actual_balance=existing.get("actual_balance"), + difference=existing.get("difference"), + status="closed", + source_note=existing.get("source_note", ""), + memo=memo or existing.get("memo", ""), + operator=operator, + session_id=existing["id"], + db_path=db_path, + ) + + +def get_review_operating_indicators(db_path: str | None = None) -> dict[str, Any]: + with db(db_path) as conn: + review_rows = conn.execute("SELECT status, COUNT(*) AS count FROM review_decisions GROUP BY status").fetchall() + pending_count = int(conn.execute("SELECT COUNT(*) FROM review_decisions WHERE status='pending'").fetchone()[0]) + held_recheck_count = int(conn.execute("SELECT COUNT(*) FROM review_decisions WHERE status IN ('held','needs_recheck')").fetchone()[0]) + unreconciled_accounts = int(conn.execute("SELECT COUNT(DISTINCT account_id) FROM reconciliation_sessions WHERE status<>'closed'").fetchone()[0]) + last_closed = conn.execute("SELECT MAX(closed_at) AS closed_at FROM reconciliation_sessions WHERE status='closed' AND closed_at<>''").fetchone()["closed_at"] + uncategorized_pending = int(conn.execute("SELECT COUNT(*) FROM transactions WHERE status='active' AND COALESCE(category,'')='' ").fetchone()[0]) + by_status = {row["status"]: int(row["count"] or 0) for row in review_rows} + return ok( + indicators={ + "pending_review_count": pending_count, + "held_recheck_count": held_recheck_count, + "unreconciled_account_count": unreconciled_accounts, + "last_reconciliation_closed_at": last_closed or "", + "uncategorized_recommendation_backlog": uncategorized_pending, + "review_decisions_by_status": by_status, + } + ) diff --git a/jarca_ledger_mcp/application/system_services.py b/jarca_ledger_mcp/application/system_services.py index 8f4aa3d..aa97db5 100644 --- a/jarca_ledger_mcp/application/system_services.py +++ b/jarca_ledger_mcp/application/system_services.py @@ -57,7 +57,7 @@ def _readonly_sqlite_connection(path: Path) -> sqlite3.Connection: def _safe_table_counts(conn: sqlite3.Connection) -> dict[str, int]: counts: dict[str, int] = {} - for table in ("accounts", "transactions", "budgets", "import_batches", "category_rules", "ledger_categories", "manual_assets", "asset_snapshots"): + for table in ("accounts", "transactions", "budgets", "import_batches", "category_rules", "ledger_categories", "manual_assets", "asset_snapshots", "review_decisions", "reconciliation_sessions"): exists = conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)).fetchone() if exists: counts[table] = int(conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]) diff --git a/jarca_ledger_mcp/application/uncategorized_workbench_service.py b/jarca_ledger_mcp/application/uncategorized_workbench_service.py index a774169..2bebd0c 100644 --- a/jarca_ledger_mcp/application/uncategorized_workbench_service.py +++ b/jarca_ledger_mcp/application/uncategorized_workbench_service.py @@ -10,6 +10,7 @@ from .shared import ( re, row_to_dict, ) +from .review_decision_service import attach_review_decisions def _rule_matches(rule: dict[str, Any], tx: dict[str, Any]) -> bool: if rule.get("transaction_type") and rule.get("transaction_type") != tx.get("type", ""): @@ -171,6 +172,8 @@ def get_uncategorized_workbench( group["recommendation"] = rec group_items = sorted(groups.values(), key=lambda g: (int(g["count"]), int(g["total_amount"])), reverse=True) + with db(db_path) as conn: + txs = attach_review_decisions(conn, txs, "uncategorized_transaction", "id") recommendable_count = sum(1 for tx in txs if tx.get("recommended_category")) repeated_group_count = sum(1 for g in group_items if int(g.get("count") or 0) >= 2) total = row_to_dict(total_row) if total_row else {"count": 0, "total_amount": 0, "merchant_group_count": 0} diff --git a/jarca_ledger_mcp/infrastructure/sqlite/migrations.py b/jarca_ledger_mcp/infrastructure/sqlite/migrations.py index dd0c70e..b948bf6 100644 --- a/jarca_ledger_mcp/infrastructure/sqlite/migrations.py +++ b/jarca_ledger_mcp/infrastructure/sqlite/migrations.py @@ -102,6 +102,40 @@ def migrate_db(conn: sqlite3.Connection) -> None: conn.execute("CREATE INDEX IF NOT EXISTS idx_asset_snapshots_basis_date ON asset_snapshots(basis_date)") conn.execute("CREATE INDEX IF NOT EXISTS idx_asset_snapshots_source ON asset_snapshots(source_type, source_id)") conn.execute("CREATE INDEX IF NOT EXISTS idx_asset_snapshots_run ON asset_snapshots(basis_date, snapshot_run_id, created_at)") + conn.execute("""CREATE TABLE IF NOT EXISTS review_decisions ( + id TEXT PRIMARY KEY, + target_type TEXT NOT NULL, + target_id TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'pending', + decision_type TEXT NOT NULL DEFAULT 'unknown', + reason_code TEXT NOT NULL DEFAULT '', + memo TEXT NOT NULL DEFAULT '', + operator TEXT NOT NULL DEFAULT 'operator', + decided_at TEXT NOT NULL DEFAULT '', + review_after TEXT NOT NULL DEFAULT '', + target_payload TEXT NOT NULL DEFAULT '{}', + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL + )""") + conn.execute("CREATE INDEX IF NOT EXISTS idx_review_decisions_target ON review_decisions(target_type, target_id, updated_at)") + conn.execute("CREATE INDEX IF NOT EXISTS idx_review_decisions_status ON review_decisions(status, review_after, updated_at)") + conn.execute("""CREATE TABLE IF NOT EXISTS reconciliation_sessions ( + id TEXT PRIMARY KEY, + account_id TEXT NOT NULL, + basis_date TEXT NOT NULL, + expected_balance INTEGER, + actual_balance INTEGER, + difference INTEGER, + status TEXT NOT NULL DEFAULT 'open', + closed_at TEXT NOT NULL DEFAULT '', + source_note TEXT NOT NULL DEFAULT '', + memo TEXT NOT NULL DEFAULT '', + operator TEXT NOT NULL DEFAULT 'operator', + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL + )""") + conn.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_reconciliation_sessions_account_basis ON reconciliation_sessions(account_id, basis_date)") + conn.execute("CREATE INDEX IF NOT EXISTS idx_reconciliation_sessions_status ON reconciliation_sessions(status, closed_at)") conn.execute("INSERT OR REPLACE INTO schema_meta(key, value) VALUES ('schema_version', ?)", (SCHEMA_VERSION,)) diff --git a/jarca_ledger_mcp/infrastructure/sqlite/schema.py b/jarca_ledger_mcp/infrastructure/sqlite/schema.py index ca46513..55c8bf9 100644 --- a/jarca_ledger_mcp/infrastructure/sqlite/schema.py +++ b/jarca_ledger_mcp/infrastructure/sqlite/schema.py @@ -1,6 +1,6 @@ from __future__ import annotations -SCHEMA_VERSION = "10" +SCHEMA_VERSION = "11" SCHEMA_SQL = """ PRAGMA journal_mode=WAL; @@ -168,7 +168,43 @@ CREATE TABLE IF NOT EXISTS asset_snapshots ( CREATE INDEX IF NOT EXISTS idx_asset_snapshots_basis_date ON asset_snapshots(basis_date); CREATE INDEX IF NOT EXISTS idx_asset_snapshots_source ON asset_snapshots(source_type, source_id); -INSERT OR REPLACE INTO schema_meta(key, value) VALUES ('schema_version', '10'); +CREATE TABLE IF NOT EXISTS review_decisions ( + id TEXT PRIMARY KEY, + target_type TEXT NOT NULL, + target_id TEXT NOT NULL, + status TEXT NOT NULL DEFAULT 'pending', + decision_type TEXT NOT NULL DEFAULT 'unknown', + reason_code TEXT NOT NULL DEFAULT '', + memo TEXT NOT NULL DEFAULT '', + operator TEXT NOT NULL DEFAULT 'operator', + decided_at TEXT NOT NULL DEFAULT '', + review_after TEXT NOT NULL DEFAULT '', + target_payload TEXT NOT NULL DEFAULT '{}', + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +); +CREATE INDEX IF NOT EXISTS idx_review_decisions_target ON review_decisions(target_type, target_id, updated_at); +CREATE INDEX IF NOT EXISTS idx_review_decisions_status ON review_decisions(status, review_after, updated_at); + +CREATE TABLE IF NOT EXISTS reconciliation_sessions ( + id TEXT PRIMARY KEY, + account_id TEXT NOT NULL, + basis_date TEXT NOT NULL, + expected_balance INTEGER, + actual_balance INTEGER, + difference INTEGER, + status TEXT NOT NULL DEFAULT 'open', + closed_at TEXT NOT NULL DEFAULT '', + source_note TEXT NOT NULL DEFAULT '', + memo TEXT NOT NULL DEFAULT '', + operator TEXT NOT NULL DEFAULT 'operator', + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +); +CREATE UNIQUE INDEX IF NOT EXISTS idx_reconciliation_sessions_account_basis ON reconciliation_sessions(account_id, basis_date); +CREATE INDEX IF NOT EXISTS idx_reconciliation_sessions_status ON reconciliation_sessions(status, closed_at); + +INSERT OR REPLACE INTO schema_meta(key, value) VALUES ('schema_version', '11'); """ ACCOUNT_ADDITIVE_COLUMNS: dict[str, str] = { diff --git a/jarca_ledger_mcp/service.py b/jarca_ledger_mcp/service.py index 4792abb..9847313 100644 --- a/jarca_ledger_mcp/service.py +++ b/jarca_ledger_mcp/service.py @@ -13,6 +13,7 @@ from .application import cross_transfer_service as _cross_transfer_service from .application import imports_service as _imports_service from .application import import_transfer_services as _import_transfer_services from .application import reconciliation_service as _reconciliation_service +from .application import review_decision_service as _review_decision_service from .application import shared as _shared from .application import system_services as _system_services from .application import transactions_write_services as _transactions_write_services @@ -32,6 +33,7 @@ _PROXY_MODULES = ( _category_rules_write_services, _transaction_report_services, _reconciliation_service, + _review_decision_service, _imports_service, _import_transfer_services, _cross_transfer_service, diff --git a/tests/test_ledger_categories.py b/tests/test_ledger_categories.py index 4785272..331666b 100644 --- a/tests/test_ledger_categories.py +++ b/tests/test_ledger_categories.py @@ -6,7 +6,7 @@ from jarca_ledger_mcp import service def test_ledger_category_create_list_delete_reactivate(tmp_path): db_path = str(tmp_path / "ledger.sqlite3") health = service.health_check(db_path) - assert health["schema_version"] == "10" + assert health["schema_version"] == "11" created = service.create_ledger_category("반려동물", "사료", sort_order=250, memo="test", db_path=db_path) assert created["success"] is True diff --git a/tests/test_review_decision_workbench.py b/tests/test_review_decision_workbench.py new file mode 100644 index 0000000..ac96097 --- /dev/null +++ b/tests/test_review_decision_workbench.py @@ -0,0 +1,103 @@ +from __future__ import annotations + +from pathlib import Path + +from jarca_ledger_mcp import service +from jarca_ledger_mcp.db import init_db + + +def test_review_decision_and_reconciliation_schema_are_additive_idempotent(tmp_path: Path) -> None: + db_path = str(tmp_path / "validation.sqlite3") + init_db(db_path) + init_db(db_path) + + status = service.get_ledger_db_status(db_path, include_hash=False, include_integrity=True) + assert status["success"] is True + assert status["integrity_check"] == "ok" + assert status["table_counts"]["review_decisions"] == 0 + assert status["table_counts"]["reconciliation_sessions"] == 0 + assert service.health_check(db_path)["schema_version"] == "11" + + +def test_review_decision_round_trip_payload_sanitizes_sensitive_fields(tmp_path: Path) -> None: + db_path = str(tmp_path / "validation.sqlite3") + decision = service.upsert_review_decision( + "cross_transfer", + "tx_synthetic_1", + status="decided", + decision_type="account_transfer", + reason_code="matched_pair", + memo="synthetic memo", + operator="qc", + review_after="2026-07-31", + target_payload={"amount": 10000, "raw_payload": "SHOULD_NOT_PERSIST", "file_path": "/secret.pdf"}, + db_path=db_path, + ) + assert decision["success"] is True + saved = decision["review_decision"] + assert saved["status"] == "decided" + assert saved["decision_type"] == "account_transfer" + assert saved["target_payload"] == {"amount": 10000} + + held = service.hold_review_decision("cross_transfer", "tx_synthetic_1", memo="hold", db_path=db_path) + assert held["success"] is True + assert held["review_decision"]["status"] == "held" + + released = service.release_review_decision("cross_transfer", "tx_synthetic_1", memo="release", db_path=db_path) + assert released["success"] is True + assert released["review_decision"]["status"] == "pending" + + listed = service.list_review_decisions("cross_transfer", "tx_synthetic_1", db_path=db_path) + assert listed["success"] is True + assert listed["count"] == 1 + + +def test_reconciliation_session_round_trip_and_report_integration(tmp_path: Path) -> None: + db_path = str(tmp_path / "validation.sqlite3") + account = service.create_ledger_account( + "Synthetic Manual Account", + type="bank", + statement_status="manual_only", + last_balance=1_000_000, + last_synced_at="2026-06-30T23:59:00+09:00", + db_path=db_path, + )["account"] + service.create_ledger_transaction("2026-06-01", "income", 700_000, account_id=account["id"], db_path=db_path) + + session = service.upsert_reconciliation_session( + account["id"], + "2026-06-30", + expected_balance=1_000_000, + actual_balance=700_000, + status="open", + source_note="synthetic validation", + db_path=db_path, + ) + assert session["success"] is True + assert session["reconciliation_session"]["difference"] == 300_000 + + report = service.get_balance_reconciliation_report(db_path=db_path) + assert report["success"] is True + item = report["items"][0] + assert item["reconciliation_session"]["id"] == session["session_id"] + assert item["status"] == "REVIEW_NEEDED" + + closed = service.close_reconciliation_session(session_id=session["session_id"], db_path=db_path) + assert closed["success"] is True + assert closed["reconciliation_session"]["status"] == "closed" + indicators = service.get_review_operating_indicators(db_path=db_path)["indicators"] + assert indicators["last_reconciliation_closed_at"] + + +def test_additive_mcp_contract_surface_exposes_safe_review_tools() -> None: + from jarca_ledger_mcp.adapters.mcp import server + + tool_names = set(server.mcp._tool_manager._tools.keys()) + assert "list_review_decisions" in tool_names + assert "upsert_review_decision" in tool_names + assert "hold_review_decision" in tool_names + assert "release_review_decision" in tool_names + assert "list_reconciliation_sessions" in tool_names + assert "upsert_reconciliation_session" in tool_names + assert "close_reconciliation_session" in tool_names + assert not {name for name in tool_names if "delete_review" in name or "reset_review" in name} diff --git a/tests/test_service.py b/tests/test_service.py index d9eb3a3..c4be9c8 100644 --- a/tests/test_service.py +++ b/tests/test_service.py @@ -10,7 +10,7 @@ def test_health_check_initializes_db(tmp_path): db_path = tmp_path / "ledger.sqlite3" result = service.health_check(str(db_path)) assert result["success"] is True - assert result["schema_version"] == "10" + assert result["schema_version"] == "11" assert db_path.exists()