# Address Management

## Overview

This journey covers how customers view and edit their address in the portal. Addresses use a Japan-specific format with bilingual support -- the address is stored in both Japanese (for Salesforce) and romanized English (for WHMCS). The portal integrates with the Japan Post API to look up addresses from postal codes, ensuring accuracy. When a customer updates their address, the change is written to WHMCS (the billing system of record) and the portal cache is cleared so the new address appears immediately.

## Portal Flow

### Viewing Your Current Address

1. Navigate to **Account > Settings** (URL: `/account/settings`).
2. The **Address Information** card shows the current address on file:
   - Primary line (street/building details)
   - Secondary line (building name or room number, shown when provided)
   - City, prefecture (state), and postal code
   - Country (displayed as the full country name, e.g., "Japan")
3. An **Edit** button appears in the top-right corner of the address card.
4. If no address is on file, an empty state shows "No address on file" with an **Add Address** button.

### Editing Your Address

1. Click **Edit** on the address card. The display switches to a step-by-step address form.
2. The form uses **progressive disclosure** -- each step appears after the previous one is completed, with smooth animations. A progress indicator at the top shows how far along you are.

#### Step 1: Enter ZIP Code

1. Type a 7-digit Japanese postal code (e.g., "100-0001" or "1000001").
2. As soon as a valid 7-digit code is entered, the portal automatically looks up the address using the Japan Post API.
3. If the postal code is found, a **"Verified" badge** appears and the looked-up address is displayed in a green-bordered card showing:
   - **Prefecture** (in both romanized English and Japanese, e.g., "Tokyo / 東京都")
   - **City / Ward** (in both languages, e.g., "Minato-ku / 港区")
   - **Town** (in both languages, e.g., "Higashiazabu / 東麻布")
4. These fields are read-only -- they are automatically filled from the postal code lookup and cannot be manually edited. This ensures accuracy.
5. If the postal code is not found, an error is displayed.

#### Step 2: Street Address

1. After the postal code is verified, a **Street Address** field appears.
2. Enter the chome-banchi-go number in hyphenated format (e.g., "1-5-3" or "1-5").
3. The field validates the format: it must be numbers separated by hyphens (chome-banchi-go or chome-banchi).
4. Helper text guides the customer: "Enter chome-banchi-go (e.g., 1-5-3)"

#### Step 3: Residence Type

1. After entering a valid street address, a **Residence Type** selector appears.
2. Choose between two options:
   - **House** (with a house icon)
   - **Apartment** (with a building icon)
3. The selected option highlights with a colored border.

#### Step 4: Building Details

1. After selecting the residence type, **Building Details** fields appear.
2. **Building Name** (required): Enter the building or residence name.
   - For apartments: e.g., "Sunshine Mansion"
   - For houses: e.g., "Tanaka Residence"
3. **Room Number** (required for apartments only): Enter the room/unit number (e.g., "201"). This field only appears when "Apartment" is selected.

#### Completion

1. When all fields are filled, a green **"Address Complete"** success message appears.
2. Click **Save Address** to submit the changes.
3. A loading state shows "Saving..." while the address is being updated.
4. On success, the form closes and the address card shows the updated address.
5. Click **Cancel** at any time to discard changes and return to the address display.

### Address Form Summary

| Step | Field          | Required | Format                    | Source         |
| ---- | -------------- | -------- | ------------------------- | -------------- |
| 1    | ZIP Code       | Yes      | 7 digits (e.g., 100-0001) | Customer input |
| 1    | Prefecture     | Auto     | Read-only from lookup     | Japan Post API |
| 1    | City / Ward    | Auto     | Read-only from lookup     | Japan Post API |
| 1    | Town           | Auto     | Read-only from lookup     | Japan Post API |
| 2    | Street Address | Yes      | Hyphenated (e.g., 1-5-3)  | Customer input |
| 3    | Residence Type | Yes      | House or Apartment        | Customer input |
| 4    | Building Name  | Yes      | Free text                 | Customer input |
| 4    | Room Number    | Yes\*    | Free text                 | Customer input |

\*Room number is required only when "Apartment" is selected.

## What Happens in WHMCS

- WHMCS is the **system of record** for the customer's billing address.
- When the customer saves their address, the portal writes the update to WHMCS and clears the cached address data so the change appears immediately.
- The address is mapped to WHMCS fields as follows:

| WHMCS Field | Content                                  | Example                |
| ----------- | ---------------------------------------- | ---------------------- |
| address1    | Building name + Room number (apartments) | "Sunshine Mansion 201" |
| address2    | Town + Street address (romanized)        | "Higashiazabu 1-5-3"   |
| city        | City (romanized)                         | "Minato-ku"            |
| state       | Prefecture (romanized)                   | "Tokyo"                |
| postcode    | ZIP code                                 | "1060044"              |
| country     | Country code                             | "JP"                   |

- To verify the address update in WHMCS admin, navigate to **Clients > [Client Name] > Profile** and check the address fields.
- The updated address will appear on all future invoices generated by WHMCS.

## What Happens in Salesforce

- Salesforce receives address updates on the **Contact** record when the customer saves their address:

| Salesforce Field  | Content                          | Example            |
| ----------------- | -------------------------------- | ------------------ |
| MailingStreet     | Town + Street address (Japanese) | "東麻布1-5-3"      |
| MailingCity       | City (Japanese)                  | "港区"             |
| MailingState      | Prefecture (Japanese)            | "東京都"           |
| MailingPostalCode | ZIP code                         | "1060044"          |
| MailingCountry    | Country                          | "Japan"            |
| BuildingName\_\_c | Building name                    | "Sunshine Mansion" |
| RoomNumber\_\_c   | Room number                      | "201"              |

- Note that Salesforce stores the **Japanese** version of the address, while WHMCS stores the **romanized English** version. Both are derived from the same Japan Post lookup data.
- Address updates on the Salesforce Contact happen alongside the WHMCS update.

## Key Things to Verify

- **Postal code lookup**: Enter a valid Japanese postal code and verify the prefecture, city, and town auto-fill correctly in both Japanese and English. Try known postal codes (e.g., 1000001 for Chiyoda-ku, Tokyo).
- **Invalid postal code**: Enter an invalid or nonexistent postal code and verify an appropriate error message appears.
- **Progressive disclosure**: Verify that each step only appears after the previous step is completed (ZIP verified before street address appears, street address filled before residence type appears, etc.).
- **Apartment vs. House**: Select "Apartment" and verify the Room Number field appears. Select "House" and verify the Room Number field is hidden.
- **Address save to WHMCS**: After saving, check the WHMCS admin Client profile and verify address1, address2, city, state, and postcode are correctly populated with romanized English values.
- **Address save to Salesforce**: After saving, check the Salesforce Contact record and verify MailingStreet, MailingCity, MailingState, and MailingPostalCode contain the Japanese values.
- **Immediate reflection**: After saving, the address card in the portal immediately shows the updated address without needing a page refresh.
- **Invoice address**: After updating the address, generate a new invoice in WHMCS and verify it uses the updated address.
- **Cancel editing**: Click Edit, make changes, then click Cancel. Verify the address reverts to the previously saved values.
- **Validation**: Try submitting with an invalid street address format (e.g., "abc" instead of "1-5-3") and verify the form shows a validation error.
- **Error handling**: If the Japan Post lookup service is unavailable, verify the portal handles the error gracefully.