# Feature: Data migration

Org-scoped bulk import wizard for departments, packages, members, overrides, dependants, and verification IDs.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Pages

| Route | Purpose |
|-------|---------|
| `/migration` | Job history hub — status, dataset type, dates |
| `/migration/new` | Start wizard — choose dataset, upload file |
| `/migration/[jobId]` | Job detail — map, validate, preview, commit, rollback |

## Entities

- [`MigrationJob`](../backend/entities/migration-job.md)

## Endpoints

- [`migration.md`](../backend/endpoints/migration.md)

## Who can use

| Role | Access |
|------|--------|
| SUPER_USER | Full — create, commit, rollback |
| HR_ADMIN | Create, commit |
| FINANCE | Read job history |

## Supported datasets

| Type | Canonical fields |
|------|------------------|
| `departments` | name, code, parent_code, sub_limit |
| `packages` | name, code, allowance, copay, categories |
| `members` | full_name, phone, email, employee_id, department_code, package_code, start_date |
| `overrides` | member_key, allowance_cap, copay_percent |
| `dependants` | primary_employee_id, full_name, phone |
| `verification_ids` | employee_id, verification_id |
| `full_onboarding_pack` | Multi-sheet workbook |

## Wizard steps

1. **Choose dataset** — or full onboarding pack
2. **Upload** — Excel/CSV; download template per type
3. **Map columns** — source → canonical; save mapping profile
4. **Validate** — row-level errors/warnings; duplicate detection
5. **Preview** — create/update/skip counts + samples
6. **Commit** — async job with progress
7. **Complete** — error report download; optional rollback window

## Events

| Event | When |
|-------|------|
| `migration.job_started` | Commit begins |
| `migration.job_completed` | Success |
| `migration.job_failed` | Fatal error |

## Out of scope

- Clinical/Rx history
- Retail orders
- Admin credit/price lists

## Validation / errors

| Scenario | Code |
|----------|------|
| Unresolved validation errors on commit | `VALIDATION_FAILED` |
| Org pending | `ORG_PENDING` |
| Job already committed | `MIGRATION_JOB_LOCKED` |
| Rollback window expired | `ROLLBACK_EXPIRED` |
| Duplicate member in file | `DUPLICATE_IN_FILE` |

## Clinical withhold

Migration datasets exclude clinical data. No withhold on API responses.

## Relation to `/members/import`

Quick import creates a `MigrationJob` with `dataset_type=members` — same engine, simplified UI (skip mapping profile save).

## UI components

- Job list DataTable with status badges
- Stepper wizard in PageShell
- Column mapper: dropdown per canonical field
- Validation report table (row, severity, message)
- Preview diff summary cards
- Commit progress bar + error report download

## Mock files

```
src/mocks/migration.ts
src/types/migration.ts
```

## Related

- [members.md](members.md) — quick import path
- [org-departments.md](org-departments.md) — department dataset