Federation Onboarding & Migration

The onboarding wizard at /federation-onboarding/wizard is a state machine: tenant-config → districts → clubs → players → review → complete. Drafts are accumulated as the operator advances, and only on complete does the platform materialise them into real TenantConfig, District, Club and PlayerProfile documents in a transactional sequence. Bulk import is stateless under /federation-onboarding/imports/* and supports three modes: validate (rows are parsed and rule-checked, nothing is written), dry_run (a full diff report classifies every row as new, update, unchanged or error) and apply (writes happen).

Validation respects TenantConfig.org_hierarchy_depth, so the same rule set evaluates a flat Norwegian import and a deep French one. Before validation runs, an idempotent cleansing pipeline normalises every field — names trimmed, code/district_code uppercased, status lowercased, email lowercased, phone numbers reduced to plus-prefix-and-digits, dates rewritten from DD/MM/YYYY, DD.MM.YYYY, DD-MM-YYYY, YYYY/MM/DD or YYYY.MM.DD into ISO YYYY-MM-DD when unambiguous (ambiguous MDY is left for the validator to reject). Every rewrite is reported as a warning on ImportRowReport with cleaned_count on ImportReport so the operator sees exactly what was changed.

The migration-plan generator is a side-effect-free function that returns an ordered MigrationPlan: prepare_source → create_sandbox → import_districts → validate_clubs → dry_run_clubs → apply_clubs → validate_players → apply_players → pilot_signoff → production_cutover, with source-specific warnings (FFBE/SBF/DPV quirks) and risk levels that auto-escalate on volume (>5000 players → high; >500 clubs on low baseline → medium). For flat hierarchies or requires_sandbox_pilot=false the plan strips the district and sandbox steps. Sandbox tenants wrap a cloned TenantConfig as a SandboxTenant with lifecycle active → promoted or active → discarded, idempotency-protected with 409 on invalid transitions; discard soft-deletes the underlying config for audit.

Rollback is captured by ImportBatch — every apply run records created_ids and pre-mutation update_snapshots; manual rollback uses /imports/batches/{id}/rollback, and a mid-apply failure triggers automatic rollback that stamps the batch auto_rolled_back. Both paths log structured audit events. The standalone-club path (F01.09, PL-T010) is a four-step admin wizard that moves Club, License, Match, Membership, Ranking and CalendarEvent documents from the standalone tenant into the target federation, sets the source read-only, and offers a 30-day rollback window with conflict-resolution policies (skip/rename/overwrite) on license-number and club-code collisions.