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>
254 lines
4.0 KiB
Markdown
254 lines
4.0 KiB
Markdown
# 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`.
|