feat: wave 2 migration (P3, P5, P7 openspec changes)

Implements, verifies, and archives the three remaining Wave 2 changes from
openspec/MIGRATION-PLAN.md.

- add-wallet-settlement (P3): demo recharge, guarded withdrawal freeze and
  one-time admin review, paginated own fund entries, idempotent per-shop
  weekly/monthly settlement statements with commission rate and one-time
  payout confirmation.
- add-merchant-onboarding (P5): personal/enterprise applications with one live
  application per user, guarded review with mandatory rejection reason, and
  transactional shop + owner provisioning returning one-time credentials;
  mall onboarding/status pages and an admin review console.
- add-membership-messaging (P7): platform member levels, append-only growth
  accrual on order completion with guarded one-way leveling, order/shipment/
  refund system messages with unread/read state and soft deletion, plus the
  mall header unread badge.

Backend: migrations 0019-0023, new wallet, settlement, merchant_onboarding,
membership and messaging modules, event hooks in order/fulfillment/aftersale,
and integration suites for each. Shared contract extended and all three
frontends updated; code indexes, domain docs, backend guidelines and the
migration tracker synced.

Verification: cargo test -p vmall-api green twice consecutively; mall, admin
and shop-admin builds pass; browser smoke on every new surface; openspec
validate --all --strict green (33 passed).

The three changes share the @vmall/shared contract, the mall mock adapter and
per-app locale/nav files, so they are committed together to keep every commit
buildable.

docs/TBD-marketing.md

@@ -85,6 +85,11 @@ Recorded so the gap is explicit, not because all of them belong in scope:
   templates (by piece/weight, first+additional fees, free thresholds, region overrides),
   server-side checkout fee computation with per-item snapshots, and a shipping-company
   dictionary validated at ship time.
+- [x] **Merchant onboarding / 商家入驻** — implemented live as `add-merchant-onboarding`:
+  the mall `/merchant/join` + `/merchant/status` pages call the real backend through the
+  `merchantOnboarding` live domain, and the admin review console calls the admin API. No
+  fixture-driven onboarding surface remains in `apps/mall/mock`, so nothing is listed here
+  as a holdout. Wallet/withdrawal and settlement holdouts are likewise live (`add-wallet-settlement`).
 
 ## Deferred designs from general B2B2C storefronts
 

docs/backend-guidelines.md

@@ -33,8 +33,39 @@ UPDATE skus SET stock = stock - $2 WHERE id = $1 AND stock >= $2
 
 -- one-time flag (reply, reopen): guard on the empty state
 UPDATE product_reviews SET reply = $2 WHERE id = $1 AND reply IS NULL
