# 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}`