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:
@@ -0,0 +1,45 @@
|
||||
-- Wallet entry points over the existing customer-account ledger:
|
||||
-- simulated recharge records and withdrawal applications awaiting review.
|
||||
-- Balances themselves stay in customer_accounts; these tables are the
|
||||
-- business records whose lifecycle drives ledger entries.
|
||||
|
||||
CREATE TYPE wallet_recharge_status AS ENUM ('credited', 'failed');
|
||||
|
||||
CREATE TABLE wallet_recharges (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
|
||||
currency CHAR(3) NOT NULL REFERENCES currencies (code),
|
||||
amount_minor BIGINT NOT NULL CHECK (amount_minor > 0),
|
||||
status wallet_recharge_status NOT NULL DEFAULT 'credited',
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE INDEX wallet_recharges_user_idx
|
||||
ON wallet_recharges (user_id, created_at DESC);
|
||||
|
||||
CREATE TYPE wallet_withdrawal_status AS ENUM ('pending', 'approved', 'rejected');
|
||||
|
||||
CREATE TABLE wallet_withdrawals (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
|
||||
currency CHAR(3) NOT NULL REFERENCES currencies (code),
|
||||
amount_minor BIGINT NOT NULL CHECK (amount_minor > 0),
|
||||
-- Free-form payout destination captured at application time.
|
||||
account_details JSONB NOT NULL DEFAULT '{}'::jsonb,
|
||||
status wallet_withdrawal_status NOT NULL DEFAULT 'pending',
|
||||
reviewed_by UUID REFERENCES users (id),
|
||||
reviewed_at TIMESTAMPTZ,
|
||||
review_note TEXT,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
-- A reviewed row always records who and when; a pending row never does.
|
||||
CONSTRAINT wallet_withdrawals_review_consistent CHECK (
|
||||
(status = 'pending' AND reviewed_by IS NULL AND reviewed_at IS NULL)
|
||||
OR (status <> 'pending' AND reviewed_by IS NOT NULL AND reviewed_at IS NOT NULL)
|
||||
)
|
||||
);
|
||||
|
||||
CREATE INDEX wallet_withdrawals_user_idx
|
||||
ON wallet_withdrawals (user_id, created_at DESC);
|
||||
CREATE INDEX wallet_withdrawals_status_idx
|
||||
ON wallet_withdrawals (status, created_at DESC);
|
||||
@@ -0,0 +1,62 @@
|
||||
-- Platform-mediated merchant settlement: per-shop, per-period statements
|
||||
-- snapshotted from confirmed-received orders minus completed refunds minus a
|
||||
-- platform commission. Amounts are integer minor units in the platform base
|
||||
-- currency; the rate is integer basis points and lives in platform settings.
|
||||
|
||||
-- Settlement attributes an order to the period in which it became
|
||||
-- confirmed-received. Refunds bump orders.updated_at, so that column cannot
|
||||
-- stand in for the completion instant.
|
||||
ALTER TABLE orders ADD COLUMN completed_at TIMESTAMPTZ;
|
||||
UPDATE orders SET completed_at = updated_at
|
||||
WHERE status = 'completed' AND completed_at IS NULL;
|
||||
CREATE INDEX orders_shop_completed_idx
|
||||
ON orders (shop_id, completed_at) WHERE status = 'completed';
|
||||
|
||||
CREATE TABLE platform_settings (
|
||||
key TEXT PRIMARY KEY,
|
||||
value TEXT NOT NULL,
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
INSERT INTO platform_settings (key, value)
|
||||
VALUES ('settlement.commission_rate_bps', '500')
|
||||
ON CONFLICT (key) DO NOTHING;
|
||||
|
||||
CREATE TYPE settlement_period_kind AS ENUM ('week', 'month');
|
||||
CREATE TYPE settlement_status AS ENUM ('pending', 'confirmed');
|
||||
|
||||
CREATE TABLE settlement_statements (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
shop_id UUID NOT NULL REFERENCES shops (id) ON DELETE CASCADE,
|
||||
-- Statement totals are converted into and snapshotted in this currency.
|
||||
currency CHAR(3) NOT NULL REFERENCES currencies (code),
|
||||
period_kind settlement_period_kind NOT NULL,
|
||||
period_start DATE NOT NULL,
|
||||
period_end DATE NOT NULL,
|
||||
order_count INT NOT NULL DEFAULT 0 CHECK (order_count >= 0),
|
||||
gross_minor BIGINT NOT NULL DEFAULT 0 CHECK (gross_minor >= 0),
|
||||
refund_minor BIGINT NOT NULL DEFAULT 0 CHECK (refund_minor >= 0),
|
||||
commission_rate_bps INT NOT NULL
|
||||
CHECK (commission_rate_bps >= 0 AND commission_rate_bps <= 10000),
|
||||
commission_minor BIGINT NOT NULL DEFAULT 0 CHECK (commission_minor >= 0),
|
||||
payable_minor BIGINT NOT NULL DEFAULT 0 CHECK (payable_minor >= 0),
|
||||
status settlement_status NOT NULL DEFAULT 'pending',
|
||||
generated_by UUID REFERENCES users (id),
|
||||
confirmed_by UUID REFERENCES users (id),
|
||||
confirmed_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CONSTRAINT settlement_statements_period CHECK (period_end >= period_start),
|
||||
CONSTRAINT settlement_statements_confirmed_consistent CHECK (
|
||||
(status = 'pending' AND confirmed_by IS NULL AND confirmed_at IS NULL)
|
||||
OR (status = 'confirmed' AND confirmed_by IS NOT NULL AND confirmed_at IS NOT NULL)
|
||||
)
|
||||
);
|
||||
|
||||
-- At most one statement per shop, period kind, and period start.
|
||||
CREATE UNIQUE INDEX settlement_statements_period_idx
|
||||
ON settlement_statements (shop_id, period_kind, period_start);
|
||||
CREATE INDEX settlement_statements_shop_idx
|
||||
ON settlement_statements (shop_id, created_at DESC);
|
||||
CREATE INDEX settlement_statements_status_idx
|
||||
ON settlement_statements (status, created_at DESC);
|
||||
@@ -0,0 +1,69 @@
|
||||
-- Merchant onboarding: a prospective seller (personal 个人 or enterprise 企业)
|
||||
-- applies once, a platform admin reviews it, and approval provisions the shop
|
||||
-- and its dedicated shop_owner account in one transaction.
|
||||
|
||||
CREATE TYPE merchant_entity_type AS ENUM ('personal', 'enterprise');
|
||||
CREATE TYPE merchant_application_status AS ENUM ('pending', 'approved', 'rejected');
|
||||
|
||||
CREATE TABLE merchant_applications (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
|
||||
entity_type merchant_entity_type NOT NULL,
|
||||
-- Personal-kind entity information.
|
||||
real_name TEXT,
|
||||
-- Enterprise-kind entity information.
|
||||
company_name TEXT,
|
||||
business_license_no TEXT,
|
||||
-- Operating categories, one or more rows of the reference category tree.
|
||||
category_ids UUID[] NOT NULL DEFAULT '{}',
|
||||
-- Contact details, shared by both kinds.
|
||||
contact_name TEXT NOT NULL,
|
||||
contact_phone TEXT NOT NULL,
|
||||
contact_email TEXT NOT NULL,
|
||||
contact_address TEXT,
|
||||
-- Qualification materials are URLs only; no file storage in this MVP.
|
||||
identity_document_url TEXT,
|
||||
business_license_url TEXT,
|
||||
extra_materials JSONB NOT NULL DEFAULT '[]'::jsonb,
|
||||
status merchant_application_status NOT NULL DEFAULT 'pending',
|
||||
rejection_reason TEXT,
|
||||
reviewed_by UUID REFERENCES users (id),
|
||||
reviewed_at TIMESTAMPTZ,
|
||||
-- Shop created by approval; null until then.
|
||||
created_shop_id UUID REFERENCES shops (id),
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
-- Each kind carries its own required entity + qualification fields.
|
||||
CONSTRAINT merchant_applications_kind_fields CHECK (
|
||||
(
|
||||
entity_type = 'personal'
|
||||
AND real_name IS NOT NULL AND btrim(real_name) <> ''
|
||||
AND identity_document_url IS NOT NULL AND btrim(identity_document_url) <> ''
|
||||
)
|
||||
OR (
|
||||
entity_type = 'enterprise'
|
||||
AND company_name IS NOT NULL AND btrim(company_name) <> ''
|
||||
AND business_license_url IS NOT NULL AND btrim(business_license_url) <> ''
|
||||
)
|
||||
),
|
||||
-- A pending row is unreviewed; terminal rows record who and when, and a
|
||||
-- rejection always carries its reason.
|
||||
CONSTRAINT merchant_applications_review_consistent CHECK (
|
||||
(status = 'pending' AND reviewed_by IS NULL AND reviewed_at IS NULL
|
||||
AND rejection_reason IS NULL AND created_shop_id IS NULL)
|
||||
OR (status = 'approved' AND reviewed_by IS NOT NULL AND reviewed_at IS NOT NULL
|
||||
AND rejection_reason IS NULL AND created_shop_id IS NOT NULL)
|
||||
OR (status = 'rejected' AND reviewed_by IS NOT NULL AND reviewed_at IS NOT NULL
|
||||
AND rejection_reason IS NOT NULL AND btrim(rejection_reason) <> ''
|
||||
AND created_shop_id IS NULL)
|
||||
),
|
||||
CONSTRAINT merchant_applications_categories CHECK (cardinality(category_ids) >= 1)
|
||||
);
|
||||
|
||||
-- At most one live application per user; rejected rows are free to retry.
|
||||
CREATE UNIQUE INDEX merchant_applications_active_idx
|
||||
ON merchant_applications (user_id) WHERE status IN ('pending', 'approved');
|
||||
CREATE INDEX merchant_applications_user_idx
|
||||
ON merchant_applications (user_id, created_at DESC);
|
||||
CREATE INDEX merchant_applications_status_idx
|
||||
ON merchant_applications (status, created_at DESC);
|
||||
@@ -0,0 +1,6 @@
|
||||
-- The "Become a Seller / 入驻商家" storefront quick link now lands on the
|
||||
-- merchant onboarding form instead of the stores directory.
|
||||
UPDATE quick_links
|
||||
SET url = '/merchant/join'
|
||||
WHERE url = '/stores'
|
||||
AND label ->> 'en' = 'Become a Seller';
|
||||
@@ -0,0 +1,73 @@
|
||||
-- Membership: platform-managed levels, an append-only growth ledger, and the
|
||||
-- customer's current level on `users`. Messaging: per-customer system messages
|
||||
-- emitted by order/shipment/refund events with unread state and soft deletion.
|
||||
|
||||
CREATE TABLE member_levels (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
name JSONB NOT NULL,
|
||||
icon TEXT NOT NULL,
|
||||
growth_threshold BIGINT NOT NULL CHECK (growth_threshold >= 0),
|
||||
benefits JSONB NOT NULL,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CONSTRAINT member_levels_icon CHECK (btrim(icon) <> '')
|
||||
);
|
||||
|
||||
-- Thresholds are unique; level order follows the threshold.
|
||||
CREATE UNIQUE INDEX member_levels_threshold_idx ON member_levels (growth_threshold);
|
||||
|
||||
ALTER TABLE users ADD COLUMN level UUID REFERENCES member_levels (id);
|
||||
CREATE INDEX users_level_idx ON users (level);
|
||||
|
||||
CREATE TABLE growth_logs (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
|
||||
-- Growth value in whole base-currency units; 0 only for sub-unit orders.
|
||||
delta BIGINT NOT NULL CHECK (delta >= 0),
|
||||
growth_total BIGINT NOT NULL CHECK (growth_total >= 0),
|
||||
reason TEXT NOT NULL,
|
||||
reference_type TEXT,
|
||||
reference_id UUID,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
-- One accrual per user and referenced order, so a retried completion is a no-op.
|
||||
CREATE UNIQUE INDEX growth_logs_reference_idx
|
||||
ON growth_logs (user_id, reference_type, reference_id)
|
||||
WHERE reference_id IS NOT NULL;
|
||||
CREATE INDEX growth_logs_user_idx
|
||||
ON growth_logs (user_id, created_at DESC, id DESC);
|
||||
|
||||
CREATE TYPE message_kind AS ENUM ('order_paid', 'order_shipped', 'refund_completed');
|
||||
CREATE TYPE message_status AS ENUM ('unread', 'read');
|
||||
|
||||
CREATE TABLE messages (
|
||||
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||
user_id UUID NOT NULL REFERENCES users (id) ON DELETE CASCADE,
|
||||
kind message_kind NOT NULL,
|
||||
title JSONB NOT NULL,
|
||||
body JSONB NOT NULL,
|
||||
reference_type TEXT,
|
||||
reference_id UUID,
|
||||
status message_status NOT NULL DEFAULT 'unread',
|
||||
read_at TIMESTAMPTZ,
|
||||
deleted_at TIMESTAMPTZ,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
CONSTRAINT messages_read_consistent CHECK (
|
||||
(status = 'unread' AND read_at IS NULL)
|
||||
OR (status = 'read' AND read_at IS NOT NULL)
|
||||
)
|
||||
);
|
||||
|
||||
-- One message per customer, kind, and reference: re-running an event handler
|
||||
-- conflicts instead of duplicating. Soft-deleted rows still occupy the slot so
|
||||
-- a re-run cannot resurrect a deleted message as a new one.
|
||||
CREATE UNIQUE INDEX messages_event_idx
|
||||
ON messages (user_id, kind, reference_type, reference_id)
|
||||
WHERE reference_id IS NOT NULL;
|
||||
CREATE INDEX messages_user_idx
|
||||
ON messages (user_id, created_at DESC, id DESC)
|
||||
WHERE deleted_at IS NULL;
|
||||
CREATE INDEX messages_unread_idx
|
||||
ON messages (user_id)
|
||||
WHERE deleted_at IS NULL AND status = 'unread';
|
||||
Reference in New Issue
Block a user