50 lines
3.4 KiB
Markdown
50 lines
3.4 KiB
Markdown
## 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.
|