MAGIK-926: International Address Format Support

[MAGIKBIT]

Story 5 — International Address Format Support

Epic: EPIC-010 — Global Internationalization & Multi-Language Support (GitHub #100)
Priority: P1

User Story

As an international MagikTap user, I want address forms that adapt to my country's format (postal code position, province vs. state, required fields), so I can enter my address correctly.

Requirements

Country-Aware Address Fields

Field	US	Ethiopia	Eritrea	Mexico	Saudi Arabia
Street Line 1	Required	Required	Required	Required	Required
Street Line 2	Optional	Optional	Optional	Optional	Optional
City	Required	Required	Required	Required	Required
State/Province	State (dropdown)	Region (text)	Region (text)	Estado (dropdown)	Province (text)
Postal/ZIP Code	Required (5-digit)	Optional (4-digit)	Optional	Required (5-digit)	Required (5-digit)
Country	Required	Required	Required	Required	Required

Address Format Templates

• US: {street}\n{city}, {state} {zip}\n{country}
• Ethiopia: {street}\n{city}\n{region}\n{country}
• Mexico: {street}\n{zip} {city}, {state}\n{country}
• Saudi Arabia: {street}\n{city} {zip}\n{province}\n{country}
• Configurable per-country via AddressFormatService

Database Changes

• Rename/alias state → state_province in address fields (backward compatible)
• Add country_code (CHAR(2), ISO 3166-1 alpha-2) where missing
• Ensure postal_code is VARCHAR (not INT) — international codes may have letters

Dynamic Form Rendering

• Country selector triggers dynamic field update via AJAX or JS
• Show/hide fields based on country requirements
• Update labels (State → Region, ZIP → Postal Code) per country
• Validate postal code format per country regex

Acceptance Criteria

#	Criteria	Priority
1	Address form adapts fields when country changes	P0
2	Labels change per country (State vs Region vs Province)	P0
3	Postal code validation is country-aware	P1
4	Address displays in country-specific format	P1
5	Country dropdown includes all ISO 3166 countries	P1
6	Existing US addresses unaffected by migration	P0
7	vCard export uses correct address format	P2

Files to Create

• app/app.portalv2/app/Libraries/AddressFormatService.php
• app/app.portalv2/public/js/address-format.js — dynamic form behavior
• sql/migration_address_internationalization.sql

Files to Modify

• app/app.portalv2/app/Views/profile/settings.php — dynamic address form
• app/app.portalv2/app/Views/auth/registration.php — international address fields
• app/app.portalv2/app/Libraries/VcardService.php — international address in vCard