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>
167 lines
4.4 KiB
Markdown
167 lines
4.4 KiB
Markdown
# Entity: Migration job
|
|
|
|
Batch import job for onboarding org data from Excel/CSV — departments, packages, members, overrides, dependants, verification IDs.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
## Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
|-------|------|----------|-------|
|
|
| `id` | `string` | ✓ | `mig_*` |
|
|
| `org_id` | `string` | ✓ | |
|
|
| `created_by` | `string` | ✓ | User id |
|
|
| `dataset_type` | `MigrationDatasetType` | ✓ | |
|
|
| `status` | `MigrationJobStatus` | ✓ | |
|
|
| `file_name` | `string` | ✓ | Original upload |
|
|
| `file_storage_key` | `string` | | Server-side blob ref |
|
|
| `column_mapping` | `ColumnMapping` | | Source → canonical |
|
|
| `mapping_profile_id` | `string` | | Saved profile for reuse |
|
|
| `validation` | `ValidationReport` | | After parse |
|
|
| `preview` | `PreviewSummary` | | Before commit |
|
|
| `commit_result` | `CommitResult` | | After commit |
|
|
| `error_report_url` | `string` | | Downloadable CSV of failures |
|
|
| `rollback_until` | `Timestamp` | | Soft rollback window |
|
|
| `started_at` | `Timestamp` | | |
|
|
| `completed_at` | `Timestamp` | | |
|
|
| `created_at` | `Timestamp` | ✓ | |
|
|
| `updated_at` | `Timestamp` | ✓ | |
|
|
|
|
### MigrationDatasetType
|
|
|
|
```
|
|
departments | packages | members | overrides | dependants | verification_ids | full_onboarding_pack
|
|
```
|
|
|
|
### MigrationJobStatus
|
|
|
|
```
|
|
uploaded | mapping | validating | validated | preview_ready | committing | completed | failed | rolled_back
|
|
```
|
|
|
|
### ColumnMapping
|
|
|
|
```typescript
|
|
Record<string, string> // sourceColumn → canonicalField
|
|
// e.g. { "Dept Name": "department_name", "Emp ID": "employee_id" }
|
|
```
|
|
|
|
### ValidationReport
|
|
|
|
| Field | Type |
|
|
|-------|------|
|
|
| `total_rows` | `integer` |
|
|
| `error_count` | `integer` |
|
|
| `warning_count` | `integer` |
|
|
| `rows` | `ValidationRow[]` |
|
|
|
|
### ValidationRow
|
|
|
|
| Field | Type |
|
|
|-------|------|
|
|
| `row_number` | `integer` |
|
|
| `severity` | `error` \| `warning` |
|
|
| `code` | `string` |
|
|
| `message` | `string` |
|
|
| `field` | `string` |
|
|
|
|
Common validation codes: `MISSING_REQUIRED`, `DUPLICATE_IN_FILE`, `DUPLICATE_MEMBER`, `INVALID_PHONE`, `UNKNOWN_PACKAGE_CODE`, `UNKNOWN_DEPARTMENT`.
|
|
|
|
### PreviewSummary
|
|
|
|
| Field | Type |
|
|
|-------|------|
|
|
| `create_count` | `integer` |
|
|
| `update_count` | `integer` |
|
|
| `skip_count` | `integer` |
|
|
| `sample_creates` | `object[]` | First N rows |
|
|
| `sample_updates` | `object[]` | |
|
|
|
|
### CommitResult
|
|
|
|
| Field | Type |
|
|
|-------|------|
|
|
| `created` | `integer` |
|
|
| `updated` | `integer` |
|
|
| `skipped` | `integer` |
|
|
| `failed` | `integer` |
|
|
| `created_member_ids` | `string[]` | For rollback scope |
|
|
|
|
## Validation rules (job lifecycle)
|
|
|
|
| Transition | Rule | Error code |
|
|
|------------|------|------------|
|
|
| → `committing` | Org must be `active` | `ORG_PENDING` |
|
|
| → `committing` | No unresolved errors | `VALIDATION_FAILED` |
|
|
| → `committing` | Status must be `preview_ready` | `MIGRATION_JOB_LOCKED` |
|
|
| Rollback | Before `rollback_until` | `ROLLBACK_EXPIRED` |
|
|
|
|
## Clinical withhold
|
|
|
|
Migration datasets exclude clinical/Rx history. No withhold concerns on entity itself.
|
|
|
|
## Out of scope
|
|
|
|
- Clinical/Rx history
|
|
- Retail orders
|
|
- Admin credit/price lists
|
|
|
|
## Sample payload (completed)
|
|
|
|
```json
|
|
{
|
|
"id": "mig_01HJOB001",
|
|
"org_id": "org_01HQXYZ",
|
|
"created_by": "usr_01HSUPER",
|
|
"dataset_type": "members",
|
|
"status": "completed",
|
|
"file_name": "employees_march_2026.xlsx",
|
|
"column_mapping": {
|
|
"Full Name": "full_name",
|
|
"Mobile": "phone",
|
|
"Emp ID": "employee_id",
|
|
"Dept": "department_code",
|
|
"Plan": "package_code"
|
|
},
|
|
"validation": {
|
|
"total_rows": 500,
|
|
"error_count": 3,
|
|
"warning_count": 12,
|
|
"rows": []
|
|
},
|
|
"preview": {
|
|
"create_count": 487,
|
|
"update_count": 10,
|
|
"skip_count": 3
|
|
},
|
|
"commit_result": {
|
|
"created": 487,
|
|
"updated": 10,
|
|
"skipped": 3,
|
|
"failed": 0,
|
|
"created_member_ids": ["mbr_...", "..."]
|
|
},
|
|
"rollback_until": "2026-03-12T10:00:00Z",
|
|
"started_at": "2026-03-11T09:00:00Z",
|
|
"completed_at": "2026-03-11T09:45:00Z",
|
|
"created_at": "2026-03-11T08:30:00Z",
|
|
"updated_at": "2026-03-11T09:45:00Z"
|
|
}
|
|
```
|
|
|
|
## Events
|
|
|
|
| Event | When |
|
|
|-------|------|
|
|
| `migration.job_started` | Commit begins |
|
|
| `migration.job_completed` | Success |
|
|
| `migration.job_failed` | Fatal error |
|
|
|
|
## Related endpoints
|
|
|
|
- [`../endpoints/migration.md`](../endpoints/migration.md)
|
|
|
|
## Relation to `/members/import`
|
|
|
|
Quick member import shares the same validation engine; creates a simplified `MigrationJob` with `dataset_type=members` or a lightweight `ImportJob` alias.
|