59 lines
2.6 KiB
Markdown
59 lines
2.6 KiB
Markdown
# KYC Wizard EU-Ready Smart Address Implementation
|
|
|
|
## Overview
|
|
|
|
Enhanced the `CompleteKycView.vue` Step 2 (Address) with an EU-ready country selector and smart ZIP→City auto-fill using the [zippopotam.us](https://www.zippopotam.us/) public API.
|
|
|
|
## Changes Made
|
|
|
|
### 1. Frontend: [`frontend/src/views/CompleteKycView.vue`](frontend/src/views/CompleteKycView.vue)
|
|
|
|
#### Template Changes (Step 2 - Address)
|
|
- **Country selector** added as the first field in Step 2 — a `<select>` bound to `kycForm.region_code` with options: HU, AT, SK, DE, RO (with flag emojis)
|
|
- **City field** now has a relative wrapper with a loading spinner (animated SVG) that appears when `isCityLoading === true`
|
|
- City input gets `opacity-60` class during loading for visual feedback
|
|
|
|
#### Script Changes
|
|
- **Import:** Added `watch` from Vue
|
|
- **New ref:** `isCityLoading` (boolean, default `false`)
|
|
- **Form state:** Added `region_code: 'HU'` to `kycForm` reactive object
|
|
- **Debounced watch on `address_zip`:**
|
|
- Clears previous timeout on each keystroke
|
|
- Triggers only when ZIP length >= 3
|
|
- 600ms debounce delay
|
|
- Calls `https://api.zippopotam.us/{country}/{zip}` using the selected `region_code`
|
|
- On success, auto-fills `kycForm.address_city` from `data.places[0]['place name']`
|
|
- Error handling with `console.error` (silent fail, user can still type city manually)
|
|
- `isCityLoading` reset in `finally` block
|
|
- **Submit payload:** Added `region_code: kycForm.region_code` to the API call
|
|
|
|
### 2. Backend Schema: [`backend/app/schemas/auth.py`](backend/app/schemas/auth.py)
|
|
|
|
- Added `region_code: Optional[str] = "HU"` to `UserKYCComplete` Pydantic model
|
|
|
|
### 3. Backend Service: [`backend/app/services/auth_service.py`](backend/app/services/auth_service.py)
|
|
|
|
- In `complete_kyc()`: Added `if kyc_in.region_code: user.region_code = kyc_in.region_code` to persist the selected country code to the user record
|
|
|
|
## Data Flow
|
|
|
|
1. User selects country (default: HU) → `kycForm.region_code`
|
|
2. User types ZIP code → debounced 600ms → `fetch(zippopotam.us/{country}/{zip})`
|
|
3. If found → `address_city` auto-filled; if not → silent fail, manual entry
|
|
4. On submit → `region_code` sent in payload → backend updates `users.region_code`
|
|
|
|
## EU Countries Supported
|
|
|
|
| Code | Country |
|
|
|------|---------|
|
|
| HU | Magyarország |
|
|
| AT | Ausztria |
|
|
| SK | Szlovákia |
|
|
| DE | Németország |
|
|
| RO | Románia |
|
|
|
|
## API Reference
|
|
|
|
- **zippopotam.us**: Free, no API key required. Returns JSON with `places[]` containing `place name`, `state`, etc.
|
|
- **Endpoint format**: `https://api.zippopotam.us/{country_code}/{zip_code}`
|