Archived

This repository has been archived on 2026-08-11. You can view files and clone it, but cannot push or open issues or pull requests.

kirukib 3778801ef5 Ship Gishen B2B institutional portal with polished layout and mock-backed flows.

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>

2026-08-06 21:18:23 +03:00

4.4 KiB

Raw Blame History

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

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[]`
`sample_updates`	`object[]`

CommitResult

Field	Type
`created`	`integer`
`updated`	`integer`
`skipped`	`integer`
`failed`	`integer`
`created_member_ids`	`string[]`

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)

{
  "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

../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.

4.4 KiB Raw Blame History