# Multi-wallet crypto snapshots and Equity/ETF manage UI pattern

Use this reference when a controlled real-data crypto test reveals that one coin is spread across multiple wallet columns, or when extending the FinanceManager dashboard with manual stock/ETF management.

## Multi-wallet crypto initial snapshot

When importing a real XLSX snapshot for a single approved coin (for example BTC):

1. Treat **one coin** and **one holding** as different scopes. A coin may have multiple non-empty wallet columns.
2. If the user approves multi-wallet import, create/control exactly one `crypto_assets` row for the coin and one `crypto_holdings` row per non-empty wallet cell.
3. Preconditions before writing:
   - Runtime DB path is outside the repo.
   - Git status is clean and safety scan passes.
   - The asset is absent or matches the approved `coin_name`, `symbol`, `coingecko_id`, and mapping status.
   - Every non-empty wallet quantity parses with `Decimal` from text; never via float.
   - No existing `asset_id + wallet_id` holding exists for the approved coin/wallet pair.
   - Legacy CHF/snapshot values are ignored unless explicitly approved for provenance fields.
4. Write only the approved coin. Do not import neighboring coins from the same XLSX.
5. Create holding-level audit-log entries for every wallet holding. If the codebase has import sessions/history traces, verify those too.
6. Post-write verification must be aggregate-only in chat:
   - Approved asset exists.
   - Holding count equals the number of non-empty approved wallet cells.
   - No duplicate `asset_id + wallet_id` holdings.
   - Quantity columns are stored as SQLite `text`/Decimal strings.
   - Audit logs exist for each holding.
   - Crypto read model and report context include the approved coin.
   - Git-safety OK and Git status clean.
7. Never print real quantities, values, wallet addresses, raw rows, or source file contents in chat.

## SQLite Decimal storage pitfall

SQLite `NUMERIC` affinity may return inserted Decimal-looking text as `real`, especially for crypto/equity quantities and FX fields. For Decimal-sensitive finance data:

- Define quantity/price/fee/valuation/FX columns as `TEXT` where exactness matters.
- Format writes with `format(Decimal(value), "f")`.
- Add/verify migrations that rebuild existing tables to TEXT affinity when needed.
- Tests should assert both domain value preservation and `typeof(column) == 'text'` for representative rows.

This applies not only to crypto quantities but also to stock/ETF ledger transaction quantities, FX rates, original amounts, and CHF equivalents.

## Equity/ETF manual management UI pattern

For a synthetic-first manual stock/ETF management page analogous to Crypto Manage:

- Use ISIN as primary identification; ticker/exchange are optional helper fields.
- Do not import real PostFinance/TrueWealth/Raiffeisen files in the UI task unless separately approved.
- Store initial holdings as explicit `initial_position_snapshot`, not fake buys.
- Require confirmation before each write.
- Require notes for incomplete-history snapshots and manual adjustments.
- Support transaction types: `buy`, `partial_sell`, `full_sell`, `dividend`, `etf_distribution`, `fee`, `manual_adjustment`.
- Expose partial sell and full sell as distinct UI actions/tabs; a full sell must match the exact current position quantity and leave the position at zero.
- Store original currency and FX-to-CHF data; if FX is missing, persist `fx_status=missing` and create/return a data-quality warning rather than inventing CHF values.
- Dividends/distributions must not change position quantity.
- Sells must not make positions negative; full sell should match the full current quantity.
- Every write must create an audit-log entry.
- Keep dashboard render local/read-first; no market-data API calls during page render.

## Verification checklist

- Run targeted tests first, then full test suite.
- Compile all source/tests.
- Remove generated caches before safety scan.
- Run Git-safety before staging/push and after runtime-data operations.
- Use aggregate-only status reporting for real financial data.