2026.06.04 frontend építés közben

docs/kyc_eu_smart_address_implementation.md

@@ -0,0 +1,58 @@
+# 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}`