feat(mall): address book wave 7 frontend, contract, and archive

Live addresses domain for the mall: shared contract (AddressBookEntry + five client methods), mock adapter state v3, live domain pick, addresses page CRUD, checkout saved-address picker with manual fallback, demo seed, and the archived change plus address-book capability spec.
2026-09-18 16:00:05 +08:00
parent 5e866d08f4
commit c51e96ae41
17 changed files with 467 additions and 88 deletions
@@ -0,0 +1,34 @@
+# Proposal: replace-mock-api-wave-7
+
+## Why
+
+The address book is the last piece of the core purchase chain still on fixed mock data: `user/addresses.vue` renders `MOCK_ADDRESSES` with local-only edits, and checkout picks from the same static list. A real address entity closes the chain end-to-end against the live API, following the established wave pattern (per-domain live pick in the mall's api plugin, mock adapter stays as fallback).
+
+## What Changes
+
+- New `addresses` table: `user_id` FK (cascade), recipient/phone/country/region/city/line1/postal_code, `is_default`, timestamps; partial unique index enforces one default per user.
+- New route module `apps/api/src/routes/addresses.rs`: `GET/POST /api/addresses`, `PUT/DELETE /api/addresses/:id`, `POST /api/addresses/:id/default` — customer role only, ownership via `WHERE user_id =` (cross-user → 404). Default management is transactional (unset siblings in the same statement/transaction); the first address becomes default automatically; deleting the default promotes the most recent remaining address.
+- `packages/shared`: `AddressBookEntry` type + `listMyAddresses` / `createAddress` / `updateAddress` / `deleteAddress` / `setDefaultAddress` on `ApiClient`.
+- Mall mock adapter implements the same methods against its persisted state (seeded from `MOCK_ADDRESSES`), so mock mode keeps working and the rollback flag stays meaningful.
+- Mall pages: `user/addresses.vue` switches to real CRUD (existing `UiModal` form pattern, plus delete + set-default); `checkout/index.vue` loads the address list from the API (falls back to an inline manual form when the list is empty) and submits the selected one; `addresses` joins `LIVE_PICKS`/`DEFAULT_LIVE_DOMAINS`.
+- `scripts/seed-demo.mjs` seeds two demo addresses for `customer@vmall.local`, idempotently.
+- Integration tests in `apps/api/tests/addresses.rs` (fixtures from `tests/common/mod.rs`): CRUD happy path, cross-user 404, single-default invariant, delete-default promotion, role guard.
+
+## Capabilities
+
+### New Capabilities
+
+- `address-book`: per-customer saved shipping addresses with a single default.
+
+### Modified Capabilities
+
+- `frontend-mall`: the buyer center address page and checkout address selection use the live address API.
+
+## Impact
+
+`apps/api/migrations/0009_addresses.sql`, `apps/api/src/routes/{addresses.rs,mod.rs}`, router registration, `packages/shared/src/{types.ts,api.ts}`, `apps/mall/{mock/api.ts,plugins/api.ts,pages/user/addresses.vue,pages/checkout/index.vue,locales/user.ts,locales/checkout.ts}`, `scripts/seed-demo.mjs`, `apps/api/tests/addresses.rs`. The contract change rebuilds all three frontends.
+
+## Non-goals
+
+- No address auto-geocoding, no region cascader data (free-text region/city stays), no address selector inside the order-before flow beyond radio pick.
+- Coupons, favorites, wallet stats, marketing subsystems (seckill/collective/integral) and reviews remain mock/future work, unchanged.
@@ -0,0 +1,25 @@
+# Spec delta: address-book
+
+## ADDED Requirements
+
+### Requirement: Saved shipping addresses
+A customer SHALL be able to list, create, update and delete their own shipping addresses through the API. Every address operation SHALL be scoped to the authenticated customer; operating on another user's address SHALL return 404. Non-customer roles SHALL be rejected with 403.
+
+#### Scenario: manage own addresses
+- **WHEN** a customer creates, updates or deletes an address they own
+- **THEN** the change persists and appears in their address list
+
+#### Scenario: cross-user access
+- **WHEN** a customer requests an address id owned by a different user
+- **THEN** the API returns 404 as if the address did not exist
+
+### Requirement: Single default address
+Each customer SHALL have at most one default address, enforced by the database. The first saved address SHALL become the default. Setting a new default SHALL unset the previous one atomically. Deleting the default address SHALL promote the most recently created remaining address to default.
+
+#### Scenario: switch default
+- **WHEN** a customer marks address B as default while address A was default
+- **THEN** B is default and A is not, after one request
+
+#### Scenario: delete the default
+- **WHEN** a customer deletes their default address and other addresses remain
+- **THEN** the most recently created remaining address becomes the default
@@ -0,0 +1,17 @@
+# Spec delta: frontend-mall
+
+## ADDED Requirements
+
+### Requirement: Address book management
+The mall buyer center SHALL list, add, edit, delete and set-default the signed-in customer's saved addresses through the selected API adapter, replacing the previous fixed mock list.
+
+#### Scenario: manage addresses in the buyer center
+- **WHEN** a signed-in shopper opens `/user/addresses` and adds or edits an address
+- **THEN** the change persists through the adapter and survives a full page reload
+
+### Requirement: Checkout address selection
+Checkout SHALL offer the customer's saved addresses for selection, defaulting to their default address, and SHALL submit the selected address with the order. When the customer has no saved address, checkout SHALL provide an inline manual address form instead.
+
+#### Scenario: checkout with a saved address
+- **WHEN** a signed-in shopper with saved addresses checks out
+- **THEN** the default address is preselected and the created order carries the chosen address
@@ -0,0 +1,29 @@
+# Tasks: replace-mock-api-wave-7
+
+## 1. Backend
+- [x] `apps/api/migrations/0009_addresses.sql`: table + `addresses_one_default` partial unique index
+- [x] `apps/api/src/routes/addresses.rs`: list/create/update/delete/set-default; customer role; `WHERE user_id` ownership (404 cross-user); transactional default switching; first address auto-default; delete-default promotes latest remaining
+- [x] Register module + router; `AddressBookEntry` row model
+
+## 2. Shared contract
+- [x] `packages/shared/src/types.ts`: `AddressBookEntry`
+- [x] `packages/shared/src/api.ts`: `listMyAddresses`, `createAddress`, `updateAddress`, `deleteAddress`, `setDefaultAddress`
+
+## 3. Mock adapter
+- [x] `apps/mall/mock/api.ts`: same five methods over persisted mock state (seed from `MOCK_ADDRESSES`)
+- [x] `apps/mall/plugins/api.ts`: `addresses` live pick + `DEFAULT_LIVE_DOMAINS` entry
+
+## 4. Mall pages
+- [x] `user/addresses.vue`: real CRUD via `$api` (modal add/edit, delete, set-default)
+- [x] `checkout/index.vue`: load addresses from `$api`; radio select; inline manual form fallback when empty; submit selected address
+- [x] Locale keys (user/checkout domains, en+zh)
+
+## 5. Seed + tests
+- [x] `scripts/seed-demo.mjs`: two idempotent demo customer addresses
+- [x] `apps/api/tests/addresses.rs`: CRUD, cross-user 404, single-default invariant, delete-default promotion, non-customer 403
+
+## 6. Verify
+- [x] `cargo test -p vmall-api` green (docker vmall_test + Redis)
+- [x] `pnpm --filter @vmall/mall build` + shop-admin + admin builds green (contract change)
+- [x] `openspec validate replace-mock-api-wave-7 --strict` green
+- [x] Browser smoke: address CRUD in user center; checkout with saved address end-to-end