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.
This commit is contained in:
2026-09-25 15:25:29 +00:00
parent 772aafa3fb
commit 9904696e76
120 changed files with 14097 additions and 125 deletions
+65
View File
@@ -2,7 +2,9 @@
## Purpose
The platform console for managing users, shops and currencies.
## Requirements
### Requirement: Platform user and shop management
Platform admins SHALL assign user roles (with shop scope), create shops, and suspend/activate shops. Suspended shops' products MUST NOT be purchasable (enforced by API, reflected in UI).
@@ -102,3 +104,66 @@ Platform admins SHALL review a paginated moderation list of all reviews with the
- **WHEN** an authenticated platform admin opens the admin console
- **THEN** a review moderation entry is reachable from the console nav
### Requirement: Withdrawal review and commission configuration
The platform console SHALL list withdrawal applications and approve or reject each pending application through the shared API contract, surfacing review outcomes and conflicts (409 on a repeated review) without silent failure. It SHALL expose the platform commission rate as an integer basis-point setting that admins can read and update.
#### Scenario: reject returns funds
- **WHEN** an admin rejects a pending withdrawal application
- **THEN** the console shows the rejected status and the buyer's wallet reflects the amount back in available balance
#### Scenario: approve deducts frozen funds
- **WHEN** an admin approves a pending withdrawal application
- **THEN** the console shows the approved status and the frozen balance decreases by the requested amount
#### Scenario: set commission rate
- **WHEN** an admin updates the commission rate
- **THEN** settlement statements generated afterwards snapshot the new rate
### Requirement: Settlement statement confirmation
The platform console SHALL list settlement statements across shops with their amount snapshots and statuses, allow manual generation for a shop and closed period, and confirm payout exactly once per statement through the shared API contract, surfacing a 409 on repeated confirmation.
#### Scenario: confirm payout
- **WHEN** an admin confirms a pending statement
- **THEN** the console shows the statement confirmed and the shop owner's ledger records the payout
#### Scenario: manual generation is idempotent
- **WHEN** an admin generates a statement for a shop and period that already has one
- **THEN** the existing statement is shown and no duplicate is created
### Requirement: Merchant application review console
Platform admins SHALL review merchant onboarding applications in a dedicated console entry beside existing platform operations: a status-filtered paginated list and a detail view showing entity kind, entity information, operating categories, contact details, and qualification URL fields. Approving SHALL provision the shop and `shop_owner` account and display the one-time initial credentials exactly once, with copy stating the password cannot be retrieved again. Rejecting SHALL require a reason. Reviewed applications SHALL leave the pending queue immediately.
#### Scenario: review an enterprise application
- **WHEN** a platform admin opens a pending enterprise application
- **THEN** the company entity data, operating categories, contact details, and qualification URLs are visible for review
#### Scenario: approve shows one-time credentials
- **WHEN** a platform admin approves an application
- **THEN** the created shop owner's initial credentials are shown once and the application moves to the approved list
#### Scenario: reject requires a reason
- **WHEN** a platform admin attempts to reject without entering a reason
- **THEN** the action is blocked until a non-empty reason is provided
#### Scenario: entry beside platform operations
- **WHEN** an authenticated platform admin opens the admin console
- **THEN** merchant application review is reachable from the console navigation
### Requirement: Member level management
Platform admins SHALL manage member levels from a dedicated admin console page through the shared API contract: levels listed in growth-threshold order, and create, edit, and delete actions over name, icon, growth threshold, and benefits with both locales editable. Deleting a level in use SHALL surface the API rejection instead of silently succeeding, and member-level management SHALL be reachable from the authenticated console navigation beside existing platform operations.
#### Scenario: manage a member level
- **WHEN** a platform admin creates a level with bilingual name and benefits, an icon, and a growth threshold
- **THEN** it appears in threshold order and is available for automatic leveling
#### Scenario: edit a growth threshold
- **WHEN** a platform admin changes a level's growth threshold to a unique value
- **THEN** the level persists with the new threshold and the bilingual content unchanged
#### Scenario: deleting a level in use fails visibly
- **WHEN** a platform admin deletes a level that customers hold
- **THEN** the console surfaces the rejection and the level and its members remain unchanged
#### Scenario: level management appears in admin navigation
- **WHEN** an authenticated platform admin opens the admin console
- **THEN** member-level management is reachable from the console nav