# Controlled Real Broker/Bank File Dry-Run Pattern

Use this after the synthetic Import Wizard / broker parser dry-run pipeline exists and the user explicitly approves real-file dry-runs for PostFinance, True Wealth, Raiffeisen, or similar sources.

## Purpose

Run real broker/bank files through the parser + dry-run + runtime review-item pipeline without creating productive portfolio truth. The goal is parser validation and review-queue population, not import.

## Guardrails

- Real files may be read only from runtime/temporary context; never copy them into the Git repo.
- Never print real row labels, quantities, values, balances, prices, account numbers, or raw file contents in chat.
- Report aggregate counts only: rows, candidate positions, candidate cash rows, mapped/blocked positions, review items, warnings/errors, quality-flag counts, snapshot-date status.
- Do not write productive `positions_snapshot`, ledger transactions, cash snapshots, crypto holdings, or final snapshots.
- Runtime review items may be created in `broker_import_review_items`; details remain runtime-only.
- Old dry runs should not be overwritten; create a new session/dry_run_id each run. Later add archive/discard/filter-by-dry-run rather than deleting history silently.

## Required sequence

1. Preflight:
   - `git status --short --branch` is clean and synchronized with `origin/main`.
   - `finance git-safety-scan .` returns `GIT_SAFETY_OK`.
   - Runtime DB, imports, reports, backups and secrets directories are outside the repo.
   - No real `.docx`, `.xlsx`, `.pdf`, `.csv`, `.sqlite*` artifacts exist in the repo.
   - Safe Mode / read-only productive-import guard remains the default.
2. Backup runtime DB:
   - `finance backup-runtime-db`
   - `finance verify-backup --file <backup-file>`
   - Report only whether backup/checksum verification succeeded and that it lives in the runtime backup folder.
3. For each source, copy/read the file only into a temp directory, parse it, run the dry-run pipeline, commit only dry-run/review-item runtime rows, then delete temp files.
4. Verify Review Queue and Data Quality Center aggregate the new review items and flags.
5. Verify productive counts did not change: `positions_snapshot`, transactions/ledger tables, and cash snapshot/ledger tables as applicable.
6. Run compile, pytest, Git-safety, and final Git status.
7. If code changed due to parser or DQ fixes, commit/push only code and synthetic tests; never commit real files or real fixtures.

## Source-specific interpretation

### PostFinance

- Expect positions plus possible cash/account rows.
- If identifiers are missing, all name-only rows must stay blocked/open for review with `missing_isin`/`missing_ticker` and `needs_manual_review`.
- Snapshot/cost-basis fields from statements are control/provenance data, not fabricated buys.

### True Wealth

- Treat ETF-like rows as review candidates unless ISIN/ticker/exchange mapping is reliable.
- Cash rows are control/review candidates.
- If no FX is available for non-CHF rows, flag `missing_fx`; do not invent CHF precision.

### Raiffeisen

- Be defensive: treat as cash/control snapshot first.
- Aggregate depot/anlagen rows without instrument details must be `aggregate_only`/`missing_instrument_details` and blocked, not imported as positions.

## Data Quality Center pitfall

Blocked review items are still active data-quality work. Aggregate review quality flags over `review_status IN ('open','blocked')`, not just `open`, otherwise Raiffeisen `aggregate_only`/`missing_instrument_details` issues disappear from the Data Quality Center.

Add/keep a synthetic test proving blocked aggregate-only review items are included in DQ flag counts.

## Aggregate-only report template

For each source report:

- rows_total
- candidate_positions
- candidate_cash_rows
- mapped_positions
- blocked_positions
- review_items_created
- warnings_count
- errors_count
- snapshot_date_status
- quality_flags_summary

Also report:

- backup created/verified/checksum OK
- Git-safety before/after
- Review Items per source
- Manual Review Queue visibility
- Data Quality Center visibility
- whether productive DB position/transaction/ledger counts stayed unchanged
- commit hash and push status if code changed