feat: add mandatory vendor onboarding wizard
Implement 4-step onboarding flow for new vendors after signup: - Step 1: Company profile setup - Step 2: Letzshop API configuration with connection testing - Step 3: Product & order import CSV URL configuration - Step 4: Historical order sync with progress bar Key features: - Blocks dashboard access until completed - Step indicators with visual progress - Resume capability (progress persisted in DB) - Admin skip capability for support cases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
191
docs/features/vendor-onboarding.md
Normal file
191
docs/features/vendor-onboarding.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# Vendor Onboarding System
|
||||
|
||||
The vendor onboarding system is a mandatory 4-step wizard that guides new vendors 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. **Company Profile Setup** - Basic company 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 /vendor/{code}/onboarding
|
||||
↓
|
||||
Step 1: Company 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
|
||||
|
||||
### VendorOnboarding Table
|
||||
|
||||
| Column | Type | Description |
|
||||
|--------|------|-------------|
|
||||
| id | Integer | Primary key |
|
||||
| vendor_id | Integer | Foreign key to vendors (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):
|
||||
COMPANY_PROFILE = "company_profile"
|
||||
LETZSHOP_API = "letzshop_api"
|
||||
PRODUCT_IMPORT = "product_import"
|
||||
ORDER_SYNC = "order_sync"
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
All endpoints are under `/api/v1/vendor/onboarding/`:
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/status` | Get full onboarding status |
|
||||
| GET | `/step/company-profile` | Get company profile data |
|
||||
| POST | `/step/company-profile` | Save company 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 vendor is created during signup, an onboarding record is automatically created:
|
||||
|
||||
```python
|
||||
# In platform_signup_service.py
|
||||
onboarding_service = OnboardingService(db)
|
||||
onboarding_service.create_onboarding(vendor.id)
|
||||
```
|
||||
|
||||
### Route Protection
|
||||
|
||||
Protected routes check onboarding status and redirect if not completed:
|
||||
|
||||
```python
|
||||
# In vendor_pages.py
|
||||
onboarding_service = OnboardingService(db)
|
||||
if not onboarding_service.is_completed(current_user.token_vendor_id):
|
||||
return RedirectResponse(f"/vendor/{vendor_code}/onboarding")
|
||||
```
|
||||
|
||||
### Historical Import
|
||||
|
||||
Step 4 uses the existing `LetzshopHistoricalImportJob` infrastructure:
|
||||
|
||||
```python
|
||||
order_service = LetzshopOrderService(db)
|
||||
job = order_service.create_historical_import_job(vendor_id, user_id)
|
||||
```
|
||||
|
||||
## Frontend Implementation
|
||||
|
||||
### Template
|
||||
|
||||
`app/templates/vendor/onboarding.html`:
|
||||
- Standalone page (doesn't use vendor base template)
|
||||
- Progress indicator with step circles
|
||||
- Animated transitions between steps
|
||||
- Real-time sync progress bar
|
||||
|
||||
### JavaScript
|
||||
|
||||
`static/vendor/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(
|
||||
vendor_id=vendor_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/vendor/onboarding.py` | API endpoints |
|
||||
| `app/routes/vendor_pages.py` | Page routes and redirects |
|
||||
| `app/templates/vendor/onboarding.html` | Frontend template |
|
||||
| `static/vendor/js/onboarding.js` | Alpine.js component |
|
||||
| `alembic/versions/m1b2c3d4e5f6_add_vendor_onboarding_table.py` | Migration |
|
||||
|
||||
## Testing
|
||||
|
||||
Run the onboarding tests:
|
||||
|
||||
```bash
|
||||
pytest tests/integration/api/v1/vendor/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)
|
||||
Reference in New Issue
Block a user