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.