This commit is contained in:
sexygoat
@@ -0,0 +1,49 @@
|
||||
## 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.
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
The device exchange popup currently collects the shipping address as a single free-text field. This makes Chinese address entry error-prone, does not support selecting province/city/district from a standard area dataset, and forces users to manually rewrite recipient details even when they already copied a full shipping string from another app.
|
||||
|
||||
The homepage top summary card already loads asset information from `/api/c/v1/asset/info`, but it does not surface the `ICCID` value even though the response now provides `data.iccid`. Users need that value visible above the package name on the homepage.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Replace the single shipping-address input in `pages/device-exchange/device-exchange.vue` with province/city/district selection backed by `element-china-area-data` plus a separate detailed-address input
|
||||
- Add a pasteable shipping-info input so the page can recognize and prefill recipient name, phone number, and address from one copied string
|
||||
- Keep the existing exchange shipping submission API contract and assemble the selected region text together with the detailed address into `recipient_address`
|
||||
- Add an `ICCID` line above the package name in the homepage top summary card
|
||||
- Use `data.iccid` from `/api/c/v1/asset/info?identifier=...` as the homepage `ICCID` source of truth
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `device-exchange-shipping-entry`: Define structured shipping entry, pasted shipping-text recognition, and payload composition for the device exchange popup
|
||||
- `index-asset-summary`: Define homepage summary display rules for `ICCID`
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected code: `pages/device-exchange/device-exchange.vue`, `pages/index/index.vue`, `components/UserInfoCard.vue`, related address parsing helpers if introduced
|
||||
- Affected dependencies: `element-china-area-data`
|
||||
- Affected API usage: `/api/c/v1/exchange/{id}/shipping-info`, `/api/c/v1/asset/info`
|
||||
- No backend API contract change is required if the frontend continues submitting a composed `recipient_address` string
|
||||
@@ -0,0 +1,50 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Device exchange shipping entry SHALL collect a structured recipient address
|
||||
The system SHALL collect recipient name, recipient phone number, a province/city/district selection sourced from `element-china-area-data`, and a separate detailed address when the user fills shipping information for a pending device exchange.
|
||||
|
||||
#### Scenario: User opens the shipping popup for a pending exchange
|
||||
- **WHEN** the device exchange record is in the state that allows filling shipping information
|
||||
- **AND** the user opens the shipping popup
|
||||
- **THEN** the popup SHALL show editable fields for recipient name, recipient phone number, province/city/district, and detailed address
|
||||
|
||||
#### Scenario: User attempts to submit without a complete address
|
||||
- **WHEN** the user submits the shipping popup without selecting province/city/district or without entering a detailed address
|
||||
- **THEN** the system SHALL block submission
|
||||
- **AND** the system SHALL tell the user that the shipping address is incomplete
|
||||
|
||||
### Requirement: Device exchange shipping entry SHALL support pasted shipping-text recognition
|
||||
The system SHALL provide a way for the user to paste one shipping-info string and SHALL attempt to recognize recipient name, mainland China phone number, and address content from that string into editable form fields.
|
||||
|
||||
#### Scenario: Pasted shipping text contains recognizable recipient information
|
||||
- **WHEN** the user pastes a shipping-info string containing a recipient name, an 11-digit mainland China phone number, and address content
|
||||
- **THEN** the system SHALL prefill the recognized recipient name and phone number
|
||||
- **AND** the system SHALL prefill the recognized address content into the structured address form as far as it can infer
|
||||
|
||||
#### Scenario: Pasted shipping text is only partially recognizable
|
||||
- **WHEN** the user pastes a shipping-info string but the system cannot confidently extract every required field
|
||||
- **THEN** the system SHALL preserve the fields it can recognize
|
||||
- **AND** the user SHALL still be able to manually complete or correct the remaining fields before submission
|
||||
|
||||
### Requirement: Device exchange shipping submission SHALL preserve the existing API contract
|
||||
The system SHALL continue submitting `recipient_name`, `recipient_phone`, and `recipient_address` to `/api/c/v1/exchange/{id}/shipping-info`, and SHALL compose `recipient_address` from the selected province/city/district text together with the detailed address.
|
||||
|
||||
#### Scenario: User submits valid shipping information
|
||||
- **WHEN** the user submits the popup with a valid recipient name, a valid mainland China phone number, a selected province/city/district, and a detailed address
|
||||
- **THEN** the system SHALL call `/api/c/v1/exchange/{id}/shipping-info`
|
||||
- **AND** the payload SHALL keep `recipient_name` and `recipient_phone`
|
||||
- **AND** the payload SHALL send a composed `recipient_address` string containing the selected region text and the detailed address
|
||||
|
||||
### Requirement: Existing exchange shipping information SHALL remain editable without data loss
|
||||
The system SHALL preserve previously saved shipping information when reopening the popup and SHALL support best-effort conversion from a previously saved combined address string into the new structured address fields.
|
||||
|
||||
#### Scenario: Existing saved address can be split into region and detail
|
||||
- **WHEN** the popup opens for an exchange record that already has a saved `recipient_address`
|
||||
- **AND** the saved address can be matched to province/city/district data
|
||||
- **THEN** the system SHALL prefill the region selection and the detailed address
|
||||
|
||||
#### Scenario: Existing saved address cannot be fully split
|
||||
- **WHEN** the popup opens for an exchange record that already has a saved `recipient_address`
|
||||
- **AND** the saved address cannot be confidently split into province/city/district plus detailed address
|
||||
- **THEN** the system SHALL preserve the original saved address content for manual correction
|
||||
- **AND** the user SHALL still be able to complete a valid structured address before resubmitting
|
||||
@@ -0,0 +1,23 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Homepage top summary SHALL display ICCID above the package name
|
||||
The system SHALL display an `ICCID` line above the package name in the homepage top summary card after asset information is loaded.
|
||||
|
||||
#### Scenario: Asset info returns an ICCID value
|
||||
- **WHEN** the homepage loads asset information successfully
|
||||
- **AND** the response contains `data.iccid`
|
||||
- **THEN** the top summary card SHALL display `ICCID: <value>` above the package name
|
||||
|
||||
#### Scenario: Asset info does not return an ICCID value
|
||||
- **WHEN** the homepage loads asset information successfully
|
||||
- **AND** `data.iccid` is empty or missing
|
||||
- **THEN** the top summary card SHALL still display the `ICCID` field
|
||||
- **AND** the field SHALL show a stable fallback value
|
||||
|
||||
### Requirement: Homepage ICCID SHALL use the asset info response as the source of truth
|
||||
The system SHALL source the homepage `ICCID` value from `data.iccid` returned by `/api/c/v1/asset/info?identifier=...`.
|
||||
|
||||
#### Scenario: Homepage refreshes asset information
|
||||
- **WHEN** the homepage reads or refreshes asset information from `/api/c/v1/asset/info`
|
||||
- **THEN** the `ICCID` shown in the top summary card SHALL be updated from `data.iccid`
|
||||
- **AND** the header SHALL NOT depend on deriving the display value from a different ICCID field for this summary position
|
||||
@@ -0,0 +1,20 @@
|
||||
## 1. Device Exchange Shipping Entry
|
||||
|
||||
- [x] 1.1 Add `element-china-area-data` and integrate province/city/district selection into `pages/device-exchange/device-exchange.vue`
|
||||
- [x] 1.2 Replace the single shipping-address input with structured region selection plus a separate detailed-address input
|
||||
- [x] 1.3 Add a pasted shipping-info input and parse recipient name, recipient phone, and address content into editable form fields
|
||||
- [x] 1.4 Compose the selected region text and detailed address into `recipient_address` when submitting `/api/c/v1/exchange/{id}/shipping-info`
|
||||
- [x] 1.5 Preserve edit compatibility for previously saved combined addresses
|
||||
|
||||
## 2. Homepage ICCID Summary
|
||||
|
||||
- [x] 2.1 Read `data.iccid` from `assetApi.getInfo(identifier)` into homepage state
|
||||
- [x] 2.2 Render `ICCID` above the package name in `components/UserInfoCard.vue`
|
||||
- [x] 2.3 Show a stable fallback when `data.iccid` is absent
|
||||
|
||||
## 3. Regression Verification
|
||||
|
||||
- [x] 3.1 Verify the device exchange popup blocks submission when region selection or detailed address is incomplete
|
||||
- [x] 3.2 Verify a pasted shipping string can prefill recipient name, phone number, and address with manual correction still available
|
||||
- [x] 3.3 Verify the exchange shipping submit payload remains compatible with the existing backend contract
|
||||
- [x] 3.4 Verify the homepage top summary shows `ICCID` from `/api/c/v1/asset/info` above the package name
|
||||
Reference in New Issue
Block a user