kirukib
3778801ef5
Deliver role-aware shell (sidebar, breadcrumbs, quick search, tables, detail/create layouts), locale-ready pages, shared backend/feature docs, and Vercel project config so HR, finance, and members can demo against typed mocks. Co-authored-by: Cursor <cursoragent@cursor.com>
105 lines
2.9 KiB
Markdown
105 lines
2.9 KiB
Markdown
# 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
|