# Budget/Cashflow source-aware import review pattern

Use this when correcting Budget/Cashflow imports after CSV-derived review candidates are too granular or when multiple sources overlap (credit card, Migros/Cumulus, AKB/Raiffeisen, manual bookings).

## Scope and safety

- Keep this as an import-logic/review sprint, not a new analytics architecture.
- Runtime DB backup first; verify backup exists, is outside Git, and checksum passes.
- Report only aggregate counts/statuses; do not print real amounts, raw rows, source file contents, account IDs, or secrets.
- Real CSV/XLS/XLSX files and the runtime DB stay outside Git.
- Preserve Dry run → Review → Confirm. Do not confirm productive transactions unless explicitly approved.

## Source-of-truth precedence

1. **Migros CSV** is source of truth for Migros expenses.
   - Credit-card rows matching Migros/Migrol/Cumulus-style merchant text should become `covered_by_migros` or ignored for booking, not duplicate expenses.
   - Migros article rows may remain as internal detail data, but normal user review must show receipt/transaction candidates, not thousands of line items.
   - Group Migros receipts by stable receipt keys such as date, time, branch/store, register, and transaction number where available.
2. **Credit-card CSV** is source of truth for non-Migros card payments: subscriptions, online purchases, travel, restaurants, Galaxus, etc.
   - Safe subscription merchants such as Apple/Apple.com, Google, Amazon Prime, Netflix, Disney/DisneyPlus may auto-map to subscriptions if not duplicate.
   - Galaxus remains review-required and splittable; do not final-categorize it automatically.
3. **Bank CSVs (AKB/Raiffeisen)** are source of truth for salary/income, transfers, fixed costs, rent, insurance, reimbursements, taxes, and bank payments.
   - Internal own-account transfers between AKB/Raiffeisen must not count as income/expense. Mark as transfer candidates.
   - Income detection can create income candidates, but ambiguous bank rows remain in review.
4. **Manual bookings** handle missing transactions, corrections, cash payments, special cases, and non-imported items.

## Review UX/API requirements

- Normal review must not be flooded by detail/article rows.
- Provide tabs/filters for: all, auto-assigned, needs review, duplicates, transfers, Galaxus, Migros over-threshold, bank transfers, income, ignored/covered.
- Review actions should be audited: change category, create split, ignore, mark transfer, and batch-confirm only safe candidates.
- Auto decisions must store rule/classification/reason/source-priority metadata so the user can understand and reverse them.

## Runtime cleanup recipe for too-granular Migros imports

1. Inspect candidate tables aggregate-only to count open Migros-like rows and likely article-level rows.
2. Create and verify runtime DB backup.
3. Mark old article-level candidates `superseded` (or archive/delete only if the schema already supports it) with an audit/cleanup event.
4. Re-import Migros as receipt-level candidates; store article rows in a detail table keyed to the receipt candidate.
5. Re-run credit-card import with Migros-card rows marked `covered_by_migros`.
6. Verify productive transaction counts did not increase unless Confirm was explicitly approved.

## Test matrix

- Migros article rows aggregate into one receipt candidate.
- Migros article rows do not appear in normal review.
- Credit-card Migros rows become `covered_by_migros`.
- Apple/Google/Amazon Prime/Netflix/Disney variants map to subscription candidates.
- Galaxus stays review-required and splittable.
- Duplicate candidates are recognized before safe auto-confirm.
- Bank salary/income rows become income candidates.
- AKB/Raiffeisen internal transfers become transfer candidates, not income/expense.
- Review actions are audited: category change, split, ignore, transfer mark, batch confirm.
- Safety checks block real CSV/XLS/DB artifacts from Git and scan source/build artifacts for secrets.

## Completion report shape

Include yes/no for: Migros article cleanup, Migros receipt aggregation, credit-card rules, AKB/Raiffeisen profiles, transfer recognition, income recognition, review UX, recategorization, MVP-light rule engine, productive import. Include counts by source/classification, test/build results, Git-safety, commit hash, push status, and open decisions — without amounts or raw rows.