# 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`](../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`](../entities/migration-job.md) 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

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

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

```json
{
  "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`.