james
9904696e76
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.
3.5 KiB
Why
Customer accounts and the append-only entry ledger already exist (0010_customer_accounts.sql, the customer-accounts capability), but nothing in the product can reach them: buyers have no wallet surface, withdrawals have no lifecycle, and money moving between buyers, merchants, and the platform leaves no statement. Platform-mediated merchant settlement — confirmed-received orders minus refunds minus a platform commission — is the core B2B2C promise and is currently invisible. This change gives the existing ledger its entry points: a buyer wallet with simulated recharge and withdrawal review, and per-period merchant settlement statements whose confirmed payout is recorded in the ledger.
What Changes
- Add a buyer wallet: available/frozen balance summary, paginated fund entries mapped to the existing ledger, simulated (demo) recharge that directly credits the available account with a ledger entry, and withdrawal applications that move the requested amount from available to frozen through guarded updates.
- Add platform-admin withdrawal review: approve deducts the frozen amount, reject returns it to available balance, each application reviewable exactly once through guarded status transitions.
- Add merchant settlement: manually generated per-period (week/month) reconciliation statements per shop, snapshotted from confirmed-received orders minus completed refunds and a platform-level commission rate, unique per shop and period.
- Add settlement payout confirmation: a platform admin confirms exactly once via a guarded
pending -> confirmedtransition, which records the payout in the ledger of the shop owner's account. - Surface everything through
@vmall/shared: a mall wallet page, admin withdrawal review / commission configuration / statement confirmation, and shop-admin statement list/detail plus shop-account withdrawal.
Capabilities
New Capabilities
wallet: Demo recharge, guarded withdrawal freeze and one-time review lifecycle, and paginated fund entries over the existing customer-account ledger.settlement: Idempotent per-shop periodic settlement statements with immutable amount snapshots, a platform-level commission rate, and apending -> confirmedpayout state machine.
Modified Capabilities
frontend-mall: A buyer-center wallet page (balance, fund entries, demo recharge, withdrawal request) driven by the shared wallet contract with fixed-adapter fallback.frontend-admin: Withdrawal review queue, platform commission-rate configuration, and settlement statement generation and confirmation.frontend-shop-admin: Shop-scoped settlement statement list/detail with manual generation, and shop-account withdrawal requests.
Non-goals
Real payment or withdrawal channels (bank cards, WeChat/Alipay payouts), WeChat profit-sharing (分账) APIs, invoice/tax linkage with settlement, automatic settlement batch timers (statements are generated manually), multi-currency wallet balances beyond the account's currency, withdrawal fee tiers, and per-shop commission rate overrides are excluded.
Impact
Adds migrations for wallet recharge/withdrawal records, settlement statements, and the platform commission setting; new wallet and settlement Rust modules built on the existing customer-accounts primitives; @vmall/shared wallet and settlement contracts; a wallet mall domain with mock-adapter parity and LIVE_PICKS wiring; and wallet, review, and settlement pages across the mall, admin, and shop-admin frontends. Settlement generation consumes the refund rows introduced by add-aftersale-refunds.