# Runtime backup and broker/bank mapping hardening

Use this reference for FinanceManager work that touches productive runtime DBs, real broker/bank files, or pre-import mapping for PostFinance/True Wealth/Raiffeisen.

## Minimal runtime backup/restore pattern

Before broader productive imports, the finance CLI should expose and test a minimal DB safety loop:

- `finance backup-runtime-db`
  - writes only under the external runtime backups directory, never in the repo
  - filename includes a UTC timestamp
  - emits aggregate metadata only; redact or avoid printing sensitive paths if user asks for terse reporting
  - writes a `.sha256` sidecar checksum
- `finance verify-backup --file <backup-file>`
  - verifies file existence and checksum before any restore/import reliance
- `finance restore-runtime-db --from <backup-file> --yes`
  - requires explicit confirmation or `--yes`
  - refuses unchecked/tampered backups

Tests should cover:

- backup created outside repo
- restore into a test DB works
- checksum mismatch is detected
- Git-safety blocks DB/backup artifacts if placed under the repo

Run compile, full pytest, cleanup of `.pytest_cache`/`__pycache__`, Git-safety, commit and push after this block.

## Broker/bank structural mapping before import

For PostFinance, True Wealth and Raiffeisen files from Google Drive, do **structural analysis only** until the user explicitly approves a productive import:

1. Download/copy files only into external runtime import/temp directories.
2. Never place real DOCX/XLSX/CSV/PDF/DB/report artifacts in Git.
3. Inspect file type, tables/sheets/sections and field coverage, but do not echo real values, quantities, market values, balances, row contents or holdings in chat.
4. Treat current-holdings files as `initial_position_snapshot` / `initial_cash_snapshot`, not synthetic buys.
5. Produce a mapping/dry-run plan before any DB mutation.
6. Store only aggregate dry-run metadata if persisting dry-run evidence; do not store raw source rows in mapping tables.
7. Require verified runtime backup before any productive broker/bank import.

## Mapping schema foundation

Useful non-destructive tables:

- `instrument_mappings`: source instrument label/ISIN/ticker/exchange/currency -> canonical `instruments.instrument_id`; statuses such as `unmapped`, `selected`, `manual_review`, `rejected`.
- `platform_account_mappings`: source platform/account labels/currency -> canonical `platforms`/`accounts`.
- `broker_import_dry_runs`: source label/type/hash, detected sections, field coverage, quality flags, aggregate row counts only.

Canonical target tables remain:

- `instruments` for stock/ETF master data; ISIN is primary identity when available, ticker/exchange are supplementary.
- `positions_snapshot` for initial equity/ETF holdings snapshots.
- `cash_balances` with `source_type='initial_cash_snapshot'` for starting cash truths.
- `import_sessions`, `audit_log`, `alerts` for auditability and quality lifecycle.

## Source-specific structural learnings

### PostFinance DOCX

Typically contains multiple tables: cash/account summaries plus a position-like table. Structural fields often include product/name, quantity, currency, total/market value and entry/cost control fields. ISIN, exchange, clean ticker metadata, fees/taxes and a reliable table-level snapshot date may be absent or ambiguous.

Default flags: `missing_isin`, `snapshot_only`, `cost_basis_uncertain`, `market_value_legacy`, `needs_manual_review`.

### True Wealth DOCX

May contain a mixed table with cash/account rows and allocation/position-like rows. Cash/account context, currency and quantity/percentage-like structures can be present, but ISIN/ticker/cost basis/fees/taxes and separable market-value semantics may be unclear.

Default flags: `missing_isin`, `snapshot_only`, `cost_basis_uncertain`, `missing_fx` for foreign-currency rows without trusted FX, `needs_manual_review`.

### Raiffeisen XLSX overview

A compact overview workbook may only provide account/cash/control totals and aggregate depot/investment labels. If detailed instrument rows, ISIN/ticker and quantities are not structurally present, use it as a cash/account/control snapshot only and block productive instrument import until a detailed export is available.

Default flags: `snapshot_only`, `market_value_legacy`, `needs_manual_review`.

## Aggregate-only reporting template

When reporting back to the user after structural mapping or dry-runs, include only:

- source names and file types
- detected section/table/sheet counts
- field-presence yes/no
- candidate counts and blocked counts
- quality-flag counts
- warnings/errors
- Git-safety/test/commit/push status

Do **not** include prices, balances, quantities, market values, account numbers, raw row labels that reveal holdings, or file contents unless explicitly authorized.