# Current-import readiness cockpit: reuse-first implementation map

Use this reference when adding a finance-only view of imported-source freshness, business-date coverage, dated account balances, payroll setup, and performance calculability.

## Smallest vertical slice

Prefer a derived read model on the existing finance command-center path over a new import framework or persisted cockpit table:

1. Add a pure read-model builder to the existing command-center service.
2. Reuse the existing command-center endpoint and frontend request.
3. Add only frontend contract fields and a compact Systemstatus/detail rendering.
4. Keep import writes on each source's existing preview/confirm API.
5. Reuse canonical performance coverage/setup output; never recreate blocker logic in the cockpit.

A typical minimal edit set is the command-center service, frontend API types, command-center component, one backend read-model test module, and the existing command-center frontend test.

## Existing write paths to reuse

- Dated cash/account balances: `cash_account_snapshots`, `preview_cash_snapshot`, `confirm_cash_snapshot`, and the existing Cash page/API. These already preserve business date, source, audit receipt, and history.
- Household sources: `preview_household_import` / `confirm_household_import` with source profiles such as bank, card, and receipt imports. Preserve receipt detail as enrichment; it must not create a second money movement.
- Managed portfolio sources: keep dedicated TrueWealth and PostFinance preview/confirm services and summaries. PostFinance confirmation already materializes canonical cash/value/performance components.
- Payroll planning: derive setup notes from income templates and active plan amounts; do not introduce a payroll subsystem merely to display readiness.
- Performance: consume `build_performance_coverage` and `build_performance_setup` reason codes/status/next actions.

## Freshness and coverage semantics

Never collapse these timestamps or claims:

- `last_received_at`: when the system confirmed/received an import.
- `data_from` / `data_to`: business dates represented by the source data.
- `balance_as_of`: dated account snapshot used for current value.
- `freshness_status`: policy evaluation against the applicable business date.
- `coverage_status`: what the stored lineage can actually prove.

For transaction/receipt imports, grouping confirmed candidate lineage by `source_type` and taking min/max transaction dates proves **observed coverage**, not gap-free completeness. Report `observed`, `partial`, or `missing`; do not call it complete merely because endpoints exist.

Use the shared freshness evaluator with a source-appropriate policy. An explicit generic maximum age is safer than pretending card/receipt imports are bank balances. Keep source-specific next actions in the read model.

## Migration test

No migration is needed when the feature only:

- summarizes existing dated account snapshots;
- derives source business-date ranges and receipt/link status;
- derives payroll setup notes from existing plan rows;
- passes through canonical performance blockers.

A migration is necessary only when the product requires durable, auditable **gap-free statement coverage or completeness attestation** that current lineage cannot prove. In that case, persist immutable per-file coverage boundaries/status (or an equivalent attestation table) rather than inferring completeness from `MIN/MAX(transaction_date)`.

## Payroll safety

Salary-text detection does not justify automatic person/category assignment. If canonical data contains multiple salary categories, keep the transaction in a decision-needed state. The cockpit may distinguish:

- templates absent;
- templates present but planned amounts missing;
- detected salary rows awaiting person/category confirmation;
- fully configured state.

Link to the existing planning/review surfaces instead of creating a new payroll workflow.

## Performance blocker safety

Performance unavailability must remain structured backend output. Preserve canonical reasons such as missing opening/closing valuations, insufficient distinct valuation days, incomplete external-cashflow coverage, unclear scope classification, missing components, and missing/stale price or FX inputs. Never turn null/unavailable performance into zero in the API or UI.

## Verification checklist

- All expected sources appear even when no import exists.
- Business dates and receive timestamps are displayed separately.
- Household coverage does not overclaim completeness.
- Receipt enrichment does not double-count card spend.
- Latest balance uses snapshot business date, not import time.
- Payroll note appears/disappears for the right setup state.
- Performance blockers are pass-through from canonical services.
- Read model is deterministic, read-only, and redacts filenames, hashes, account references, and raw source payloads.
- Existing source-specific import and performance regression tests remain authoritative.