48 lines
3.6 KiB
Markdown
48 lines
3.6 KiB
Markdown
# BAT-016 Design: Review decision persistence and reconciliation workbench
|
|
|
|
## Design Status
|
|
- Status: completed
|
|
- Owner: 가웨인 direct recovery path; Kanban prohibited by user.
|
|
|
|
## 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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|