device-voice-h5/openspec/changes/update-device-exchange-shipping-entry-and-index-iccid/design.md

Context

The current device exchange popup stores recipient name, phone, and address in three flat fields, with recipient_address being a single string. The shipping submit API currently accepts only recipient_name, recipient_phone, and recipient_address, so the frontend must remain compatible unless the backend contract changes later.

The homepage already loads /api/c/v1/asset/info through assetApi.getInfo(identifier). The UI shows package name and expiry date in the top summary card, but the request now also returns data.iccid, which should be exposed without adding a second asset query.

Goals / Non-Goals

• Goals:

• Add a structured province/city/district selector using element-china-area-data

• Keep a separate detailed-address field for device exchange shipping info

• Allow users to paste one shipping-info string and prefill recipient name, phone, and address fields

• Preserve compatibility with the existing exchange shipping submit endpoint

• Show ICCID above the package name in the homepage top summary card

• Non-Goals:

• Redesign the backend exchange shipping API

• Add OCR or image-based recognition for shipping labels

• Normalize all historical address data outside the device exchange popup

Decisions

• Decision: Use element-china-area-data as the source for province/city/district options. Why: The request explicitly requires that dataset, and a static local area dataset avoids introducing extra network dependencies.

• Decision: Keep /api/c/v1/exchange/{id}/shipping-info unchanged and compose recipient_address on the client. Why: The existing API already accepts one address string, so the frontend can implement the new UX without blocking on backend changes.

• Decision: Recognize pasted shipping text with best-effort client-side parsing for mainland China phone numbers and common copied-address formats. Why: Users often copy a single line or multi-line string from chat or e-commerce apps, and partial automation reduces manual entry while still allowing correction.

• Decision: When reopening existing saved shipping info, prefill split fields with best-effort parsing and preserve the original address content if a full region split cannot be derived. Why: Existing records are already stored as a combined string, so the UI needs a no-data-loss compatibility path during the transition.

• Decision: Use data.iccid from the existing asset info response as the homepage summary source of truth. Why: The user explicitly named that field and endpoint, and it avoids mixing multiple ICCID sources in the header card.

Risks / Trade-offs

• Pasted shipping strings vary in format, so recognition must remain best-effort and allow manual correction before submission.
• Some previously saved combined addresses may not map cleanly back to province/city/district selections, so fallback behavior must preserve the original text.
• Adding a new area dataset dependency increases bundle size slightly, but it keeps address selection deterministic and local.

Migration Plan

1. Add the element-china-area-data dependency and wire it into the device exchange popup.
2. Introduce split address state, pasted-text parsing, and composed submit payload handling.
3. Update homepage asset state to read data.iccid and render it above package name.
4. Verify that existing exchange records remain editable without losing previously saved address content.