# Import Wizard / Mapping Layer Pattern

Use this reference when building broker/bank import review flows for PostFinance, True Wealth, Raiffeisen, or similar sources.

## Purpose

Create a safe review and mapping process before any real Aktien/ETF/Cash data is written productively. Existing broker/bank files may be structurally useful but often lack enough clean metadata for automatic imports.

## User-approved sequencing

1. Build mapping and dry-run infrastructure first.
2. Keep Import Wizard default mode read-only.
3. Do not start later analytics modules in this phase: Monte Carlo, backtesting, rebalancing, scores, heatmaps, projections, or similar.
4. Do not productively import real PostFinance/True Wealth/Raiffeisen assets or cash without a separate explicit approval.
5. Report only aggregate counts/status; never echo real holdings, values, prices, quantities, raw rows, or file contents in chat.

## Instrument mapping rules

`instrument_mappings` should map broker/bank source labels to internal instruments.

Required/expected fields:

- `mapping_id`
- `source_name` / source identifier if legacy-compatible
- `source_platform`: PostFinance, True Wealth, Raiffeisen, Manuell/Sonstige
- `source_account`
- `source_label`
- `normalized_name`
- `isin`
- `ticker`
- `exchange`
- `currency`
- `asset_class`: equity, etf, cash, other
- optional `instrument_id`
- `mapping_status`: mapped, needs_manual_review, missing_isin, missing_ticker, ambiguous, ignored
- `confidence`
- `quality_flags_json`
- `notes`
- timestamps

Rules:

- ISIN is primary identification for equities/ETFs.
- Ticker + Exchange is only a fallback and should remain review-gated unless explicitly safe.
- Name alone is never enough for automatic productive mapping.
- Missing ISIN for equities/ETFs should create `needs_manual_review` plus `missing_isin` quality flag.
- Manual confirmation must require a non-empty note and create an audit-log entry.

## Platform/account mapping rules

`platform_account_mappings` should separate source account labels from internal platform/account IDs.

Fields:

- `mapping_id`
- `source_platform`
- `source_account_label`
- `normalized_platform`
- `normalized_account_name`
- `internal_platform_id`
- `internal_account_id`
- `account_type`: brokerage, cash, robo_portfolio, reserve, other
- `currency`
- `mapping_status`
- `quality_flags_json`
- `notes`
- timestamps

Rules:

- PostFinance, True Wealth and Raiffeisen must remain clearly separable.
- Cash and custody/brokerage accounts must not be mixed.
- Treat Raiffeisen as cash/control snapshot first when detailed instrument positions are missing.

## Broker import dry-run rules

`broker_import_dry_runs` stores aggregate review results only, not raw rows or productive ledger writes.

Fields:

- `dry_run_id`
- `source_platform`
- `source_file_type`: docx, xlsx, csv, pdf, unknown
- `source_filename_hash`
- `detected_snapshot_date`
- `snapshot_date_status`: clear, inferred, missing, conflict
- `rows_total`
- `candidate_positions`
- `candidate_cash_rows`
- `mapped_positions`
- `blocked_positions`
- `warnings_count`
- `errors_count`
- `quality_flags_json`
- `summary_json`
- `created_at`

Guardrails:

- Persist only hashes and aggregate summaries for real files.
- Strip raw `rows`, raw `values`, or equivalent row-level details from summary JSON.
- Dry-run must not write `positions_snapshot`, transaction ledger, cash ledger, or holdings.

## UI MVP pages

### Import Wizard

- Select source.
- Select/upload runtime file; never copy into repo.
- Show file type, detected structures, field coverage, candidate counts, cash-row counts, snapshot-date status.
- Show mapping summary and review items.
- Commit button visible but disabled in read-only mode.

### Manual Review Queue

Show unresolved issues:

- missing_isin
- missing_ticker
- ambiguous_name
- unclear accounts
- unclear snapshot dates
- blocked import rows
- missing_fx
- cost_basis_uncertain
- snapshot_only
- market_value_legacy

Actions may be prepared but should not productively create positions in this phase. Mapping confirmation requires audit log and note.

### Data Quality Center

Include active/resolved alerts plus missing prices, stale prices, missing FX, missing ISIN, missing CoinGecko ID, `snapshot_only`, `cost_basis_uncertain`, and stale active alerts that might be resolvable. Recheck/resolve buttons can be visible but should remain safe-gated until write mode is deliberately enabled.

### Safe/read-only indicator

Every import/review page should make the DB and write mode obvious:

- Runtime vs demo DB indicator where available.
- Read-only vs write-enabled mode.
- Warning before productive writes.
- Import commit buttons disabled by default.

## Test matrix

Add/maintain tests for:

- creating instrument mappings
- missing ISIN => `needs_manual_review`
- name-only source labels are not auto-mapped
- platform/account mappings for PostFinance, True Wealth, Raiffeisen cash/control
- broker dry-run stores summary and creates no productive positions
- Import Wizard modules import/render cleanly
- Manual Review Queue loads open mapping problems
- Data Quality Center shows missing ISIN/FX/prices
- read-only mode blocks commit actions
- audit log on manual mapping confirmation
- no real files in repo
- Git-safety remains OK

## Verification sequence

Before commit/push:

1. `PYTHONPATH=src python -m compileall -q src tests`
2. `PYTHONPATH=src pytest -q`
3. remove generated caches
4. `PYTHONPATH=src python -m jarvis_finance.cli.main git-safety-scan .`
5. `git status --short --branch`
6. commit and push only if clean/safe.