orion/app/modules/tenancy/docs/onboarding.md

# Store Onboarding System

The store onboarding system is a mandatory 4-step wizard that guides new stores through the initial setup process after signup. Dashboard access is blocked until onboarding is completed.

## Overview

The onboarding wizard consists of four sequential steps:

1. **Merchant Profile Setup** - Basic merchant and contact information
2. **Letzshop API Configuration** - Connect to Letzshop marketplace
3. **Product & Order Import Configuration** - Set up CSV feed URLs
4. **Order Sync** - Import historical orders with progress tracking

## User Flow

```
Signup Complete
      ↓
Redirect to /store/{code}/onboarding
      ↓
Step 1: Merchant Profile
      ↓
Step 2: Letzshop API (with connection test)
      ↓
Step 3: Product Import Config
      ↓
Step 4: Order Sync (with progress bar)
      ↓
Onboarding Complete
      ↓
Redirect to Dashboard
```

## Key Features

### Mandatory Completion
- Dashboard and other protected routes redirect to onboarding if not completed
- Admin can skip onboarding for support cases (via admin API)

### Step Validation
- Steps must be completed in order (no skipping ahead)
- Each step validates required fields before proceeding

### Progress Persistence
- Onboarding progress is saved in the database
- Users can resume from where they left off
- Page reload doesn't lose progress

### Connection Testing
- Step 2 includes real-time Letzshop API connection testing
- Shows success/failure status before saving credentials

### Historical Import
- Step 4 triggers a background job for order import
- Real-time progress bar with polling (2-second intervals)
- Shows order count as import progresses

## Database Model

### StoreOnboarding Table

| Column | Type | Description |
|--------|------|-------------|
| id | Integer | Primary key |
| store_id | Integer | Foreign key to stores (unique) |
| status | String(20) | not_started, in_progress, completed, skipped |
| current_step | String(30) | Current step identifier |
| step_*_completed | Boolean | Completion flag per step |
| step_*_completed_at | DateTime | Completion timestamp per step |
| skipped_by_admin | Boolean | Admin override flag |
| skipped_reason | Text | Reason for skip (admin) |

### Onboarding Steps Enum

```python
class OnboardingStep(str, enum.Enum):
    MERCHANT_PROFILE = "merchant_profile"
    LETZSHOP_API = "letzshop_api"
    PRODUCT_IMPORT = "product_import"
    ORDER_SYNC = "order_sync"
```

## API Endpoints

All endpoints are under `/api/v1/store/onboarding/`:

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/status` | Get full onboarding status |
| GET | `/step/merchant-profile` | Get merchant profile data |
| POST | `/step/merchant-profile` | Save merchant profile |
| POST | `/step/letzshop-api/test` | Test API connection |
| POST | `/step/letzshop-api` | Save API credentials |
| GET | `/step/product-import` | Get import config |
| POST | `/step/product-import` | Save import config |
| POST | `/step/order-sync/trigger` | Start historical import |
| GET | `/step/order-sync/progress/{job_id}` | Get import progress |
| POST | `/step/order-sync/complete` | Complete onboarding |

## Integration Points

### Signup Flow

When a store is created during signup, an onboarding record is automatically created:

```python
# In platform_signup_service.py
onboarding_service = OnboardingService(db)
onboarding_service.create_onboarding(store.id)
```

### Route Protection

Protected routes check onboarding status and redirect if not completed:

```python
# In store_pages.py
onboarding_service = OnboardingService(db)
if not onboarding_service.is_completed(current_user.token_store_id):
    return RedirectResponse(f"/store/{store_code}/onboarding")
```

### Historical Import

Step 4 uses the existing `LetzshopHistoricalImportJob` infrastructure:

```python
order_service = LetzshopOrderService(db)
job = order_service.create_historical_import_job(store_id, user_id)
```

## Frontend Implementation

### Template

`app/templates/store/onboarding.html`:
- Standalone page (doesn't use store base template)
- Progress indicator with step circles
- Animated transitions between steps
- Real-time sync progress bar

### JavaScript

`static/store/js/onboarding.js`:
- Alpine.js component
- API calls for each step
- Connection test functionality
- Progress polling for order sync

## Admin Skip Capability

For support cases, admins can skip onboarding:

```python
onboarding_service.skip_onboarding(
    store_id=store_id,
    admin_user_id=admin_user_id,
    reason="Manual setup required for migration"
)
```

This sets `skipped_by_admin=True` and allows dashboard access without completing all steps.

## Files

| File | Purpose |
|------|---------|
| `models/database/onboarding.py` | Database model and enums |
| `models/schema/onboarding.py` | Pydantic schemas |
| `app/services/onboarding_service.py` | Business logic |
| `app/api/v1/store/onboarding.py` | API endpoints |
| `app/routes/store_pages.py` | Page routes and redirects |
| `app/templates/store/onboarding.html` | Frontend template |
| `static/store/js/onboarding.js` | Alpine.js component |
| `alembic/versions/m1b2c3d4e5f6_add_store_onboarding_table.py` | Migration |

## Testing

Run the onboarding tests:

```bash
pytest tests/integration/api/v1/store/test_onboarding.py -v
```

## Configuration

No additional configuration is required. The onboarding system uses existing configurations:

- Letzshop API: Uses `LetzshopCredentialsService`
- Order Import: Uses `LetzshopOrderService`
- Email: Uses `EmailService` for welcome email (sent after signup)