31 lines
3.5 KiB
Markdown
31 lines
3.5 KiB
Markdown
## 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 -> confirmed` transition, 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 a `pending -> confirmed` payout 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`.
|