+
+-- one-time review out of a pending state (wallet withdrawals, payouts)
+UPDATE wallet_withdrawals SET status = $2, reviewed_by = $3, reviewed_at = now()
+ WHERE id = $1 AND status = 'pending'          -- 0 rows → ApiError::Conflict
 ```
 
+Idempotent generation guarded by a unique index (settlement statements): insert
+with `ON CONFLICT (<cols>) DO NOTHING RETURNING id`; a `None` result means a
+repeat or a racing request won, so re-read the existing row and return it
+unchanged instead of recomputing.
+
+"At most one live row per owner" (merchant applications: one `pending`/`approved`
+per user) is a **partial unique index** — `UNIQUE (user_id) WHERE status IN (...)`
+— checked first in the service for a friendly 409 and relied on as the
+concurrency backstop via `unique_conflict`. Transactional provisioning (approval
+creating a shop + owner account) reads the row `FOR UPDATE`, provisions, then
+runs the guarded status flip last so any failure rolls the whole thing back.
+
+Event side effects (membership growth, system messages) run **inside the
+transition's transaction** and are made idempotent by a partial unique index plus
+`ON CONFLICT DO NOTHING`, so a retried handler cannot double-write:
+
+```sql
+-- one message per customer, kind, and reference
+INSERT INTO messages (...) VALUES (...)
+ON CONFLICT (user_id, kind, reference_type, reference_id)
+    WHERE reference_id IS NOT NULL DO NOTHING
+```
+
+A per-customer ledger total (growth) serializes on `SELECT id FROM users WHERE
+id = $1 FOR UPDATE`, then reads `COALESCE(SUM(delta),0)::bigint` and appends the
+entry carrying the new running total.
+
 Multi-row `FOR UPDATE` must `ORDER BY` primary key. Ledger writes are
 append-only: change a balance only via `account::service::credit/debit`
 inside the caller's transaction, never by writing an absolute balance.
@@ -74,3 +105,11 @@ endpoints especially. Mind pipefail: `cargo test | grep` hides failures.
 3. Add the column to **every** SELECT/RETURNING list for that table.
 4. Extend INSERT binds if writable.
 5. Mirror in `packages/shared/src/types.ts`.
+
+Nuance: a column that only one module writes and reads may stay out of the
+shared `models.rs` row when adding the field would force every existing
+`SELECT`/`RETURNING` list for that table to change. Example:
+`orders.completed_at` (settlement period attribution) is written by the order
+completion transition and read by `modules/settlement/repo.rs`; `models::Order`
+does not carry it. Also remember `updated_at` is not a completion timestamp —
+refunds bump it — so period attribution needs a dedicated column.

docs/code_index/consoles.md

@@ -17,6 +17,8 @@ per page. Navigation is a static list in each `app.vue`.
 | `pages/invoices.vue` | invoice issuing |
 | `pages/freight-templates.vue` | freight templates + region rules |
 | `pages/shop-profile.vue` | own shop profile self-edit |
+| `pages/settlements.vue` | own-shop statements: list/detail, idempotent generation |
+| `pages/shop-account.vue` | shop-owner wallet summary, withdrawal request/history, fund entries |
 
 ## apps/admin (platform console, :3002)
 
@@ -30,3 +32,7 @@ per page. Navigation is a static list in each `app.vue`.
 | `pages/content.vue`, `pages/brands.vue` | storefront content, brand registry |
 | `pages/currencies.vue` | currency registry + rates |
 | `pages/points-products.vue`, `pages/points-orders.vue` | points mall ops |
+| `pages/withdrawals.vue` | withdrawal review queue (approve/reject once, 409 feedback) |
+| `pages/settlements.vue` | commission rate, statement list/detail, idempotent generation, one-time payout confirmation |
+| `pages/merchant-applications.vue` | merchant application review queue, detail, approve/reject, one-time owner credentials |
+| `pages/member-levels.vue` + `components/MemberLevelForm.vue` | member level catalog CRUD (bilingual, unique threshold, in-use delete rejection) |

docs/code_index/index.md

@@ -10,7 +10,7 @@ files it lists.**
 | Post-order | aftersales/refunds, reviews | [code_index/post-order.md](post-order.md) |
 | Catalog | products, SKUs, categories, brands | [code_index/catalog.md](catalog.md) |
 | Marketing | coupons, flash sales, group buying, points | [code_index/marketing.md](marketing.md) |
-| Platform | identity, accounts/ledger, shops, storefront content, currencies, addresses | [code_index/platform.md](platform.md) |
+| Platform | identity, accounts/ledger, wallet, settlement, merchant onboarding, membership & messages, shops, storefront content, currencies, addresses | [code_index/platform.md](platform.md) |
 | Shared contract | types, API client, locales, UI components | [code_index/shared.md](shared.md) |
 | Storefront app | mall pages, mock adapter, live-domain wiring | [code_index/mall.md](mall.md) |
 | Console apps | shop-admin, admin pages | [code_index/consoles.md](consoles.md) |

docs/code_index/mall.md

@@ -12,10 +12,16 @@ Guidelines: `docs/frontend-guidelines.md`.
 | `pages/search.vue`, `pages/goods/[id].vue` | catalog browsing; goods detail has reviews tab |
 | `pages/cart.vue`, `pages/checkout/*` | cart and checkout (address → quote → submit → pay → success) |
 | `pages/stores/*` | store directory + store detail |
-| `pages/user/*` | buyer center: orders, aftersales, reviews, coupons, addresses, invoices, favorites |
+| `pages/user/*` | buyer center: orders, aftersales, reviews, coupons, addresses, invoices, favorites, wallet |
+| `pages/user/wallet.vue` | wallet balances, paginated ledger entries, demo recharge, withdrawal request/history |
+| `pages/user/membership.vue` | level/benefits, growth total, progress to the next threshold, growth history |
+| `pages/user/messages.vue` | system message center: unread filter, mark read, mark-all-read, soft delete |
+| `pages/merchant/join.vue` | 商家入驻 multi-step application form (anonymous fill, sign-in gate, draft return) |
+| `pages/merchant/status.vue` | applicant's own application status, rejection reason, re-apply |
+| `locales/<domain>.ts` + `locales-extra.ts` | app-local bilingual strings deep-merged over the shared locales (mall namespaces: shell/home/search/product/cart/checkout/auth/user/stores/marketing/wallet/merchant/membership/messaging) |
 | `pages/seckill.vue`, `collective.vue`, `integral.vue` | flash sale, group buying, points mall |
-| `app.vue` + `components/shell/*` | header/footer shell |
-| `composables/` | session/cart stores, `usePrice` (currency conversion display) |
+| `app.vue` + `components/shell/*` | header/footer shell; `SiteHeader.vue` carries the unread-message badge |
+| `composables/` | session/cart stores, `usePrice` (currency conversion display), `useUnreadMessages` (header badge count) |
 
 Remember: mall is the only app with a mock adapter; every new live domain
 needs mock parity so `NUXT_PUBLIC_LIVE_DOMAINS` rollback keeps working.

docs/code_index/platform.md

@@ -1,8 +1,9 @@
 # Index: Platform (identity, accounts, shops, content, currency, addresses)
 
 Domain design: `docs/domains/platform.md`. Specs: `openspec/specs/auth/`,
-`customer-accounts/`, `store-directory/`, `storefront-content/`, `currency/`,
-`address-book/`, `rbac/`.
+`customer-accounts/`, `wallet/`, `settlement/`, `merchant-onboarding/`,
+`membership/`, `messaging/`, `store-directory/`, `storefront-content/`,
+`currency/`, `address-book/`, `rbac/`.
 
 ## Backend (`apps/api`)
 
@@ -10,7 +11,12 @@ Domain design: `docs/domains/platform.md`. Specs: `openspec/specs/auth/`,
 |---|---|
 | `modules/identity/` | register/login/me; admin user role assignment |
 | `modules/account/` | customer_accounts ledger; credit/debit/freeze/release, `ensure_monetary_account` |
+| `modules/wallet/` | demo recharge, guarded withdrawal freeze + one-time admin review, paginated own fund entries |
+| `modules/settlement/` | idempotent per-shop weekly/monthly statements, commission-rate setting, one-time payout confirmation |
 | `modules/shop/` | shop CRUD/status, profiles, `PUT /shop/profile` merchant self-write |
+| `modules/merchant_onboarding/` | merchant applications (personal/enterprise), guarded review, transactional approval provisioning |
+| `modules/membership/` | member level catalog, growth accrual ledger, one-way level upgrade, derived status |
+| `modules/messaging/` | event-driven system messages, unread/read state, soft delete, unread count |
 | `modules/content/` | four home-content kinds, whole-list replacement |
 | `modules/currency/` | currency registry, rates, `convert` endpoint |
 | `modules/address/` | customer address book |
@@ -18,8 +24,10 @@ Domain design: `docs/domains/platform.md`. Specs: `openspec/specs/auth/`,
 | `src/error.rs` | `ApiError` envelope, `unique_conflict` |
 | `src/money.rs` | `convert_minor` |
 
-Tests: `tests/auth.rs`, `tests/accounts.rs`, `tests/shops.rs`,
-`tests/content.rs`, `tests/addresses.rs`, `tests/catalog.rs` (currency too).
+Tests: `tests/auth.rs`, `tests/accounts.rs`, `tests/wallet.rs`,
+`tests/settlement.rs`, `tests/merchant_applications.rs`, `tests/membership.rs`,
+`tests/messaging.rs`, `tests/shops.rs`, `tests/content.rs`,
+`tests/addresses.rs`, `tests/catalog.rs` (currency too).
 
 ## Frontends
 
@@ -27,4 +35,4 @@ Tests: `tests/auth.rs`, `tests/accounts.rs`, `tests/shops.rs`,
   `layouts/`/`app.vue`, `pages/user/addresses.vue`
 - Shop-admin: `pages/shop-profile.vue`
 - Admin: `pages/users.vue`, `pages/shops.vue`, `pages/content.vue`,
-  `pages/brands.vue`, `pages/currencies.vue`
+  `pages/brands.vue`, `pages/currencies.vue`, `pages/member-levels.vue`

docs/domains/platform.md

@@ -10,8 +10,34 @@ The ledger is the audit trail; balances are never set absolutely. Credits in
 a currency the customer never held lazily create the zero row
 (`ensure_monetary_account`).
 
-Planned on this foundation: wallet top-up/withdrawal and merchant settlement
-(`openspec/changes/add-wallet-settlement`).
+## Wallet (`modules/wallet/`)
+
+Buyer- and shop-owner-facing entry points over the ledger. `GET /wallet` is the
+available/frozen summary in the platform base currency; `GET /wallet/entries`
+pages the caller's own `customer_account_entries` (money kinds only) newest
+first with signed deltas and resulting balances. `POST /wallet/recharges` is a
+**simulated** demo credit (`demo: true` on the payload, no payment provider),
+and `POST /wallet/withdrawals` freezes the requested amount out of available
+balance through the account module's guarded transfer. Platform admins list and
+review pending applications via `/admin/wallet/withdrawals`: approve consumes
+the frozen funds, reject returns them to available, and the
+`pending -> approved|rejected` transition is guarded so a repeat review is a
+409. Every movement pairs with a ledger entry in the same transaction.
+
+## Settlement (`modules/settlement/`)
+
+Per-shop, per-period reconciliation statements generated manually for a closed
+week or month (`/shop/settlement/*` for the own shop, `/admin/settlement/*` for
+the platform). Generation is idempotent per `(shop, period_kind, period_start)`
+— enforced by a unique index — and snapshots the contributing confirmed-received
+orders (`orders.completed_at` inside the period), their gross and completed
+refunds converted into the platform base currency, the platform commission rate
+in integer basis points, and `payable = gross - refunds - commission`, all in
+integer minor units. The platform rate lives in `platform_settings`
+(`settlement.commission_rate_bps`) and only affects statements generated after a
+change. Confirmation is a guarded `pending -> confirmed` transition that credits
+the payable amount to the shop owner's available account with exactly one
+`settlement_payout` ledger entry.
 
 ## Storefront content (`modules/content/`)
 
@@ -34,6 +60,51 @@ Email+password register/login, JWT bearer tokens. `AuthUser` carries
 `require_shop()` for tenant scoping (cross-shop resources return 404).
 `ensure_accounts` runs inside the registration transaction.
 
+## Merchant onboarding (`modules/merchant_onboarding/`)
+
+The B2B entry that replaces manual admin shop creation: an authenticated user
+submits one application as `personal` or `enterprise` (kind-specific entity
+fields, one or more reference categories, contact details, qualification URLs
+only). One live application per user is enforced by service validation plus a
+partial unique index on `(user_id) WHERE status IN ('pending','approved')`, so
+a rejected applicant may re-apply. The review state machine is
+`pending -> approved | rejected` through guarded updates; rejection requires a
+non-empty reason, and both terminal states are immutable (409 on repeat).
+Approval is one transaction — `shop::service::create_in_tx`, a dedicated
+`shop_owner` user via `identity::repo::insert_user`, its zero-balance accounts,
+and the guarded status flip — and returns the generated initial password
+exactly once; any failure rolls the whole provisioning back and leaves the
+application `pending`. Applicants only ever read their own history; platform
+admins list/filter all applications.
+
+## Membership (`modules/membership/`)
+
+Platform-managed `member_levels` (bilingual name and benefits, icon, globally
+unique integer growth threshold) plus an append-only `growth_logs` ledger and
+`users.level`. When the buyer confirms receipt and the order reaches
+`completed`, `membership::service::accrue_for_order` runs inside that
+transaction: it converts the order's realized paid amount (total minus completed
+refunds) into the base currency with `money::convert_minor`, truncates to whole
+units via the base exponent, appends exactly one entry (`ON CONFLICT DO NOTHING`
+on the `(user_id, reference_type, reference_id)` partial unique index), and
+moves `users.level` with a guarded update that only ever raises the threshold.
+Leveling is one-way; the status read re-derives the displayed level against the
+current thresholds so an admin edit is reflected without rewriting members.
+Growth history is own-only and paginated.
+
+## Messaging (`modules/messaging/`)
+
+Per-customer system messages emitted by order events: payment success
+(`order_paid`), shipment dispatch (`order_shipped`), and refund completion
+(`refund_completed`, referenced by the after-sale row and naming the order).
+Each emit is a guarded insert keyed by `(user_id, kind, reference_type,
+reference_id)` inside the transition's transaction, so a retried handler cannot
+duplicate a message and a soft-deleted row still occupies its slot. Messages are
+created `unread`; marking one or all read uses guarded updates that only touch
+`unread` rows, deletion is a soft-delete marker that is idempotent and excludes
+the row from listing and counting, and a dedicated unread-count endpoint feeds
+the mall's top-bar badge.
+
 ## Key files
 
 See `docs/code_index/platform.md`.