Gishen-Archive/Gishen-B2B
Archived
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
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.
8fe6d58a09
Gishen-B2B/docs/backend/endpoints/migration.md
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.0 KiB
Raw Blame History

Endpoints: Migration

Bulk data migration wizard — upload, map, validate, preview, commit, rollback.

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

Entity: ../entities/migration-job.md

GET /v1/migration/jobs

List migration jobs.
Auth Required
Roles SUPER_USER, HR_ADMIN, FINANCE (read history)

Query

?page=1&status=completed&dataset_type=members

Response 200

Paginated MigrationJob summaries.

POST /v1/migration/jobs

Create job + upload file.
Auth Required
Roles SUPER_USER, HR_ADMIN

Request

multipart/form-data:

Field Type Required
dataset_type string ✓
file file ✓

Response 201

{
  "data": {
    "id": "mig_01HNEW",
    "status": "uploaded",
    "file_name": "employees.xlsx"
  }
}

GET /v1/migration/jobs/:id

Job detail with validation/preview state.
Auth Required
Roles SUPER_USER, HR_ADMIN, FINANCE (read)

GET /v1/migration/templates/:dataset_type

Download Excel template.
Auth Required
Roles SUPER_USER, HR_ADMIN

Response 200

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Filename: gishen_migration_{dataset_type}_template.xlsx

PUT /v1/migration/jobs/:id/mapping

Save column mapping.
Auth Required
Roles SUPER_USER, HR_ADMIN

Request

{
  "column_mapping": {
    "Full Name": "full_name",
    "Mobile": "phone",
    "Emp ID": "employee_id"
  },
  "save_profile": true,
  "profile_name": "Default employee import"
}

Response 200

Job status: "mapping" → triggers validating.

POST /v1/migration/jobs/:id/validate

Re-run validation after mapping changes.
Auth Required
Roles SUPER_USER, HR_ADMIN

Response 200

Job with validation report. Status → validated or validated with errors.

POST /v1/migration/jobs/:id/preview

Generate preview diff.
Auth Required
Roles SUPER_USER, HR_ADMIN

Response 200

Job status: "preview_ready" with preview summary.

Errors

Code HTTP When
VALIDATION_FAILED 400 Unresolved errors

POST /v1/migration/jobs/:id/commit

Commit import.
Auth Required
Roles SUPER_USER, HR_ADMIN

Headers

Idempotency-Key: <uuid> (recommended)

Response 202

{
  "data": {
    "id": "mig_01HNEW",
    "status": "committing"
  }
}

Poll GET until completed or failed.

Errors

Code HTTP When
ORG_PENDING 422 Org not active
MIGRATION_JOB_LOCKED 409 Wrong status
VALIDATION_FAILED 400 Errors remain

Events

  • migration.job_started
  • migration.job_completed or migration.job_failed

POST /v1/migration/jobs/:id/rollback

Soft rollback within window.
Auth Required
Roles SUPER_USER

Response 200

status: "rolled_back" — deactivates members created in job where safe.

Errors

Code HTTP
ROLLBACK_EXPIRED 422

GET /v1/migration/jobs/:id/error-report

Download error CSV.
Auth Required
Roles SUPER_USER, HR_ADMIN

GET /v1/migration/mapping-profiles

Saved column mapping profiles for org.
Auth Required
Roles SUPER_USER, HR_ADMIN

UI routes

Route Endpoint(s)
/migration GET /v1/migration/jobs
/migration/new POST job wizard
/migration/[jobId] Job detail + wizard steps

Clinical withhold

Migration datasets exclude Rx/clinical history. No withhold on responses.

Shared engine

/members/import uses same validation/commit pipeline with dataset_type=members.